Configuring DevOps Test Integrations and APIs Agent as an IBM® Engineering Test Management adapter

HCL DevOps Test Integrations and APIs Agent (Test Integrations and APIs Agent) can be configured as an Engineering Test Management adapter to enable remote test runs.

Procedure

The agent must be provided with the Engineering Test Management server configuration information, similar to the details provided in HCL DevOps Test Integrations and APIs (Test Integrations and APIs).

The configuration can be modified in the Agent.config file. If you have installed Test Integrations and APIs Agent, then modify the Agent.config file in C:\Program Files\HCL\DevOpsTestAPIAgent/config. If you only installed Test Integrations and APIs then modify the Agent.config file in C:\Program Files\HCL\DevOpsTestAPI/config. The configuration file is an XML file that contains an empty or default configuration that can be changed to match the Test Integrations and APIs and Engineering Test Management installation environment.

Note: By default, the Engineering Test Management adapter functionality is disabled and must be configured before it can be used.

The Engineering Test Management adapter configuration is contained within the <rqm> element in the configuration file. The <rqm> element has the following attributes:

enabled: Set this attribute to true or false to enable or disable the adapter functionality without having to change any other part of the configuration.
authType: Set this attribute to configure the authentication method to use. Valid values are as follows: BASIC, KERBEROS, SMARTCARD, and SSLCERT.

The default adapter configuration is as follows:

<!-- authType valid values: BASIC, KERBEROS, SMARTCARD, SSLCERT -->
<rqm enabled="true" authType="BASIC">
<!-- RQM endpoint is usually '/qm' but check with your RQM or ETM Server Administrator -->
<url value="https://localhost:9443/qm" />
<rqmproject value="" />
<ghtprojectbaselocation value="" />
<rqmAdapterId value="MyFixedGHTesterId" />

<!-- Values for authType="BASIC" -->
<username value="admin" />
<password value="admin" />

<!-- Values for authType="KERBEROS" -->
<kerberosConfigPath value="" />

<!-- Values for authType="SMARTCARD" -->
<smartcardAlias value=""/>

<!-- Values for authType="SSLCERT" -->
<sslCertKeystorePath value="C:\SSL\cladmin-cert2.p12"/>
<sslCertKeystorePassword value="cladmin"/>

<!-- Setting keepProjectOpen to false will make Agent re-open the project for every test. 
This may adversely affect RQM Suite performance. Default:true -->
<!-- <keepProjectOpen value="false" /> -->
<!-- Setting idleTimeout determines how long the Agent will keep a project open for further 
work. Default:60-->
<!-- <idleTimeout value="60" /> -->
</rqm>

Note: To support multiple Engineering Test Management projects, you can add multiple <rqm> sections to the configuration file. You can do this by either specifying a separate ghtprojectbaselocation for each Engineering Test Management project or you must ensure that a Test Integrations and APIs project is only used from one Engineering Test Management project.

After the Agent configuration file is modified and saved, run the Agent to connect it to Engineering Test Management as an adapter.

The required configuration values can be modified as follows:

Table 1. Required configuration parameters for the Agent
Parameter	Description
authType	The authentication method to use the for the Agent configuration, which could be any of the following: BASIC, KERBEROS, SMARTCARD, and SSLCERT. Note: The SMARTCARD authentication is supported only on Windows.
username Note: Applies to the BASIC authentication method.	The ID of a Engineering Test Management user to be used by the Agent or adapter. This user ID requires either of the following Client Access Licenses, which can be assigned within Engineering Test Management: Engineering Test Management - Connector Engineering Test Management - Quality Professional The user must also belong to the JazzUsers group under Repository Permissions.
password Note: Applies to the BASIC authentication method.	The password for the user ID entered in the Username field. If the password contains any of the following characters, you must replace it with its equivalent HTML code or entity name: < (less than), > (greater than), & (ampersand), ' (apostrophe), and " (double quotation mark). For example, represent "&" as "&" or "&#38". Note: To use an encrypted password in the Agent.config file you can run the `EncryptPassword` program supplied with Test Integrations and APIs. Run the program from a command window, passing in the password and the encrypted password is generated. Copy and paste the encrypted password into the password element in the Agent.config file.
url	The base URL of the Engineering Test Management server (for example, `https://server_name:9443/qm`). This is the public URI configured for the Quality Management application. The path of the URL that is to be used is shown in the Application Administration list on the Jazz Team Server Home page, which is accessible from the Administration menu on the web interface. For example, if the Jazz Team Server Home is `https://server_name:9443/jazz/admin` and lists Quality Management (/qm), then the URL to use is `https://server_name:9443/qm`.
rqmProject	The Engineering Test Management project to which the configured Agent connects. The value that you enter for this parameter is displayed both as part of the Engineering Test Management server URL and on the Engineering Test Management web interface pages. If the project name ends with (Quality Management), then it must be included in the project name in the Agent.config file.
ghtProjectBaseLocation	The base location of your Test Integrations and APIs projects. This is the directory that contains the projects that you use for running tests, such as C:\DevOpsTestAPIProjects. For Engineering Test Management, you must manually copy your projects from your Test Integrations and APIs server to your Agent machine. Copy your projects to the folder specified in ghtProjectBaseLocation. The project name is appended to the path to locate it, so project names must match their folder names. For example, copy the MyProject directory to C:\DevOpsTestAPIProjects. This process creates the MyProject subfolder, which contains the MyProject.ghp project file and its associated files.
rqmAdapterId	A unique identifier for the current instance of the Agent/adapter. Each running instance must supply a unique identifier.
kerberosConfigPath Note: Applies to KERBEROS authentication method.	The absolute path to the Kerberos configuration file. For example, `C:\Windows\krb5.ini`.
smartcardAlias Note: Applies to the SMARTCARD authentication method.	An alias for the smart card certificate.
sslCertKeystorePath Note: Applies to the SSLCERT authentication method.	The absolute path to the SSL certificate keystore. For example, `C:\work\certs\cert.p12`.
sslCertKeystorePassword Note: Applies to the SSLCERT authentication method.	The password for the SSL certificate keystore. For example, `#com.xyz.1!eedc6A5240EC21137E1212994AC0446CE349`. You can encrypt this value by using the EncryptPassword.exe located in the Agent installation folder or retain it as plain text.

In addition to the required configuration parameters, the following optional parameters can be specified:

Table 2. Optional configuration parameters for the Agent
Parameter	Description	Default Value (if not supplied)
rqmPollInterval	The polling interval in seconds. This interval is the wait interval between queries of the Engineering Test Management server.	5
rqmAdapterName	The name that is used when you register with the Engineering Test Management server.	Integration Tester
rqmAdapterDescription	The description that is used when you register with the Engineering Test Management server.	Integration Tester adapter
idleTimeout	The duration in seconds for the agent to wait between the tests before closing the project. Value range: 0 to MaxInt (2,147,483,647)	60 seconds
keepProjectOpen	To improve the performance while running the sequential tests, the project is loaded and kept open in between the tests. However, if the tests belong to different Engineering Test Management projects, then different projects must be loaded and hence there can be a performance decline. For optimal performance, sequential tests should be run from the same project.	True

All parameters take the form <parameter value="" />, where the configuration value is specified in quotation marks and parameter is the configuration parameter that is being set (for example, <user name value="ghuser" />).