Work Item Command Line 4.1

I recently had a chat with a colleague who is trying to automate RTC Work Item creation. As a casual user without administration experience they where wondering how to find the IDs for the work item types to be able to create work items of the types in WCL. Today you must know the ID of the work item and look them up in the administration UI.

I always wanted to add the ability to be able to list the available work item types in WCL, but for whatever reason I never got to searching the API and add it to WCL.  Having some time last week I took the opportunity to finally implement it. This closes a last big gap that WCL left open. Users can now print the work item types and with that information print the attributes available on the work item type.

A small description how to use WCL can be found here. WCL prints a help if the command is omitted. The help information is very long. Make sure to redirect it into a file or increase the shell buffer size.

This post provides the code for the latest version of WCL and also a description how to install WCL.


WCL is released under the MIT License. See the License.txt and the license headers in the individual files.


This code has been used with RTC 4.x, 5.x  and 6.x with no or minimal changes and it is pretty safe to assume, that the code will work with newer versions of RTC to come. The code requires the RTC Plain Java Client Libraries. The Export and import commands require additional external libraries that need to be downloaded and installed separately. See the document below.


Source Code for Download

The code is available in the Jazz Community. WCL 4.1 is available in this release.


Additional Download

You can also download the latest version 4.1 here:


Added a command printtypes to list the work item types available for a project area.

wcl -printtypes repository="" user=ralph password=****** projectArea="JKE Banking (Change Management)"

lists the work item types. The output will look like below:


The Type ID is the work item type ID required to set and get work item information. The type category is an additional information to understand if work item types have the same workflow.

Download the Plain Java Client Libraries

WCL requires at least the RTC Plain Java Client Libraries for your version of RTC. To download that, open the All Downloads tab of the RTC version you are interested in. For example and scroll down to the Plain .zip Files section.


Download the RTC Plain Java Client Libraries file.

Use 7Zip and unzip the RTC Plain Java client Libraries download file (for example named Use 7Zips Extract Files command and provide the extraction Path for example C:\RTCWCL\PlainJavaAPI. Remember the location for later.

Optional: Download the Plain Java Client Libraries API documentation and extract it to the same folder you extracted the RTC Plain Java client Libraries download.

How to Install WCL

There are several ways how the WCL can be set up and run. The two main methods are:

  1. As pre-compiled Java e.g in a jar file using a batch file
  2. Using launch files to run or debug in Eclipse

The following sections explain the first method.

Create Packaged Version

To package your own version of WCL for release from the source code, setup your development environment as described in the next section. Then follow the document ReadMe – HowToRelease.txt in the eclipse project you can find in the source code to package WCL.

Install Packaged Version

If you download the packaged, executable application latest version 4.1, the download is already packaged and prepared. The downloaded file is compressed and will be named like Extract the WCL package file e.g. using 7Zip to a folder, for example C:\RTCWCL.

The folders structure should look as below.


Check and Adjust the Script File

To work, the WCL needs a Java JRE or JDK. Open the file wcl.bat or Provide a JRE or JDK. I Usually use a JRE that comes with the CCM server or a JDK that comes with the Eclipse client. However any compatible JRE should do.

Change the JAVA_HOME variable to point to a location containing a JRE. If needed, remove the path section  JRE from the final call.


If you installed the Plain Java Client Libraries API into a different location, set the variable PLAIN_JAVA to that folder location.

Make sure the files are executable and test WCL e.g. by calling wcl and running one of the commands. For example use the new prittypes command

wcl -printtypes repository="" user=ralph password=****** projectArea="JKE Banking (Change Management)"

Provide Additional Libraries

The export and the import commands of WCL need two libraries that are not shipped with the downloads.

If you use the packaged WCL and want to use the export/import capability follow the steps below to add the required libraries to the folder lib in the folder lib in the WCL folder.

If you use the Eclipse project for WCL and want to use the export/import capability follow the steps below to add the required libraries to the folder lib in the Eclipse project

The export and the import commands of WCL use the Open CSV Library. I had issues with the newer versions of Open CSV that I could not resolve, so this code assumes the version 3.7. Download the version 3.7 from here. Uncompress and untar the the file opencsv-3.7-src-with-libs.tar.gz you downloaded. Look for the folder opencsv-3.7 deploy\ copy the JAR file opencsv-3.7.jar and put it into the lib folder of your version of WCL.

It is possible to use other such libraries like SuperCSV with minor changes to the source code as well.

The import commands of WCL can only provide the capability to use a mapping file by using a JAR file that only ships with the RTC Eclipse client and the SDK. The classes used for the mapping file capability are located in the library  Open the Install location of the RTC Eclipse client and search for*. You should find a file names similar to this one: The version numbers at the end could be different. Copy the JAR file into the into the lib folder of your version of WCL.

Installing the Source Code

The best approach to develop for the RTC Java APIs is, to setup the development environment based on the RTC SDK . This provides with the source code for the API and allows to search examples. This saves so much time in the long run that saving the effort of setting the SDK makes no sense. So follow the instructions in the next section.

Just starting with extending RTC?

If you just get started with extending Rational Team Concert, or create API based automation, start with the post Learning To Fly: Getting Started with the RTC Java API’s and follow the linked resources.

Importing the Source Code

Get the source code from the Jazz Community. Use Git to clone the project and import the source project into Eclipse. You can also download the source as a zip file and import the project with the other Eclipse Import wizards. Switch to the Java perspective or the Plug in Development perspective.

The project should look as below


The folders contain the information to build the jar file, to run the and debug the code, folder for additional libraries and the scripts to run the Java application from a shell.

The Eclipse project is a Plug-in development project. This trick provides the access to the SDK and the API source code.

Install The Plain Java Client Libraries

The project references the Plain Java Client Libraries and needs them to run.


So the minimum additional step needed to be able to run the WCL for development in Eclipse is to install the RTC Plain Java Client Libraries as a user library.  The Plain Java Client Libraries have already been downloaded and installed. The same folder with the install can be used in the next steps.

Open Windows>Preferences and type “User lib” into the search window.


In the Java>Build Path User Libraries click the New… button. Type the name that is alreay referenced: PlainJavaAp. Click OK.

Select the new User Library and click Add External JARs…


Browse to the folder containing the Plain Java Client Libraries C:\RTCWCL\PlainJavaAPI in this example. Select all JAR files and click open.


The User Library should now contain the libraries.


Go back to the section “Provide Additional Libraries” and add the libraries to the folder lib. Make sure the libraries are available. Remove and re add the jar files to the build path if needed.

You should now be able to run or debug the WCL from within Eclipse. The debug configurations shipped with the source code in the Launches folder are now available under the Debug>Debug Configuration section.


Change the configurations as needed.

To package your own version of WCL for release from the source code, follow the document ReadMe – HowToRelease.txt in the eclipse project you can find in the source code to package WCL.


You should now be able to start working on WCL and enhance it if needed. I hope this document helps the many users out there.


14 thoughts on “Work Item Command Line 4.1

  1. Hi Ralph,

    It is a very good job. Actually I was using the version 3 but it failed with NPE at Attachment to String point. Now I found the new version and tried to give it a try. It does not start at all as ClassNotFoundException for com.opencsv.CSVWriter . Are you sure it still uses the opencsv version 2.3? The com.opencsv packaging was introduced in version 4, wasn’t it?


  2. Hi Ralph,
    I always get very good tips and well support for this utility.Our jazz instance is recently changed with TLS 1.2 . Thereafter, our WCL utility failed with below exception.

    “TeamRepositoryException: Unable to log into repository!
    CRJAZ0099E An HTTP error occurred when this URL was being accessed: /ccm/versionCompatibility?clientVersion=6.0.4. Error details: Remote host closed connection during handshake. ”

    Please help us to fix this issue.


  3. Hi Ralph, I installed wcl in UNIX, got “Exception in thread “main” java.lang.NoClassDefFoundError:” when I tried to run it. What would be the fix to get the error go away? Thanks!

    • I have already answered in Please look there, Summary:
      1. Make sure not to use Java 1.9. Use Java 1.8. Make sure the class path works.

      I can not test the Linux script, but it should look like this:

      export JAVA_HOME
      export PLAIN_JAVA
      $JAVA_HOME/bin/java -Djava.ext.dirs=./lib:$PLAIN_JAVA:$JAVA_HOME/jre/lib/ext -cp ./lib:$PLAIN_JAVA% -jar wcl.jar “$@”

  4. Hello Dear Ralph,
    I would like to thank you for this solution, it sounds pretty interesting, but I’ve one problem in the creation of the Defect or Activity here it is the trace :

    .\wcl : 10-janv.-2019 16:40:49 unexpectedError
    At line:1 char:1
    + .\wcl -create /ignoreErrors repository=”https://rtc5a.gsissc.myXftd.n …
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (10-janv.-2019 1…unexpectedError:String) [], RemoteException
    + FullyQualifiedErrorId : NativeCommandError

    GRAVE: Error invoking default value provider

    how to hide this or fix it , at the end the ticket or defect or the activity is created.

    • Sorry, I can’t help with the information provided. Please post a question to, provide version numbers, the call parameters (hide passwords and sensible data).

      WCL does not call any value providers, maybe you are passing data that violates rules or there is a clash between the data you send and a default value provider you use. Look into the process configuration and search for sWS7ANaVEeiyj78paVC0OQ to find out what value provider that is.

      Use a test system to play with WCL to understand it is working. Make sure to understand what values to pass, disable required attributes etc in case there are errors on the server side.

      If you want to discuss more, ask and provide the data mentioned above on,

  5. Hi Ralph,

    I’am facing this issue when I execute Create command for WCL:

    GRAVE: Value provider not found:

    is that normal ? I use /ignoreErrors but fruitless

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.