- 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
- Downloadable resources
- Related topics
Integrate Rational Team Concert by using Visual Basic scripting language
Use Rational Team Concert OSLC capabilities to integrate it with an existing system
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
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
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
|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|
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:
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"
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
|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
|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
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
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
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.
The author expresses sincere thanks to Paul Weiss and Ken Kumagai for their guidance in writing this article.
- Check these sources for more information related to this article:
- 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.
- 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.
- 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.