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).

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.

Back to top

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.

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.

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.

Back to top

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.

'--------------
' 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

Back to top

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.

 ' 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.

 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

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.

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

workItemId = CreateWorkItem(http, factory_service, attrString) 

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.

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).

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.

Back to top

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.

' Parameter definition
' CLM parameters 
    url = "https://clm.example.com:9443/ccm" 
    project = "TRADITIONAL" 
    userid = "jazzadmin" 
    passwd = "jazzadmin" 

Each parameter is explained in Table 3

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

 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 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."

Back to top

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.

' 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 show that Links tab has links to child work items created by this script.

Back to top

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).

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.

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.

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.

Back to top

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.

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.

 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.

Back to top

Acknowledgement

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

Back to top

Download

Information about download methods

Resources

Learn

• Check these sources for more information related to this article:
  • Open Services for Lifecycle Collaboration (OSLC)
  • OSLC Change Management V2.0 specification
  • Rational Team Concert implementation of OSLC CM V2.0
  • Microsoft XML Core Services (MSXML) and MSXML reference
  • Eclipse Lyo Project information page
  
  
• For more about Rational Team Concert:
  • Find Rational Team Concert articles and links to many other resources on IBM developerWorks, and check the product overview page, features and benefits, system requirements, and the user information center.
  • Check the Rational Team Concert page on Jazz.net.
  • Watch the Using Rational Team Concert in a globally distributed team webcast or a demonstration of the Dashboards and reports, or listen to the podcast about IBM Rational Team Concert and Jazz.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  
  
• Subscribe to the developerWorks weekly email newsletter, and choose the topics to follow. Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
  
  

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

• Get connected. Join the Rational community to share your Rational software expertise and get connected with your peers.
  
  
• Rate or review Rational software. It's quick and easy.
  
  
• Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
  
  
• Follow Rational software on Facebook, Twitter (@ibmrational), and YouTube, and add your comments and requests.
  
  
• Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.
  
  

About the author

Takehiko 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.

Rate this article

Comments

Back to top

Table of contents

• Scenario
• Overview of OSLC service and this Visual Basic script
• Sample script overview
• Using the script
• Examples of uses of the sample script
• Ways to extended use of the script
• Integration with another system
• Summary of technology used in the script
• Acknowledgement
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Team Concert
• Demo: Rational and Jazz
• Webcast: Agile development with IBM Rational Synergy and IBM Rational Team Concert
• Buy: Rational Team Concert

Dig deeper into Rational on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers