Configuring the HCL OneTest API Agent

The HCL OneTest™ API Agent can be configured as an IBM® Rational® Quality Manager adapter to enable remote test execution.

About this task

The following procedure is valid for all versions of Rational Quality Manager.


  1. The Agent must be provided with the Rational Quality Manager server configuration information, similar to the details provided in HCL OneTest API.
  2. The configuration can be modified in the Agent.config file, which is located in Agent_installation_directory/config. The configuration file is an XML file that contains an empty or default configuration that can be changed to match the HCL OneTest API and Rational Quality Manager installation environment.
    Note: By default, the Rational Quality Manager adapter functionality is disabled and must be configured before it can be used.
    The Rational Quality Manager 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 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" /> -->
    Note: To support multiple Rational Quality Manager projects, you can add multiple <rqm> sections to the configuration file. You can do this by either specifying a separate ghtprojectbaselocation for each Rational Quality Manager project or you must ensure that a HCL OneTest API project is only used from one Rational Quality Manager project.

    After the Agent configuration file is modified and saved, run the Agent to connect it to Rational Quality Manager 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.
    Note: Applies to the BASIC authentication method.
    The ID of a Rational Quality Manager user to be used by the Agent/adapter when you are connecting. This user ID requires either of the following Client Access Licenses, which can be assigned within Rational Quality Manager:
    • Rational Quality Manager - Connector
    • Rational Quality Manager - Quality Professional
    The user must also belong to the JazzUsers group under Repository Permissions.
    Note: Applies to the BASIC authentication method.
    The password for the user ID entered in Username. 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 "&amp;" or "&#38".
    Note: To use an encrypted password in the Agent.config file you can run the EncryptPassword program supplied with HCL OneTest API. Run the program from a command window, passing in the password and the encrypted password will be output. Copy and paste the encrypted password into the password element in the Agent.config file.
    url The base URL of the Rational Quality Manager server (for example, https://server_name:9443/qm). This is the public URI configured for the Quality Management application. The path of the URL to use is shown in the Application Administration list on the Jazz Team Server Home page, which is accessible from the Administration menu at the top right of 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 Rational Quality Manager project to which the configured Agent connects. The value that you enter for this parameter is displayed both as part of the RQM server URL and at the top of the RQM 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 HCL OneTest API projects. This is the directory that contains the projects that you use for running tests, such as C:\OneTestAPIProjects. For Rational Quality Manager, you must manually copy your projects from your HCL OneTest API 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:\OneTestAPIProjects. 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.
    Note: Applies to KERBEROS authentication method.
    The absolute path to the Kerberos configuration file. For example, C:\Windows\krb5.ini.
    Note: Applies to the SMARTCARD authentication method.
    An alias for the smart card certificate.
    Note: Applies to the SSLCERT authentication method.
    The absolute path to the SSL certificate keystore. For example, C:\work\certs\cert.p12.
    Note: Applies to the SSLCERT authentication method.
    The password for the SSL certificate keystore. For example,!eedc6A5240EC21137E1212994AC0446CE349.

    You can encrypt this value by using the EncryptPassword.exe located in the Agent installation folder or leave it as plain text.

    In addition to the required configuration parameters (shown), 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 Rational Quality Manager server. 5
    rqmAdapterName The name that is used when you are registering with the Rational Quality Manager server. HCL OneTest API
    rqmAdapterDescription The description that is used when you are registering with the Rational Quality Manager server. HCL OneTest API 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 Rational Quality Manager projects, then different projects needs to 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" />).