Integrate Rational Team Concert by using Visual Basic scripting language

Use Rational Team Concert OSLC capabilities to integrate it with an existing system

IBM Rational Team Concert is an agile application lifecycle management (ALM) solution that helps software development teams collaborate, regardless of where they are located. It has various capabilities, such as task management, defect management, source code configuration management, build management, and so forth. It implements an open service called Open Services for Lifecycle Collaboration (OSLC), which enables it to integrate with an existing system, such as a project management or activity management tool. This article explains how to take advantage of the Rational Team Concert OSLC service by using Visual Basic scripting language and how to integrate it with an existing system.

Share:

Takehiko Amano (amnt@jp.ibm.com), IT Specialist, IBM

author photoTakehiko Amano is a solution architect at the IBM Software Development Laboratory in Tokyo, Japan. He works as a member of Unleash the Labs initiative. One of his interests is global collaborative software development tools and processes.



04 September 2012

Also available in Chinese Russian Portuguese

Scenario

Suppose that there you work with a system that was constructed by the latest technology at the time, for compliance. It is mandatory to input development information. The system became stable enough, so IT manager decided not to maintain the system except for security vulnerability concerns and defects associated with new OS patches. Also suppose that IBM® Rational Team Concert™ was introduced to the development team to support global delivery. Developers probably do not want to waste precious time to input the same information to both systems. The goal of this article is to illustrate techniques to integrate this kind of system.

Figure 1 shows a goal image of this article. My System is used to input some kind of development information, which has a COM+ interface to the system, while the team introduced Rational Team Concert to accelerate global delivery. Rational Team Concert has an open interface called OSLC (Open Services for Lifecycle Collaboration).

Figure 1. Goal is to integrate an existing system, My System, with Rational Team Concert
Illustration of uses of the two separate systems

Disclaimer and prerequisite for using these sample scripts

The script is provided merely as a sample and should be considered as-is. If you try the script receive an error message similar to either of these, it is likely that Rational Team Concert server is set up to use self-certification:

msxml3.dll: System Error: -2146697191
msxml3.dll: The system cannot locate the resource specified.

If you access the server with Microsoft Internet Explorer, you will get a certificate error message. The reason is that the client does not trust the server because the setup is self-certificate. To be able to use the sample script, you must resolve this problem first.

OSLC is an open community of software developers and organizations to standardize the integration of various software development lifecycle tools. It also defines specifications of tool integrations. The core specification is to use RDF (Resource Description Framework) as a representation of data and to use RESTful web services to access data. But My System provides its own interface. In this example it is COM+ (Component Object Model plus), which can be accessed by various languages including Microsoft Visual Basic or Visual Basic scripting language.

This article describes how to access both systems by using Visual Basic scripting language. The sample scripts are provided with this article (see the Downloads section). These sample scripts use the OSLC Change Management specification and Rational Team Concert as a tool. The script manipulates data called workitem. The script can create, update, or query a Rational Team Concert work item.


Overview of OSLC service and this Visual Basic script

Figure 2 shows a diagram of the flow of OSLC services, which go from the Root Service Document through the Catalog and Service Provider to the Work Item.

Figure 2. Overview of OSLC service
flow diagram

The first step is to access the Root Service Document. This service provides the service catalog. For example, it provides a CM (change Management) service catalog (shown in Figure 2), a SCM (source code management) service catalog, a Project Area management service catalog, and so on. In this example for this article:

  • CM provides access service to work items.
  • Catalog provides the service provider URL for each project area.
  • Service Provider enables access to Work Item.

The script uses a set of services called Microsoft XML Core Services (MSXML). MSXML can handle XML-based applications in a fast and efficient way. It also has various APIs to handle contents of XML documents. OSLC uses RDF as data representation, and MSXML can handle RDF documents, too.

Table 1 shows the basic functions to access work items that the script provides.

Table 1. Basic functions to manipulate a Rational Team Concert work item
FunctionDescription
JazzLogin() Log in to the Jazz™ Team Server, which hosts the Rational Team Concert application.
CreateWorkItem() Create a work item
UpdateWorkItem() Update a work item
QueryWorkItems() Query work items with conditions
CreateParentChild() Create parent and child relationship between work items

Note:
There are several additional functions in the script. This article explains how to use these functions to automate work item creation and updating. Then it explains how to integrate them with an existing system. Throughout this article, some of coding practice is omitted, such as comprehensive error-checking.


Sample script overview

Before going into how to run the sample scripts, take a look at Listing 1, which shows the main part of the script. This will help you understand how easy it is to access the Rational Team Concert work item interface by using the script.

Listing 1. Main part of a script
'--------------
' Parameter definition
' CLM parameters
	url = "https://clm.example.com:9443/ccm"
	project = "TRADITIONAL"
	userid = "jazzadmin"
	passwd = "jazzadmin"
'-------------

	' Login to jazz application server
	Set http = JazzLogin(url, userid, passwd)

	' obtain service catalog from jazz root service.
	' obtain workitem factory (use default factory) and query service
	' update service is given original URL, not service url
	service_url = GetServicebyProjectName(http, url, project)
	factory_service = GetFactoryService(http, service_url)
	update_service = GetUpdateService(http, url)
	query_service = GetQueryService (http, service_url)


	'attrString has format such that
	'<attribute>,<value>,<attribute>,<value>

	' Sample workitem create 
	attrString = "dcterms:type,task"
	attrString = attrString&","&"dcterms:title,This is sample title"

	workItemId = CreateWorkItem(http, factory_service, attrString)
	If (workItemId = -1) then
			WScript.ECHO "Workitem creation failed"
	End If


	' Sample workitem update
	attrString = "dcterms:title"&","&"This is sample title with update"

	workItemId = UpdateWorkItem(http, update_service, workItemId, attrString)
	If (workItemId = -1) then
		WScript.ECHO "Workitem update failed"
	End If

	' run query 
	set resultSet = QueryWorkItems(query_service, "dcterms:identifier="&workItemID,
"dcterms:title")

	' display result set
	call DisplayResultSet(resultSet)
	set resultSet = Nothing

	' Exit the script with return status 0 (zero)
	WScript.Quit 0

Using the script

In this section, you see how to use the script to access Rational Team Concert work items.

Log in to Rational Team Concert

The first step is to login to Rational Team Concert. The script provides a JazzLogin() function to do this.

Listing 2. Log in to Rational Team Concert
 ' Login to jazz application server
Set http = JazzLogin(url, userid, passwd)

The JazzLogin() function takes three arguments.

  • A url parameter is a URL for Rational Team Concert (for example, https://rtc-server.example.com/ccm).
  • The second and third arguments are the user ID and password to log n to Rational Team Concert.

Upon successful login, it returns a MSXML2.XMLHTTP object, which is basically an HTTP connection to the server.

Obtain OSLC services

Rational Team Concert provides various services. The script provides three functions to obtain them:

  • Get factory service: GetFactoryService() function
  • Work item update service: GetUpdateService() function
  • Work item query service: GetQueryService() function

Listing 3 shows a procedure to get work item services.

Listing 3. Sample code to obtain factory services
 service_url = GetServicebyProjectName(http, url, project)
factory_service = GetFactoryService(http, service_url)
update_service = GetUpdateService(http, url)
query_service = GetQueryService (http, service_url)

The first step is to obtain the service URL for a specified Rational Team Concert project. Figure 1 shows four steps. However, Step 1 to 3 are done within a single function, GetServicebyProjectName(). After obtaining the service URL, the GetFactoryService() function obtains a work item creation service.

Specify work item attributes

Before creating or updating a work item, attributes for the work item must be prepared. These attributes are created as a simple string in this format:

 <attribute1 >,<value1>,<attribute2>,<value2>,….

For example, when you want to create work item with just a title, the parameter should be this format:

 dcterms.title, This is a sample title

When you want to create a work item with a title and a description, specify the parameter this way:

 dcterms.title,This is title,dcterms.description, This is lengthy description

In the sample script, the argument is prepared as shown in Listing 4

Listing 4. Sample code to prepare the argument
attrString = "dcterms:type,task" 
attrString = attrString&","&"dcterms:title,This is sample title"

By specifying dcterms:type,task, the script creates a work item of a type called Task. When this parameter is changed to defect, it will create a Defect type of work item. To get a full list of work item attributes, see the Work Items Service provider for OSLC 2.0 CM Specification page on Jazz.net.

Create and update work item functions

Table 2 shows a list of work item create and update functions. The sample script also has a function to set a parent and child relationship between work items.

Table 2. Three functions provided for creating and updating a work item
FunctionDescription
CreateWorkItem(http, factory_service, attrString) This function creates a work item. It takes three arguments.

http is an HTTP connection to the server returned by the JazzLogin() function.

factory_service is a work item creation factory URL. This URL is obtained through the GetFactoryService() function.

attrString is a work item attribute.
UpdateWorkItem(http, update_service, workItemId, attrString) This function updates a work item. It takes four arguments.

http is an HTTP connection to the server returned by the JazzLogin() function.

update_service is a URL to update a work item.

workItemId is the ID number of a work item.

attrString is a work item attributes.
CreateParentChild (http, update_service, parentID, childIDs) CreateParentChild() creates a parent-child relationship between a work item specified by parentId and childIds. The childIDs is an array of child work items.

update_service is a URL to update a work item. This function internally calls the UpdateWorkItem() function.

In the sample script, create and update work item is used as shown in Listing 5 and Listing 6

Listing 5. Create a work item
workItemId = CreateWorkItem(http, factory_service, attrString)
Listing 6. Update a work item
workItemId = UpdateWorkItem(http, update_service, workItemId, attrString)

Query work items and display the query result

QueryWorkitems() and DisplayResultSet() can be used to query work items and display results of query.

The QueryWorkitems() function argument takes oslc.where and oslc.select in the second and third argument. To illustrate how these values can be constructed, imagine a database query language as in Listing 7.

Listing 7. A sample database query language
db> select id, title where id=100 from database

This query will return the a portion of record id and title where id matches the number 100. A QueryWorkitems() function behaves similarly. In the sample script, it is used like the code in Listing 8 (slightly modified to indicate that the script will query the work item where id=100).

Listing 8. Query work item of the identifier is equal to 100
set resultSet = QueryWorkItems(query_service, "dcterms:identifier=100”, "dcterms:title")

The query will return multiple work items, depending on the where clause. Because of that, the QueryWorkItems() function returns a collection object. The DisplayResultSet() function is prepared so that it can output the returned collection object in human-readable format. It is similar to most database query output.


Examples of uses of the sample script

Some parameters must be modified to try the sample script. Listing 9 shows the portion of script in which parameters are specified.

Listing 9. A parameter definition part of a script
' Parameter definition
' CLM parameters 
    url = "https://clm.example.com:9443/ccm" 
    project = "TRADITIONAL" 
    userid = "jazzadmin" 
    passwd = "jazzadmin"

Each parameter is explained in Table 3

Table 3. Explanation of parameters
ParameterExplanation
url Rational Team Concert server URL
project Name of a project within the Rational Team Concert repository
userid User ID to log in to the Jazz Team Server
passwd Password for the user ID

If you run the script, the result will look Listing 10.

Listing 10. Result output after running the script
 dos>cscript OSLC-utility.vbs
Microsoft (R) Windows Script Host Version 5.8
Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

503 This is sample title with update,503

Executing the script created work item 503 and updated the same work item. Figure 3 shows the actual work item GUI in the Eclipse client.

Figure 3. Actual work item GUI created by the script
Screen capture, work item in Rational Team ConcertScreen capture, work item in Rational Team Concert

Figure 3 shows portions of Overview and History tabs. The History tab Summary field shows that this work item has an update. It was "This is sample title," but it has been changed in the script to "This is sample title with update."


Ways to extended use of the script

You can extend the script for various uses. Listing 11 is a portion of script that creates a work item (parent) and nine child work items.

Listing 11. Create parent and 9 child work items
' Parent workitem create 
attrString = "dcterms:type,task"
attrString = attrString>",">"dcterms:title,This is parent"
	parentId = CreateWorkItem(http, factory_service, attrString)
' Create 9 child workitems
For counter = 1 to 9
	attrString = "dcterms:type,task"
	attrString = attrString>",">"dcterms:title,This is ">counter>" Child"
	childIds(counter-1) = CreateWorkItem(http, factory_service, attrString)
		
Next
	
' Then set child workitems to the parent
call CreateParentChild(http, update_service, parentId, childIds)

A work item is created before the loop as a parent work item. Then the script creates nine child work items. The work item ID is set to array. This parent and child work item are passed to the CreateParentChild() function. The GUI presentation of this script execution is shown in Figure 4.

Figure 4. Actual work item GUI result from the script
Screen shows Links segment with 9 child items

Figure 4 show that Links tab has links to child work items created by this script.


Integration with another system

So far, the script manipulated only work item creation and some updates, such as update work item information or add child work items. The core of this script is to provide the easiest way to integrate with an existing system. This integration should be called data exchange type of integration (Figure 5).

Figure 5. Integration strategy between My System and Rational Team Concert
Simple diagram of interaction between two systems

If the existing system has an interface such as COM+, it might provide an easier way to access Visual Basic scripting language. A typical interface should be similar to the code in Listing 12.

Listing 12. Typical Visual Basic code to access information in My System
Set app = CreateObject(“System.Application”) ' Create application object
Call app.login(“<user>”, “<password>”) ' Login to the system

set recordList = app.GetRecordList() ' Obtain list of records

' Loop to obtain information
For Each record In recordList
	' do something
Next

Call app.Quit() ' Terminate application.

In this pseudo sample, the application provides an interface to obtain entire records and then access each record in the loop. This sample can be extended to create Rational Team Concert work items, as Listing 13 shows.

Listing 13. Sample code extended to create work items in Rational Team Concert
Set app = CreateObject(“System.Application”)' Create application object
Call app.login(“<user>”, “<password>”) ' Login to the system

set recordList = app.GetRecordList() ' Obtain list of records

For Each record In recordList

	' convert record into attribute pairs
	attrString = ConvertRecord(record)

	Call CreateWorkItem(http, factory_service, attrString)

Next

Call app.Quit() ' Terminate application.

The loop has extended to call the ConvertRecord() pseudo function, which is expected to convert the My System record into attribute pairs. Then it is passed to the CreateWorkItem() function. In this example, all record information is integrated with Rational Team Concert. After this creation, it should be noted that the integration script should use the UpdateWorkItem() function to exchange data between My System and Rational Team Concert.

Ideally, the system should be integrated by linking rather than by data exchange. For more information about the linking type of integration, see the Eclipse Lyo project page on Eclipse.org. This project provides the SDK to implement the link type of integration.


Summary of technology used in the script

Because you might want to modify sample scripts from this article, this section explains two portions of the sample script. Listing 14 is code in the UpdateWorkItem() function.

Listing 14. A portion of the UpdateWorkItem() function
Set workItemDoc = CreateWorkItemDocument(attrString)

http.Open "PUT", update_url, False
http.setRequestHeader "Content-Type", "application/xml"
http.setRequestHeader "Accept", "application/xml"
http.setRequestHeader "OSLC-Core-Version", "2.0"
http.send(workItemDoc)

MSXML technology allows connecting to a web server in a simple way. For example, the first line in Listing 14 is to open an HTTP PUT request with the specified URL. The connection sends header information and then sends actual XML document created by the CreateWorkItemDocument() function. It is important to specify OSLC-Core-Version in the header to tell the Rational server to interact with OSLC V2.0 specification.

Various XML manipulation functions are used in the script. Listing 15 shows a portion of XML document manipulation.

Listing 15. A portion of XML document manipulation
 set doc = Http.ResponseXML
set elements = doc.getElementsByTagName("oslc_cm:ChangeRequest")

http.ResponseXML obtains an XML document object returned from the Rational Team Concert server. doc.getElementsByTabName() is used to find a tag in the XML document. By using this method, it is easy to find information associated with tag in the XML document. An alternative method is to use XPath, but this was not used in the sample scripts. For more information about MSXML (Microsoft XML Core Service), please see the MSXML documentation, which is available on MSDN.microsoft.com.


Acknowledgement

The author expresses sincere thanks to Paul Weiss and Ken Kumagai for their guidance in writing this article.


Download

DescriptionNameSize
Sample scripts and READMESample_Scripts_and_README.zip10KB

Resources

Learn

Get products and technologies

  • Download Rational Team Concert from Jazz.net and try it free on up to 10 projects for as long as you want (requires registration). If you'd prefer, you can try it in the sandbox instead, without installing it on your own system.
  • Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=832542
ArticleTitle=Integrate Rational Team Concert by using Visual Basic scripting language
publish-date=09042012