I worked with a colleague on the Work Item Command Line who was adding a feature for usage with a customer. That colleague had also done some changes related to availability and performance running queries. These changes where merged back into the code. WCL was missing some capabilities that I always wanted to have. I had a quick look to understand how much effort hat would be and took the opportunity to implement these capabilities on the way. While doing so, some small enhancements where added and some defects where found and fixed. All that needed to be published as a new version of WCL.
New in Version 4.3
The latest release 4.3 is available here and has the following changes:
- Readme.md updated
- Readme documents for deployment in source code updated
- Refactored the capability to create a string representation for a work item attribute, link or pseudo attribute (e.g. attachments) into a helper class WorkItemExportHelper
- Migrated -exportworkitems to use the new helper class WorkItemExportHelper
- Several fixes in -exportworkitems to
- Enable error handling and make suppressing errors work
- Introduce a new flag that exports all supported columns and links
- If exporting all columns, order the attributes and links (except ID, Type and Summary that are by default at the beginning)
- Checked functionality with newest OpenCSV
- Refactoring class to make maintenance easier
- Added a new command -printworkitem that prints the attributes, attachments and supported links of a work item
- Using the WorkItemExportHelper and its capabilities
- Also provides switch to print all attributes and links ordered as above
- Exports the attachments to a provided folder
- Added a new command -printtypeattributes that allows to get the attribute Id’s and Display Names for a given work item type in a project area
- Added a command -validateoslclinks that validates OSLC links and their back links in other applications fixing missing back links
- External library dependencies are added without a version number to allow newer versions
Please keep in mind that the information in this blog is “as is”, unsupported, and may be outdated or inaccurate.
The Work Item Command Line (WCL) is not an officially supported application.
For information on released products, consult the product documentation, support tech notes, and the Jazz.net library.
Some of the API used in the Work Item Command Line becomes deprecated.
- Some changes especially for -importworkitems needed for versions of RTC e.g. 6.0.5 and later
- These will likely not work with earlier versions of RTC
- if you need that either try an earlier version of WCL such as 4.0 or 4.1 or open an issue and I could look into a backport
- The Linking API in RTC has evolved and deprecates some API used in WCL
- OpenCSV has evolved and newer versions deprecates some API used in WCL
- OpenCSV requires a new library commons-lang3-3.1.jar
- Migration to Maven might be something to consider
This is all not problematic yet, but needs to be addressed sooner or later.
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.
An exception is the -importworkitems command that requires a library to use a mapping file. The capability to use the mapping file was moved into the plain Java Client libraries in RTC 6.0.5 as an internal class. To support work item import with the mapping moved to the Plain Java Client Libraries as internal API, the imports in ImportWorkItemsCommand where changed and the file com.ibm.team.workitem.rcp.core*.jar was removed from the jar file dependencies in the build path.
See Restore Compatibility to 6.0.4 and before for how to switch this back.
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.
Restore Compatibility to 6.0.4 and older
To support 6.0.5 and beyond the imports in ImportWorkItemsCommand where changed from:
and the file com.ibm.team.workitem.rcp.core*.jar was removed from the jar file dependencies in the build path.
Follow the description in the sections beginning with Downloads how to get and rebuild the code. The steps in this section below are required to port WCL back to RTC 4.0.4 and earlier:
The original imports have been put back in past 4.0.3, but commented out. To enable the mapping for earlier versions of RTC, replace the imports *BugzillaMapping* with the versions commented out. Then add the com.ibm.team.workitem.rcp.core_*.jar file back in to the build path and add the required JAR file as below
There are different ways to download.
- The easiest is to download the latest code as a zip file using the button Clone or download.
- Use the option Download ZIP to download the code as ZIP file. Once the download finishes, browse the folder structure of the ZIP file. The top level contains the README.md file. An Eclipse project is contained in the folder com.ibm.js.team.workitem.commandline. This project can be used to develop the code and to generate an executable.
- It is also possible to clone the repository and import the project using GIT. Clone the GIT project to your local file system. This requires GIT or some GIT GUI to be installed. How to use GIT is out of the scope of this blog. See the help how to set up GIT and how to use it with Eclipse.
- It is also possible to download releases from the releases page. The zip code made available is in the same format as the one above can be used as described above. Note that the releases might be older, and there might be no release available for the latest code version.
See below how to import the enclosed project into Eclipse.
Some releases might contain a prepackaged executable for convenience e.g. named wcl-V4.3-20190117.zip. See the section Deploying the packaged application below for how to use this form of packaging. Please note that the prepackaged executable might not be available for all versions. The following sections explain how to create this executable. See the section Packaging the application for shipping for how to perform the packaging.
Install a current Eclipse or RTC Eclipse client.
Install a current Java 1.8 JRE or Java 1.8 JDK set it as active in Eclipse as Installed JRE and Execution Environment.
Getting the code, install and deploy
Once you have installed such an environment do the following
Import the Code
- Open the Java Perspective in Eclipse.
- Import the project into Eclipse from the file system.
- To import the ZIP file use File>Import, select Existing Projects into Workspace. Click Select archive file, browse to and select the ZIP file you downloaded. Import the enclosed Eclipse project com.ibm.js.team.workitem.commandline.
- To import the GIT repository use the GIT perspective to add the local cloned repository and then import the
Create a User Library for the Plain Java Client Libraries
- Use Window>Preferences>Java>BuildPath>User Libraries and add a user library named PlainJavaApi .
- Add the JAR files of the Plain Java Client Libraries for the version of RTC you are using.
Download and Install openCSV
- Download opencsv from http://sourceforge.net/projects/opencsv/files/opencsv/3.7/
- It is possible to use the latest version 4.3.2 from https://sourceforge.net/projects/opencsv/files/opencsv/
- It is possible to use the latest version 4.3.2 from https://sourceforge.net/projects/opencsv/files/opencsv/
- Rename the jar file e.g. opencsv-3.7.jar to opencsv.jar
- Copy the library file opencsv.jar into /com.ibm.js.team.workitem.commandline/lib to be able to run from Eclipse
Download and Install Apache commons-lang
- Download apache commons-lang from https://commons.apache.org/proper/commons-lang/download_lang.cgi version 3-3.1 worked for me
- Rename the jar file e.g. commons-lang3-3.1.jar to commons-lang.jar
- Copy the library file commons-lang.jar into /com.ibm.js.team.workitem.commandline/lib to be able to run from Eclipse
Check the project and recompile
- Select Project>Clean and clean the project that was just imported.
- There should be no compiler errors or issues with the classpath
The project should now have built and compiled and show no errors.
Building the WCL or extract from a Release
Follow the description in the file ReadMe – HowToRelease.txt in the root folder of the project
- To create a wcl.jar file
- To crate a WCL/lib folder
- To provide batch and license files
Follow the description in the file /lib/ReadMe.txt in the lib folder of the project
- To provide the required libraries in the WCL/lib folder
Select the folder, for example C:\Temp\wcl\ and compress the file
- Rename the archive file to wcl-Vx-YYYYMMDD.zip,
where YYYY is the year, MM is the month and DD is the day
- The file is now ready for publishing
Use the file wcl-Vx-YYYYMMDD.zip for shipping similar to the next section.
Deploying the packaged application
Assume a file was created following the steps above and the file is called
wcl-V4.3-20190117.zip. This binary contains WCL as JAR file and other information such as licenses and Readme files. It also contains script files to set the environment and run the Jar File.
The folder lacks libraries needed to execute that need to be provided.
To deploy from this file, create a new folder as deploy location for the automation prototype. In the description here we use C:\temp. It is possible to use any other folder. In this case replace the folder in the this description by the folder you chose.
Extract the binary wcl-V4.3-20190117.zip file into the location C:\temp. There should now be a folder C:\temp\WCL. The folder among others contains the files wcl.jar, wcl.bat, wcl.sh.
Get the libraries as described in Download and Install openCSV and Download and Install Apache commons-lang above, and rename them as described in /lib/ReadMe.txt.
Check the script file and make sure to provide a valid path to a folder containing the unzipped Plain Java Client Libraries and a recent Java 1.8 is available over a Java_Home.
Call WCL using the script files or call it as Jar File as described in said script files.
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’sand follow the linked resources.
You should be able to use the following code in this environment and get your own automation or extension working.
This is only the first blog. I will try to provide a little bit more about the commands and the parameters soon.
As always, I hope this helps users out there.
Please ask questions on in https://jazz.net/forum/questions/ and tag them rational-team-concert and wcl.
You can create issues in https://github.com/jazz-community/work-item-command-line/issues as well.
Keep in mind this is off hours work and not officially supported.