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®
Rational® Quality Manager 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 Rational Quality
Manager, 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.
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:
- On the test target machine, open the
CommandLine.properties
file
or an equivalent preferences file.
- Add the following property to the file:
com.ibm.rqm.commandline.maxservedrequests=N
Where N is the maximum number of tests to run concurrently.
- 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 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 Rational Quality Manager 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:: 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 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 Rational Quality
Manager 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 . Before you try to run a test against a running command-line adapter, make sure that
the status is green.