Contents


Integrate Rational Team Concert by using Visual Basic scripting language

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

Comments

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
Illustration of uses of the two separate systems

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 Downloadable resources 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
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 Concert
Screen 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
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
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.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

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