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.

About this task

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

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:
     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.

     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 config2.ini.

     The adapter generates a configuration file to contain the registration information. The configuration file is either the config2.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 config2.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 config2.ini file:
     : Run the batch file without any arguments:

     C:\ start.bat

     : 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 config2.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 config2.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.

Launching Adapter…
Configuration file config2.ini does not exist, adapter will use the arguments passed
Successfully created an HTTP client
The adapter is now connected
Created Commandline Adapter