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 run the command-line adapter on supports a minimum of Java™ version 1.8 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 Engineering Test Management project area
The 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 Engineering Test Management project area permissions that control operations that are specific to test management, see Engineering Test Management 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.

Note: When you start the adapter, a lab resource is created. When the adapter is running, the permission for creating or editing a lab resource is not mandatory. You can create or edit lab resources even if you do not have the Save Lab Resource permission.

Important: Running the current version of the command-line adapter with an older version of the Engineering Test Management server is not supported. However, the command-line adapter with a version up to three releases older than the current version of the Engineering Test Management server can be connected and used with the current version of the Engineering Test Management server. For example, with the Engineering Test Management server 7.0.3 version, you can run the command-line adapter of version 7.0 and later.

About this task

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

Procedure

Complete these steps on the target test machine:

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.
Extract the RQMCommmandLineAdapter.zip file to a folder on the target test machine.
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.
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.

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

The host name or IP address of the Engineering Test Management server.

port

The port where the Engineering Test Management server is running.

userid

A registered user ID for Engineering Test Management that has the license to run an adapter.

password

The password of the submitted user ID. The user can specify the user password or the application password that is generated by the configured third-party identity provider, such as SAML or OIDC.

adapter-name

An adapter name that the user assigned.

project area

The name of the project that you are logging on to.

sleep time

The polling interval between polling for tasks. The default setting is 5 seconds.

configuration file

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. If you work in an environment that uses third-party identity providers, such as SAML or OIDC for authentication, use the application password that you receive from the Jazz Authorization Server (JAS).

Note: The command-line adapters support an authentication process to connect to the ELM applications that are configured for OpenID Connect (OIDC) authentication by using the JAS.
You can use this authentication process with the command-line adapters to work in an environment that uses third-party identity providers, such as SAML or OIDC for authentication without any direct support for the protocol that is used by these identity providers. Instead, users receive an application password from JAS. The application password is generated by the configured third-party identity provider. For example, a user can select SAML with the two-factor authentication process and use the application password for authentication with the ELM applications.

With this authentication process, you must assign the -password command-line argument and enter the application password instead of the user password.

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.

Argument name	Argument value
`-authType`	`KERBEROS`
`-kerberosConfigPath`	Absolute path to the Kerberos configuration file. Example: C:/Windows/krb5.conf

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.

Argument name	Argument value
`rqm.authType`	`KERBEROS`
`rqm.kerberosConfigPath`	Absolute path to the Kerberos configuration file. Example: C:/Windows/krb5.conf

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