Setting up and starting the command-line adapter

With the command-line adapter, you can use a target test machine for command-line execution. You must register the adapter on the target test machine to run command-line scripts.

Before you begin

  • Ensure that the platform you will run the command-line adapter on supports a minimum of Java version 1.5 or later.
  • The java.exe executable file must be accessible in the path on the target test machine.
  • To start the adapter, you must have this information:
    • The Jazz repository URL, which is typically https://qmserver:port/qm
    • A user ID that has the appropriate licenses to log on as an adapter
    • The password for this user
    • The name of the project area, if it is not the default Quality Management project area
  • The Quality Management application must be running on the server.
  • Ensure that each user belongs to each project area created on the IBM® Engineering Test Management server. All users must also have both the "Register Tool Adapter" and the "XML Import" permissions that are assigned to them. Otherwise, they cannot send or import data to Engineering Test Management, and the adapter is stopped. For more information on the Quality Management project area permissions that control operations that are specific to test management, see Quality management role-based permissions. For information about accessing these settings, see Modifying role-based permissions.
Important: You can run more than one adapter on a target test machine, but each adapter must be a separate process with a unique name that is specified in the -adapterName option.

About this task

The command-line adapter must be set up and started on the target test machine.

Command-Line Execution setup

Procedure

Complete these steps on the target test machine:

  1. Obtain the install-location\JazzTeamServer\server\conf\qm\adapters\RQMCommmandLineAdapter.zip file from the installation machine. A server administrator with read access to the server might need to get the compressed file for you.
    Note: In environments where you are setting up multiple target test machines, make sure to upload a clean copy of the RQMCommmandLineAdapter.zip to each test machine.
  2. Extract the RQMCommmandLineAdapter.zip file to a folder on the target test machine.
  3. Optional: Customize the actual script results, which are shown in the test case execution record or test suite execution record. For more information, see Customizing the command-line adapter.
  4. If you use version 5.0 or later and want command-line adapters to serve multiple requests in parallel, you can enable that feature, which is disabled by default. You enable the feature by adding a property. If you do not add the property or set it to an invalid value, when multiple tests are sent to an adapter, they are queued to run as they were received.
    Tip: Using the command-line adapter to run tests in parallel is best for long-running tests. The adapter selects tests one by one based on its capacity to run each test. It selects a script, starts running it, and then selects another script to run. If the scripts are short, it might seem like they are being run sequentially.
    To enable parallel test execution on a command-line adapter:
    1. On the test target machine, open the CommandLine.properties file or an equivalent preferences file.
    2. Add the following property to the file: com.ibm.rqm.commandline.maxservedrequests=N

      Where N is the maximum number of tests to run concurrently.

    3. If the command-line adapter is active, restart it.
    When the specified maximum is reached, tests that are sent to the adapter are queued to run as space becomes available.
  5. Start the command-line adapter.
    • To start the command-line adapter for the first time:
      Windows icon
      Run the batch file with the command-line arguments as shown:
      C:\ start.bat -repository  https://qmserver:port/qm -user userid -password password [-adapterName adapter-name]
      -projectArea project area[-sleepTime sleep
      time]	[-configFile configuration file]

      In an environment with multiple target test machines to ensure that each adapter has a unique ID at startup, you can add the -adapter argument for each command-line adapter that you start. You must provide a different value for each adapter. For example: [-adapter adapter-id]

      Note: You cannot connect a test adapter with the same adapter ID on different test host machines in a project area. If you try to connect the test adapter, an error message indicates that another adapter with a same ID is running. To avoid this error, register the adapter with a different ID.

      For more information, see Customizing the command-line adapter.

      Linux icon
      Unix icon
      Run the shell script with the command-line arguments as shown:
       $ start.sh -repository  https://qmserver:port/qm -user userid -password password [-adapterName adapter-name]
      -projectArea project area[-sleepTime sleep
      time]	[-configFile configuration file]
      Where:
      • qmserver is the host name or IP address of the Quality Management server.
      • port is the port where the Quality Management server is running.
      • userid is a registered user ID for Quality Management that has the license to run an adapter.
      • password is the password of the submitted user ID.
      • adapter-name is an adapter name that the user assigned.
      • project area is the name of the project that you are logging on to.
      • sleep time is the polling interval between polling for tasks. The default setting is 5 seconds.
      • configuration file is the file to store and read the settings for this adapter. The default file name is config.ini.

      The adapter generates a configuration file to contain the registration information. The configuration file is either the config.ini file or the file that is specified in the -configFile option. This information is reused when the adapter is restarted.

      When you start the command-line adapter for the first time, you must enter your user ID. The adapter prompts you to enter your password; then, the password is encrypted and stored in the config.ini file.

    • To start the adapter by using smart card authentication:
      You can use a smart card to authenticate a Engineering Test Management server while you start the adapter. Use the following authentication methods:
      • To authenticate by using Kerberos/SPNEGO, pass the values for the following arguments:
        Argument name Argument value
        -authType KERBEROS
        -kerberosConfigPath Absolute path to the Kerberos configuration file. Example: C:/Windows/krb5.conf
      • To authenticate by using a keystore alias, pass the values for the following arguments:
        Argument name Argument value
        -authType SMARTCARD
        -keystoreAlias Keystore alias (friendly name) for the user certificate.
      • To authenticate by using an SSL certificate, pass the values for the following arguments:
        Argument name Argument value
        -authType SSLCERT
        -certificatePath Path to the SSL certificate. Example: C:\SomeDir\userCert.p12
        -certificatePassword Password for the certificate file. This argument is optional.

      For more information about smart card authentication, see the readme file for the adapter.

    • To restart the command-line adapter from a config.ini file:
      Windows icon
      : Run the batch file without any arguments:
      C:\ start.bat
      Linux icon
      Unix icon
      : Run the shell script without the command-line arguments:
      $ start.sh
      Note: The configuration file is expected to be in the directory that the adapter is started from. In environments with multiple command-line adapters on separate test machines, you must delete the generated config.ini file and restart the command-line adapter by performing the first-time startup procedure.
    • To use smart card authentication when you restart the adapter from a config.ini file:

      You can use a smart card to authenticate a Engineering Test Management server while you restart the adapter. Use the following authentication methods:

      • To authenticate by using Kerberos/SPNEGO, pass the values for the following arguments:
        Argument name Argument value
        rqm.authType KERBEROS
        rqm.kerberosConfigPath Absolute path to the Kerberos configuration file. Example: C:/Windows/krb5.conf
      • To authenticate by using a keystore alias, pass the values for the following arguments:
        Argument name Argument value
        rqm.authType SMARTCARD
        rqm.keystoreAlias Keystore alias (friendly name) for the user certificate.
      • To authenticate by using an SSL certificate, pass the values for the following arguments:
        Argument name Argument value
        rqm.authType SSLCERT
        rqm.certificatePath Path to the SSL certificate. Example: C:\SomeDir\userCert.p12
        rqm.certificatePassword Password for the certificate file. This argument is optional.

      For more information about smart card authentication, see the readme file for the adapter.

Results

The system generates a message that is like this message:
Launching Adapter…
Configuration file adapterConfig.ini does not exist, adapter will use the arguments passed
Successfully created an HTTP client
The adapter is now connected
Created Commandline Adapter

What to do next

You can verify the adapter state in the Quality Management application on the test machine by clicking Execution > Adapter Console. Before you try to run a test against a running command-line adapter, make sure that the status is green.

video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki