| Chapter 12. Import/Export | ||
|---|---|---|
|
 |
|
| Chapter 12. Import/Export | ||
|---|---|---|
|
|
|
|
Table of Contents
Klaros-Testmanagement provides several interfaces to import data from other tools and export its data into several formats.
User authentication is mandatory for all import operations. The user role required varies with the type of data being imported. For importing test results, the Tester role is sufficient as for requirements and test cases the Manager role is required.
![[Important]](images/important.png) |
LDAP Authentication |
|---|---|
| .
If the setting Login default is enabled in the LDAP configuration, then authentication is done exclusively via the LDAP directory. Local authentication information is always ignored in this case. |
Klaros-Testmanagement allows importing of test cases from Excel sheets structured in a predefined format which will be further detailed in Section 12.1.1, “Import Format”.
In addition to the standard fields provided for test cases, users of the Klaros-Testmanagement Enterprise Edition are also able to import data for user-defined fields. For this it is necessary to prepare the project according to what is listed in Section 12.1.2, “Prerequisites”.
The import interface consists of a simple REST interface which can be accessed by command line tools as well as custom applications. This is further detailed in Section 12.1.3, “Execution”.
The Excel sheet used to import test cases has to follow this strict format:
Each test case is located on a separate sheet.
Each sheet is divided into three sections: general properties, test case steps and custom properties.
The fields A:1 to A:22 are reserved for the standard attributes of a test case. The corresponding values are entered in the fields B:1 to B:22. It is not mandatory to fill all fields.
Column G is for the names of any number of user-defined properties. In column H the corresponding values are entered.
The Step field in cell A:25 must remain.
Changing or deleting the A:25 field will cause the import of this table to be rejected.
From here the definition of the test steps begins:
Column A for the test step number,
Column B for the action,
Column C for the precondition,
Column D for the postcondition and
Column E for the expected result.
The table below lists the cell coordinates for the general test case properties. The test case ID does not have to be specified. The ID is generated during the import. None of these values are mandatory. Some fields can take only predefined values which are listed there.
|
Coordinate |
Value |
|---|---|
|
B2 |
Name |
|
B3 |
Revision (only used in export) |
|
B5 |
Description |
|
B6 |
Precondition |
|
B7 |
Postcondition |
|
B8 |
Expected Result |
|
B10 |
Note |
|
B11 |
Area ( |
|
B12 |
Design Method ( |
|
B13 |
Variety ( |
|
B14 |
Execution ( |
|
B15 |
Priority ( |
|
B16 |
State ( |
|
B17 |
Team |
|
B18 |
Level ( |
|
B19 |
Document Base |
|
B20 |
Dependency |
|
B21 |
Evaluation |
|
B22 |
Traceability |
Table 12.1. General Property Coordinates
Test cases may contain a variable number of test steps. These are listed one per row starting from cell A:26 downwards. The import parser will stop reading steps once it encounters an empty step number.
|
Coordinate |
Value |
|---|---|
|
A26 (ff) |
Step Number |
|
B26 (ff) |
Action |
|
C26 (ff) |
Precondition |
|
D26 (ff) |
Postcondition |
|
E26 (ff) |
Expected Result |
Table 12.2. Test Step Coordinates
Only available in Klaros-Testmanagement Enterprise Edition
Test cases may contain custom properties. These may be listed as name/value pairs starting from cell G1 downwards.
For the import to succeed, the names of the listed properties must match with user defined properties defined for the project targeted by the import.
The value field for enumeration properties must exactly match the name of the enumeration property value definition to be parsed.
If an empty name cell is found, processing stops.
|
Coordinate |
Value |
|---|---|
|
G1 (ff) |
Property name |
|
H1 (ff) |
Property value |
Table 12.3. Custom Property Coordinates
To import Excel based test cases the following prerequisites have to be met:
The file that is going to be imported has to be XLS or XLSX format.
The project that should contain the imported test cases has to be already created.
If user defined properties (only available in Klaros-Testmanagement Enterprise Edition) are to be imported they have to be created for the project prior to starting the import process.
To import Excel-based test cases a REST interface is available which allows you to upload your data from the command-line or other applications.
The following example shows how to import an Excel sheet containing test cases into the project named P00001 using the curl command line application. Curl should be available in every Linux distribution and as part of the Cygwin http://www.cygwin.com/ distribution or as a command line tool from http://curl.haxx.se/download.html for the Microsoft Windows operating system family.
|
Incompatible Windows Powershell curl Alias |
|---|---|
|
Windows Powershell also defines an alias named curl which also can be used for this purpose but takes a completely different set of arguments. If you prefer to use the Linux compatible curl executable under Powershell, use curl.exe instead of curl. |
curl -v -T TestCases.xls "<klaros-app-url>/seam/resource/rest/import/testcase/xls?config=P00001\ &username=user&password=secret"
Example 12.1. Excel Test Case Import via Command Line
![[Note]](images/note.png) |
ID Format |
|---|---|
|
All objects which are referenced during import (like projects or test cases) contain five digits in their id. For example, P00001 is a valid project ID, while P0001 and P000001 are not. |
Klaros-Testmanagement allows importing of test cases from XML Files. The import process will always create new instances of the supplied test cases for each invocation.
The format of the XML file is described in Appendix C, Test Case Import File Specification. The XML schema is available at the following URL: https://www.klaros-testmanagement.com/files/schema/klaros-testcases-1.0.xsd.
To import XML based test cases the following prerequisites have to be met:
The file that is going to be imported has to in XML format.
The project that should contain the imported test cases has to be already created.
If user defined properties are to be imported, they have to be created in the project prior to starting the import process.
To import XML-based test cases a REST interface is available which allows you to upload your data from the command-line or other applications.
The following example shows how to import an XML file containing test cases into the project named P00001 using the curl command line application. Curl should be available in every decent Linux distribution and as part of the Cygwin http://www.cygwin.com/ distribution or as a command line tool from http://curl.haxx.se/download.html for the Microsoft Windows operating system family.
curl -v -T TestCases.xml "<klaros-app-url>/seam/resource/rest/import/testcase/xml?config=P00001\ &username=user&password=secret"
Example 12.2. XML Test Case Import via Command Line
In order to correctly import requirements from Excel spreadsheets, the data must exist in a specified format. This format is described in detail in the following section Section 12.1.1, “Import Format”.
In addition to the standard fields provided for requirements, users of the Klaros-Testmanagement Enterprise Edition are also able to import data for user-defined fields. For this it is necessary to prepare the project accordingly. You can find more information about this at Section 12.1.2, “Prerequisites”.
The import interface consists of a simple REST interface which can be accessed by command line tools as well as custom applications. This is further detailed in Section 12.1.3, “Execution”.
The Excel sheet used to import requirements has to follow this strict format:
Each requirement is located on a separate sheet.
Each sheet is divided into two sections: general properties and custom properties.
The fields A:1 to A:9 are reserved for the standard attributes of a requirement. The corresponding values are entered in the fields B:1 to B:9. It is not mandatory to fill all fields.
Column G is for the names of any number of user-defined properties. In column H the corresponding values are entered.
The table below lists the cell coordinates for the general requirement properties. None of these values are mandatory. Some fields can take only predefined values which are listed there.
|
Coordinate |
Value |
|---|---|
|
B1 |
ID (only used in export) |
|
B2 |
Name |
|
B3 |
Revision (only used in export) |
|
B5 |
Summary |
|
B6 |
Description |
|
B8 |
Priority
( |
|
B9 |
State
( |
Table 12.4. General Property Coordinates
Requirements may contain custom properties. These may be listed as name/value pairs starting from cell G1 downwards.
For the import to succeed, the names of the listed properties must match with user defined properties defined for the project targeted by the import.
The name in the name column must exactly match the name of a user defined property for a value to be parsed correctly. The parsing stops once an empty name cell has been found. The value field for enumeration properties must exactly match the name of the enumeration property value definition to be parsed.
|
Coordinate |
Value |
|---|---|
|
G1 (ff) |
Property name |
|
H1 (ff) |
Property value |
Table 12.5. Custom Property Coordinates
To import Excel based requirements the following prerequisites have to be met:
The file that is going to be imported has to be in XLS or XLSX format.
The project that should contain the imported requirements has to be already created.
If user defined properties (only available in Klaros-Testmanagement Enterprise Edition) are to be imported they have to be created for the project prior to starting the import process.
To import Excel-based requirements a REST interface is available which allows you to upload your data from the command-line or other applications.
The following example shows how to import an Excel sheet containing requirements into the project named P00001 using the curl command line application. curl is available in almost any Linux distribution and for the Microsoft Windows operating system family as part of the Cygwin http://www.cygwin.com/ distribution or as a command line tool from http://curl.haxx.se/download.html.
curl -v -T Requirements.xls "<klaros-app-url>/seam/resource/rest/import/requirement/xls?config=P00001\ &username=user&password=secret"
Example 12.3. Excel Requirement Import via Command Line
Klaros-Testmanagement allows to both import and synchronize requirements from XML Files.
An import is limited to a one-time action that always creates new instances of the delivered requirements. Synchronization, on the other hand, allows updating existing requirements with the content of the XML file and creating new revisions of them as needed.
The format of the XML file is described in Appendix D, Requirement Import File Specification. The XML schema is available at the following URL: https://www.klaros-testmanagement.com/files/schema/klaros-requirements-1.0.xsd.
To import XML based test cases the following prerequisites have to be met:
The file that is going to be imported has to be in *.XML format.
The project that should contain the imported requirement has to be already created.
If user defined properties are to be imported, they have to be created in the project prior to starting the import process.
If user defined properties are to be imported, they have to be created in the project prior to starting the import process.
To import XML-based requirements a REST interface is available which allows you to upload your data from the command-line or other applications.
The following example shows how to import an XML file containing requirements into the project named P00001 using the curl command line application. curl is available in almost any Linux distribution and for the Microsoft Windows operating system family as part of the Cygwin http://www.cygwin.com/ distribution or as a command line tool from http://curl.haxx.se/download.html.
curl -v -T Requirements.xml "<klaros-app-url>/seam/resource/rest/import/requirement/xml?config=P00001\ &username=user&password=secret"
Example 12.4. XML Requirement Import via Command Line
To synchronize XML-based requirements a different REST interface is available
(ending with /sync/requirement/xml). It understands the same import
format as defined for importing requirements but requires additional elements to be present
for correct operation.
In contrast to an import a synchronization action is intended to update the set of requirements stored in Klaros-Testmanagement from arbitrary external applications on a regular basis.
The synchronization supports creating and updating as well as revisioning of requirements. Changes to the requirements will be reflected in the Klaros-Testmanagement database on a per-field basis for each synchronization action.
![[Caution]](images/caution.png) |
Synchronization Overrides Local Changes! |
|---|---|
|
Be aware that all data received via synchronization will overwrite any changes made to the requirements stored in Klaros-Testmanagement. |
![[Tip]](images/tip.png) |
externalId
|
|---|---|
|
Supplying the |
|
externalRevision
|
|---|---|
|
Supplying the |
The following example shows how to synchronize an XML file containing requirements into the project named P00001 using the curl command line application. curl is available in almost any Linux distribution and for the Microsoft Windows operating system family as part of the Cygwin http://www.cygwin.com/ distribution or as a command line tool from http://curl.haxx.se/download.html.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <r:container xmlns:r="http://klaros-testmanagement.com/export-requirement-1.0"> <r:requirements> <r:requirement> <r:attributes/> <r:externalId>RTM-00001</r:externalId> <r:externalRevision>1.0</r:externalRevision> <r:priority>MEDIUM</r:priority> <r:shortname>Remote-controlled door panels / unlocking</r:shortname> <r:summary>Doors must me remote controllable.</r:summary> </r:requirement> </r:requirements> </r:container>
Example 12.5. XML Requirement Synchronization via Command Line
curl -v -T Requirements.xml "<klaros-app-url>/seam/resource/rest/sync/requirement/xml?config=P00001\ &username=user&password=secret"
Example 12.6. XML Requirement Import via Command Line
Test automation tools typically generate test results in file form. These files can be imported via a REST interface and automatically converted into test results.
To import test results the following prerequisites have to be met:
The project, iteration, test environment and system under test that should contain the imported test case or test suite results have to be created.
The default URL of the import interface is located at
http://localhost:18080/klaros-web/seam/resource/rest/importer.
The content is transferred via an HTTP PUT request using the above URL and various URL query parameters.
|
The <klaros-app-url> Term
|
|---|---|
|
The |
The following parameters are supported:
|
config |
The ID of the project to import the results into (e.g. P0001). |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
iteration |
The ID of the iteration to relate the results to (e.g. ITR00001). This parameter is optional. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
env |
The ID of the test environment in which the tests have been run (e.g. ENV00001). Please make sure that this test environment already exists in the project before starting the import. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
sut |
The ID of the system under test in which the tests have been run (e.g. SUT00001). Please make sure that this system under test already exists in the project before starting the import. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
type |
The type of the import format. The following types are supported:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
job |
The optional ID of a job this test run should be assigned to (e.g. JOB00001). If given, the job must already exist in the project before starting the import. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
time |
The time of the test execution. Please make sure the fixed format for the time is |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
createTestSuiteResults |
If set to |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
autoCreateTestCases |
If set to |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
username |
The username for the import. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
password |
The password for the import. |
A complete example for a QF-Test import URL would look like this:
http://localhost:18080/klaros-web/seam/resource/rest/importer?\ config=P00001&env=ENV00001&sut=SUT00001&type=qftest&time=01.03.2011_12:00&username=me&password=secret
Example 12.7. QF-Test import URL sample
The result file is contained in the HTTP request body.
The curl command line tool can be used on Linux or Windows/Cygwin to trigger an import in a single command line.
curl -v -H "Content-Type: text/xml" -T <test result file> \ "<klaros-app-url>/seam/resource/rest/importer?config=P00001&env=ENV00001&sut=SUT00001&type=junit\ &time=23.05.2011_14:55"
Example 12.8. Curl Command Line Example
|
Incompatible Windows Powershell curl alias |
|---|---|
|
Windows Powershell also defines an alias named curl which also can be used for this purpose but takes a completely different set of arguments. If you prefer to use the Linux compatible curl executable under Powershell, use curl.exe instead of curl. |
curl -Method put -InFile <test result file> -Uri \ "<klaros-app-url>/seam/resource/rest/importer?config=P00001&env=ENV00001&sut=SUT00001&type=junit\ &time=23.05.2011_14:55"
Example 12.9. Powershell Curl Alias Command Line Example
This plugin integrates a continuous integration server with Klaros-Testmanagement by publishing the test results of a Jenkins build to the Klaros-Testmanagement application. The test results will be stored in the Klaros-Testmanagement database for further evaluation and reporting purposes. You can find the installation and configuration guide for the plugin in the Jenkins GitHub page.
Only available in Klaros-Testmanagement Enterprise Edition
With Klaros-Testmanagement it is possible to export the content of all tables to an Excel file. The current filter and sort settings will be considered.
To move data between different database installations, or to selectively import data, Klaros-Testmanagement provides the functionality to import and export database content via XML files. Section 10.6, “Backup” explains the import and export functionality in detail.
Klaros-Testmanagement Enterprise Edition contains a REST-based interface that grant access to back up files of single projects. The following URI for example returns the backup xml file of the project P00004: http://{host}:{port}/klaros-web/seam/resource/rest/io/backup/project/P00004.
|
Note |
|---|---|
|
For more information on how to access REST-based interfaces, see Chapter 13, The Remote API. |
|
|
|
|
| 11.5. Creating a Chart |  |
Chapter 13. The Remote API |
