Registering HCL OneTest API Agent with HCL Quality Server

HCL Quality Server runs stubs on agents. Agents can also be used to run scheduled tests. During the installation of the HCL OneTest API Agent, the agent is configured to register with the server instances so that they are available for stubs and/or running scheduled tests.

About this task

After the installation of the HCL OneTest API Agent, you can change the configuration of the agent by editing the Agent.config file manually. For example, you might need to change the URL of the server instance with which the agent is registered.

  • An agent can be registered with only one server instance at any given time.
  • The settings in the Agent.config file are used regardless of whether the agent is run from a command prompt or as a service.


  1. Using a text editor program, open the Agent.config file, which is in <Agent installation directory>\config.
  2. Find the server properties at the beginning of the file:

    Server configuration section in the agent config file

  3. Ensure that the enabled attribute is set to true.
  4. Set the base-url value as required.
    • The base-url value must not end with a forward slash (/).
    • You can specify Internationalized Domain Names (IDN) values as the host name in the base-url value. To update the file with the IDN value, you must open the file in "UTF-8" encoding format.
  5. Set the security-token value if you want to use domain-level security for the agent.
    For more information about security-tokens, see Configuring agents and proxies to use security tokens.
  6. Set the identifier value if you want to specify a name for the agent.

    The name is displayed on the Infrastructure Dashboard of HCL Quality Server 8.6.0 or later. Assigning a name to an agent makes it easier to identify the agent when two or more agents of the same type are registered with the server.

  7. By default the agent trusts all certificates presented by the server. For greater control over the truststore and SSL protocol used you can use the default SSL element or you can specify and use a different truststore if you want to use your own generated certificate.
    Table 1. SSL settings
    Element Description
    ssl The SSL connection details that you want to use to connect to the server. The SSL element is optional. If the ssl element is not included, then the agent uses the Java keystore location and password that is found in the system properties and If these properties are not set, then the agent trusts all server certificates.
    If set to true, this attribute tells the agent to trust all certificates that are presented by the server. In this case, the trustStore, trustStoreType and trustStorePassword attributes are ignored.
    The path to the keystore that contains the trusted certificates that are used to verify the certificate that is presented by the server. By default this attribute's value is set to the path of the ssl\greenhat.jks keystore, which is included with the HCL OneTest API Agent and contains the HCL OneTest API Root CA certificate. If the server's certificate was changed, then this value must also be changed to point to a keystore that contains a certificate that can be used to verify the new server certificate. For more information about configuring the server certificate, see Using your own truststore for server SSL connections.
    The type attribute specifies the type of the keystore. If not specified, the default value is jks.
    The password attribute specifies the password that is used to load the keystore file. The password for the default truststore is passphrase.
    The protocol attribute defines the SSL handshake protocol used to connect to the server.

    Default value: SSL_TLSv2, TLS.

    The specified default options are checked for availability. SSL_TLSv2 protocol is supported by the JRE and, if it is unavailable, the TLS protocol is used.

  8. If you want to restrict the agent so that it is available only for specific domains and environments, uncomment the <domains> block and enter one or more domains and environments.
    • If HCL OneTest API Agent was installed in agent mode, you must restrict the agent so that it is available only for specific domains and environments. This restriction is because the default Agent.config file makes the agent available for running stubs in all domains and environments that are managed by the server.
    • Each environment name value must end with a forward slash (/). Otherwise, the XML is invalid and the agent might not start.
  9. Save and close the file.
  10. If the agent was running while the Agent.config file was being modified, restart it to enable the changes that you made to take effect.


To determine if HCL OneTest API Agent registered correctly, log in to the server as an administrator and open the Infrastructure Dashboard. The registered agents and proxies are displayed.
Note: The server "heartbeats" with agents and proxies, so the server is aware if they stop running, and the agent and proxies are aware if the server stops running. The agent/proxy logs and Infrastructure Dashboard indicates this case if it happens. The environment recovers itself when the agent/proxy or server restarts. For example, if an environment is running with two or more agents and two or more HCL OneTest API proxies, and the server is restarted, the agents and proxies register automatically when the server restarts, so they do not need to be restarted manually.