A RTC WorkItem Command Line V1.0 – Deprecated


Please refer to the new Version of the RTC WorkItem Command Line. The code has been enhanced and received a lot of testing and will be the basis for future efforts.

Version 1.0 is Deprecated

Version 1.0 is Deprecated

Please refer to the new Version of the RTC WorkItem Command Line. The code has been enhanced and received a lot of testing and will be the basis for future efforts.

I have seen many requests to be able to create and update work items from a command line in the forum. There are enhancement requests and a story for it in the Rational Team Concert development repository. I had a lot of the required code already available and thought I should provide a solution if possible.

This post provides a simple Work Item Command Line Client and explains the usage. It comes with code, so you can also enhance it if you need more features.

 

Related posts

  • Installing and using the WorkItemCommandLine – this post

WorkItemCommandLine Summary

The WorkItemCommandLine – in short WCL – works on Windows and Unix clients. It requires a JDK and the Plain Java Client Libraries to be installed.

It currently allows to

  • Create work items
  • Update work items
  • Show the attributes ID’s available for a work item type in a project area

The WCL allows to set and update almost all available attribute types.

  • String based attributes
  • Number based attributes
  • Enumeration and Enumeration List based attributes
  • Tag based attributes
  • ……

This works for built in attributes as well as for custom attributes.

The only attribute types currently not supported are Item and ItemList, where the type of the item is not specified or where the type is an SCM object. This might get implemented in the future. The problem is that the syntax needs to be able to specify what Item Type to look for in order to implement this, and to include the SCM component for searching.

Please note, for List attribute types it is currently only possible to set the list, unless described otherwise in the help. I am looking into a common parameter value encoding that can help more flexibility with being able to add and remove items as well.

In addition to these attribute types various not attribute based work item values can be modified:

  • Subscription
  • Comments
  • Approvals
  • Links to work items
  • Links from build results
  • Attachments can be uploaded
  • Trigger a workflow action

This should be sufficient for most of the automation needs, especially during builds.

License

The post contains published code, so our lawyers reminded me to state that the code in this post is derived from examples from Jazz.net as well as the RTC SDK. The usage of code from that example source code is governed by this license. Therefore this code is governed by this license. I found a section relevant to source code at the and of the license.

Please also remember, as stated in the disclaimer, that this code comes with the usual lack of promise or guarantee.

On the other hand, you have the code and are able to add your own code to it. It would be nice to know what you did and how, if you do so.

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.

You should be able to use the following code in this environment and get your own automation or extension working.

 

Download

You can download the tool here:

Setup

Download the packaged executable application. The file is compressed and will be named like wcl-Vx-YYYYMMDD.zip. The x represents the version number and is followed by the date it was created.

If you have installed an RTC API development environment following the RTC Extensions workshop and this post, you have all else that is needed and can use  the installs folder of your extension development install, for example C:\RTC401Dev\installs.

Extract the file e.g. using 7Zip to a folder, for example C:\RTCWCL (or C:\RTC401Dev\installs).

The destination folder should now contain a folder wcl.

If you don’t have an extension development environment set up, download and install the Plain Java Client Libraries for your version of RTC. Open the All Downloads tab of the RTC version you are interested in. For example https://jazz.net/downloads/rational-team-concert/releases/4.0.1?p=allDownloads and scroll down to the Plain .zip Files section.

PlainJavaDownloadDownload the Plain Java Client Libraries file.

Use 7Zip and unzip the Plain Java client Libraries download file (for example named RTC-Client-plainJavaLib-4.0.1.zip). Use 7Zips Extract Files command and provide the extraction Path C:\RTCWCL\PlainJavaAPI .

If you don’t have an extension development environment set up, download and install a Java JDK. If you have the Rational Team Concert client installed a compatible JDK is available in the install location e.g. TeamConcert\jazz\client\eclipse\jdk. The easiest way is to download the zip version of the Rational Team concert Client and extracting it to C:\RTCWCL\TeamConcert.

The folder should now look similar to this image.

WCL Folder Structure

Adjusting the Scripts to the Environment

If you downloaded a different JDK or have the RTC Eclipse client installed in a different location, follow the next steps to adjust the WCL to the different paths.

Open the folder created when extracting the WCL for example C:\RTCWCL\wcl. The folder contains the script files

  • wcl.bat – for Windows clients
  • wcl.sh – for client with Unix/*ux operating systems such as Linux

Open the file relevant for your operating system. It should look similar to this:

Script

The script assumes an install structure where the JDK and the Plain Java Client Libraries are installed like in the image before. If your setup uses different paths, adjust then according to your setup.

On Unix operating systems chmod the shell script so that it is executable.

You should now be able to run the WorkItemCommandLine.

Test the Environment

Open a shell or cmd window. change the directory to where you extracted WCL for example C:\RTCWCL\wcl. Type wcl and run the WorkItemCommandLine. The command should be executed and print help content like below.

Start WCLIf this does not happen, make sure the paths are set correctly and the JDK is compatible.

The Syntax of WCL

WCL uses the following syntax:

wcl -<command> [/<flag>] [<parameter>=<value>]

Where <command> can be

  • create
  • update
  • printtypeattributes

The commands have their own requirements for base parameters such as repository URL, users, password and the like.

The flag

  • ignoreErrors allows to successfully perform the create and update command if minor errors happen. For example if an optional attribute or its value was not found. If the flag is not provided any error will cause the operation to fail.

The parameter sections <parameter>=<value> must not have spaces in the <parameter> or in the <value> or before or after the =. You can enclose the value of <parameter>, <value> or the whole term in quotation marks. For example projectArea=”JKE Banking (Change Management)”.

The WorkItemCommandline also defines various pseudo attribute names e.g. to upload files as attachment.

Each <parameter> can only be used once in the command line. In some cases like attachment uploads a special section needs to be added in the parameter to allow for multiple specifications.

The WorkItemCommandline also has an alias mechanism built in, that allows to map different external names for attributes to the internal representation. Currently the names of the AttributeCustomization described here are built in. This allows, for example, to use FOUND_IN=”Sprint 2 Development” instead of foundIn=”Sprint 2 Development”. You can add your own aliases if needed.

Parameter values <value> are usually the display value of elements. For example setting an enumeration attribute would use “High” instead of the literal ID. This makes it easier to use.

In some cases e.g. for links, subscriber lists and other user lists, it is necessary to specify the ID of the element instead of the display name.

The help given by the tool should be enough to figure out how to use it. However, here some more details and examples.

The Command to get the Attribute ID’s and Types

To set work item attributes, wcl needs the ID of the attribute. You can look up the ID of an attribute in the process configuration. The command printtypeattributes prints the attribute ID’s for the built-in and for the custom attributes of a work item type in a project area.

wcl -printtypeattributes repository="https://clm.example.com:9443/ccm" user=ralph password=ralph projectArea="JKE Banking (Change Management)" workItemType=task

Please note, for the built in attributes this returns an internal ID that might not show up if you look into the process configuration. You can use the ID’s you find there too, the API should translate them correctly.

The Create Command

The command create can be used to create a new work item and set its attributes.

The command requires, in addition to the repository URL, the user and password, at least the project area and the work item type to create. Please note, if the process specifies additional required attributes, these need to be provided as well, otherwise the creation and save operation will fail.

Here an example for creating a work item.

wcl -create /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph projectArea="JKE Banking (Change Management)" workItemType=task summary="New Item" category=JKE owner=ralph

The Update Command

The command update can be used to update a work items attributes.

The command requires, in addition to the repository URL, the user and password, at least the ID of the work item to update. Please note, if the process specifies additional required attributes, these need to be provided as well, otherwise the save operation will fail. This can be relevant if the state of a work item is changed.

Here is an example where a work item gets heavily updated:

-update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 SUMMARY="New summary" FOUND_IN="Sprint 2 Development" owner=ralph target="Main Development/Release 1.0/Sprint 3" internalSeverity=Major foundIn="Sprint 2 Development" internalPriority=High attachFile="./Test.txt:Some Description:text/plain:UTF-8" internalApprovals="approval:Please Approve:ralph,deb" internalSubscriptions=al,ralph,deb internalState="In Progress" internalTags="test1,test2" custom.duration=1800000 custom.boolean=true custom.contributor=al custom.contributor.list=al,deb,tanuj custom.decimal=1500200 custom.integer=234 custom.long=567 custom.tag=tag1,tag2 custom.timestamp="2014/12/31 12:30:00 GMT+01:00" custom.wiki="My Wiki" custom.projectarea.list="JKE Banking (Change Management)" custom.project.area="JKE Banking (Change Management)" custom.teamarea.list="JKE Banking (Change Management)/Business Recovery Matters,JKE Banking (Change Management)/Release Engineering" custom.team.area="JKE Banking (Change Management)/Release Engineering" custom.process.area="JKE Banking (Change Management)/Release Engineering" custom.processarea.list="JKE Banking (Change Management)/Business Recovery Matters,JKE Banking (Change Management)/Release Engineering" custom.workitem=3 custom.workitem.list=9,20,7

Special Attributes and not  Attribute Based Workitem Modifications

Some attribute types need special treatment or require more complex values to be specified. Some have other limitations and considerations. These are explained below.

For Item List attributes the items need to be provided as a list of items with the separator “,”. As an example a work item attribute of type TeamAreaList would be set like this:

custom.teamarea.list="JKE Banking (Change Management)/Business Recovery Matters,JKE Banking (Change Management)/Release Engineering"

Please note, that this implies that the separator can not be part of any of the display names of the elements.

Special Properties Handling

Some special properties are protected from changing.

  • Work Item ID: can not be changed
  • Project Area: can not be changed – use the category

There might be other limitations imposed by the process e.g. against changing the creator of a work item.

User, User Lists, Subscribers

For attributes that require users or user lists the value of the property needs to specify the user or the list of users with the ID. Examples:

internalSubscriptions=al,ralph,deb custom.contributor.list=al,deb,tanuj

Links

To create links to other elements a special pseudo attribute/parameter link is used. The syntax is:

link_<linktype>=<value>

The supported <linktype> values are printed in the help. The value is a list of item ID’s to link to. The list of one or more elements can either be a list of one or more work item ID’s or the label or ID, in case of a build result. Examples:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 link_parent=1 link_blocks=2,3 link_reportAgainstBuild=P20141208-1713

 Workflow, States and Resulutions

The WorkItemCommandline allows to set the state of the work item in different ways. Please note, the state is reached after the save operation, if it can be set.

You can specify a workflow action by using the pseudo parameter workflowAction. In this case wcl looks up the current state of the work item, tries to find a workflow action with the given name and sets the save operation to trigger this action when the work item gets saved. An example:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=115 workflowAction="Reopen"

In addition the attribute internalState can be used to set the state.

Syntax is:

internalState=[<forceFlag>:]StateName

In this case wcl looks up the target state and tries to reach the state, using any available direct workflow action. If there is no workflow action the state change is not performed. If the flag forceState: is added before the target state, wcl uses a dprecated API to forcefully set the state. Please note, that this does not trigger a workflow action and does also not trigger operational behavior. It should be used with caution.

Example with a target state:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 internalState="In Progress"

Example with a target state forcefully set:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 internalState="forceState:New"

The resolution can be set using the attribute internalResulution. Example:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 workItemType=defect internalResolution=Invalid

Approvals

The WorkItemCommandline allows to create approvals, reviews and verifications. The syntax is

internalApprovals=”<approval_type>:<Approval Name String>:{<userID1>{,<userID>}}

Where <approval_type> is one of

  • approval
  • review
  • verification

The name of the approval <Approval Name String> is required and it is possible to add one or more approver userID’s

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="approval:Please approve:ralph,deb"
wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="review:Please review:deb"
wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="verification:Please verify:tanuj"
wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111  internalApprovals="verification:We need a verification"

Attachments

The WorkItemCommandline allows to upload attachments to work items. The syntax is

attachFileIDString{<uniqueID>}=”<pathToFile>:<description>:<contentTypeID>:<encodingID>”

Where the <uniqueID> is optional, but must be unique if multiple attachment uploads are specified, the <pathToFile> needs to exist  and be accessible, the description is some string.

The values for <contentTypeID> and <encodingID> need to match the file.

Supported values for <contentTypeID> are:

  • text/plain
  • application/unknown
  • application/xml

Supported values for <encodingID> are:

  • UTF-8
  • UTF-16LE
  • UTF-16BE
  • us-ascii

Example:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 attachFile="./Test.txt:Some Description:text/plain:UTF-8" attachFile_1="./LintResult.txt:Lint result:text/plain:UTF-8"

Subscriptions

WCL allows to add subscribers to work items. The syntax is:

internalSubscriptions=<userID1>{,<userID>}

To remove subscribers use the pseudo attribute unsubscribe. The syntax is the same as when subscribing:

unsubscribe=<userID1>{,<userID>}

Example:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph internalSubscriptions=al,ralph,deb unsubscribe=myadmin

Tags

WCL allows to set tags in the built in tag attribute as well as for custom attributes of the type tag. The syntax is:

<parameter>=<Tag>{,<Tag>}

Example:

wcl -update /ignoreErrors repository="https://clm.example.com:9443/ccm" user=ralph password=ralph id=111 internalTags="test1,test2" custom.tags="MyTag"

Duration Types

In duration types provide the value in milliseconds. For example

custom.duration=1800000

Timestamps

Timestamps need to be provided as string in the SimpleDateFormat using the format pattern “yyyy/MM/dd hh:mm:ss z”. For example:

custom.timestamp="2014/12/31 12:30:00 GMT+01:00"

Summary

This WorkItemCommandLine should allow for most of the automation needs when creating work items. In addition it is a nice resource for the RTC work Item API. If my schedule allows, I will enhance it to support the missing types and potentially some export and import options.

In later posts I will explain the code for users that are interested in adding their own implementation.

As always, I hope the post is an inspiration and helps someone out there to save some time. If you are just starting to explore extending RTC, please have a look at the hints in the other posts in this blog on how to get started.

Advertisements

About rsjazz

Hi, my name is Ralph. I work for IBM and help colleagues and customers with adopting the Jazz technologies.
This entry was posted in Jazz, RTC, RTC Automation and tagged , , , , , , , , , , , , , . Bookmark the permalink.

7 Responses to A RTC WorkItem Command Line V1.0 – Deprecated

  1. Sam says:

    Really JDK? are u compiling some java under the covers? otherwise JRE should be enough I would think

    • rsjazz says:

      I have seen a issue with just a JRE and the plain Java Client Libraries in the past. A special error message missing the EXT folder.

      I am too Java-dummy to know how to fix it. If you get it running with a JRE, great and let us know.

      I have so many RTC JDK’s (yes it is a JDK in the Eclipse client) that I don’t need another JRE.

  2. Harry says:

    Very nice. Thank you for putting this together. And plans to support the creation of OSLC links to DNG or RQM? Thanks.

  3. ibmamnt says:

    I propose to have this utility on either GitHub or JazzHub (IBM DevOps services). I see customer would like to folk the source to customize this !

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s