Configuring HCL OneTest API Agent as an IBM® Engineering Test Management adapter

HCL OneTest API Agent can be configured as an Engineering Test Management adapter to enable remote test runs.

Procedure

  1. The agent must be provided with the Engineering Test Management server configuration information, similar to the details provided in HCL OneTest API.
  2. The configuration can be modified in the Agent.config file. If you have installed HCL OneTest API Agent, then modify the Agent.config file in Agent_installation_directory/config. If you only installed HCL OneTest API then modify the Agent.config file in API_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 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 HCL OneTest API 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 "&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 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 HCL OneTest API projects. This is the directory that contains the projects that you use for running tests, such as C:\OneTestAPIProjects. For Engineering Test Management, 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.
    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" />).