How to consume the Rational Team Concert change management services

Published/Last Updated: November 12, 2009
Build basis: Rational Team Concert 2.0
Author: Martin Aeschlimann, IBM Rational

Introduction

Open Services for Lifecycle Collaboration (also known as OSLC or Open Services) is a community effort to define common APIs to software lifecycle tools such as change, requirement and quality-management systems. Rational Team Concert (RTC) 2.0 implements the OSLC 1.0 specification for change management systems (OSLC CM). Change management systems deal with change requests: bug reports, defects and enhancement requests. In RTC these are called work items. Applications interested in the integration with RTC’s work items can now use the OSLC CM interface to access work items in a well defined manner that also works with other OSLC CM-compliant change management systems. Change requests can be queried, created and modified programmatically, but also through user interface dialogs such as pickers and creation dialogs provided by the change management systems. OSLC relies on standard Web technologies such as HTTP, JSON, XML and HTML.

This article shows how your application can integrate with OSLC CM compliant systems using the example of RTC. It demonstrates how to access the RTC work items, how to query items and how to embed RTC’s work item picker and creation dialogs in your product.

OSLC CM
OSLC CM and RTC
Change Request Resource Specification
Service Discovery
OSLC Services
Conclusion
References

OSLC CM

OSLC CM allows other tools to easily create, find, and retrieve records in a CM system through RESTful APIs. The first completed specification is OSLC CM 1.0; a version 2.0 is in the works.

In a nutshell OSLC CM 1.0 consists of the following parts:

Change request resource specification
OSLC CM defines change request representations in XML and JSON. RESTful operations can be used to access and modify resources. OSLC CM 1.0 defines a minimal set of standardized attributes, but does not describe the details of the CM system’s underlying schemas, required attributes, and other process rules.
Change management services
OSLC CM defines a set of services that can or must be offered by OSLC CM systems. This includes services to find and create change requests programmatically but also through creation and selection dialogs offered by the CM system (‘delegated creation’). Services are addressable through service URI’s and can return results in XML, JSON, ATOM and HTML.
Change management service discovery
OSLC CM defines how services are provided by CM systems so they can be discovered by tools interested to integrate with the CM tool. It introduces a CM system ‘context’ (‘project area’ in RTC) that offers to group CM resources and their operations.

OSLC CM and RTC

Rational Team Concert (RTC) 2.0 implements OSLC CM 1.0. The RTC work items can be accessed through the OSLC CM resource interfaces. RTC implements OSLC CM service discovery and makes available its creation and query services including creation and selection dialog.

This article demonstrates OSLC CM using the example of RTC. The goal is to offer an introduction to OSLC CM and show how tools can use the OSLC CM specification to access RTC work items in a standardized way. As services and resources are all based on web technologies such as HTTP, JSON, XML and HTML, it is easy to experiment and play with the specification using a variety of tools. To follow the examples, start an RTC repository and create a sample project area with some test items. The examples assume that the RTC repository is running on https://rtc:9443/jazz; fill in your host name for ‘rtc’.

To make the REST calls use Firefox with an add-on like Poster, or use standalone REST utilities like curl or HTTP4e.

Change Request Resource Specification

Resource Representation Overview

A change request resource in OSLC is identified by an URI.

It is up to the change management system to define the URI representation
Clients must not make assumptions on how the URI is composed and must not try to parse and reconstruct a URI to get, for example, the URI of a different resource
A change management system can use more than one URI to identify the same resource. But the resource content typically defines a canonical URI for the given resource

RESTful operations GET, PUT and DELETE can be used to access the resource.

GET returns the content of the resource
PUT overwrites the resource with a new content
DELETE deletes the resource. Note: The OSLC CM spec does not require change management systems to support deletion of change requests, but they can optionally support this capability
POST is only allowed on collections. You will see an example below.

OSLC CM defines two change request representations: XML and JSON (JavaScript Object Notation)

To get the XML representation of a resource use application/x-oslc-cm-change-request+xml in the Accept header
For the JSON representation use application/x-oslc-cm-change-request+json in the Accept header

The resource representations consist of attributes and attribute collections.

OSLC CM defines how the attributes and attributes are represented in XML and JSON and how they can be modified
OSLC CM 1.0 defines a minimal set of standardized attributes. The CM system adds additional attributes and attribute collections which can also be accessed and modified if known to a client
OSLC CM 1.0 does not describe the details of the CM system’s underlying schemas, required attributes, and other process rules. Modifications might fail if a modification violates a constraint like a required attribute
Attribute collections are represented as a collection resource. RESTful operations can be used for its access and modification.
In the JSON representation attribute collections are inlined and represented as an array.
The resource operations like GET and PUT support partial resource representations. Callers can define an attribute profile to select a smaller set of attributes that is returned or set

Resource Representation in XML

Let’s look how this is done in RTC.

We have a work item and have its resource URI. The first operation we’re doing is a GET.

GET https://rtc.com:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_0J39QJu-Ed6cerS9lb5AWw
Accept: application/x-oslc-cm-change-request+xml

Note: it is important to define the accept header and define the content type of the returned element. A resource URI is typically used for other resource representations as well.

The call returns:

<?xml version="1.0" encoding="UTF-8"?>
<oslc_cm:ChangeRequest
  xmlns:rtc_cm="https://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"
  xmlns:dc="http://purl.org/dc/terms/" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
  xmlns:jp="https://jazz.net/xmlns/prod/jazz/presentation/1.0/" xmlns:jd="https://jazz.net/xmlns/prod/jazz/discovery/1.0/"
  xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:calm="https://jazz.net/xmlns/prod/jazz/calm/1.0/">
  <dc:type rdf:resource="https://rtc:9443/jazz/oslc/types/_gasc4Ju-Ed6cerS9lb5AWw/defect"/>
  <dc:identifier>9</dc:identifier>
  <dc:created>2009-09-07T14:59:06.333Z</dc:created>
  <dc:creator rdf:resource="https://rtc:9443/jazz/oslc/users/_6I8ZMJu9Ed6cerS9lb5AWw"/>
  <dc:title>My First Bug</dc:title>
  <dc:description>This is my first bug</dc:description>
  <dc:subject/>
  <dc:modified>2009-09-07T14:59:06.348Z</dc:modified>
  <oslc_cm:priority rdf:resource="https://rtc:9443/jazz/oslc/enumerations/_gasc4Ju-Ed6cerS9lb5AWw/priority/priority.literal.l01"/>
  <oslc_cm:severity rdf:resource="https://rtc:9443/jazz/oslc/enumerations/_gasc4Ju-Ed6cerS9lb5AWw/severity/severity.literal.l3"/>
  <rtc_cm:comments oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:comments"/>
  <rtc_cm:state rdf:resource="https://rtc:9443/jazz/oslc/workflows/_gasc4Ju-Ed6cerS9lb5AWw/states/com.ibm.team.workitem.defectWorkflow/1"/>
  <rtc_cm:resolution/>
  <rtc_cm:filedAgainst rdf:resource="https://rtc:9443/jazz/resource/itemOid/com.ibm.team.workitem.Category/_hckJkpu-Ed6cerS9lb5AWw"/>
  <rtc_cm:correctedEstimate/>
  <rtc_cm:due/>
  <rtc_cm:estimate/>
  <rtc_cm:foundIn/>
  <rtc_cm:subscribers oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:subscribers"/>
  <rtc_cm:modifiedBy rdf:resource="https://rtc:9443/jazz/oslc/users/_6I8ZMJu9Ed6cerS9lb5AWw"/>
  <rtc_cm:ownedBy rdf:resource="https://rtc:9443/jazz/oslc/users/_YNh3MOlsEdq4xpiOKg5hvA"/>
  <rtc_cm:projectArea rdf:resource="https://rtc:9443/jazz/oslc/projectareas/_gasc4Ju-Ed6cerS9lb5AWw"/>
  <rtc_cm:resolved/>
  <rtc_cm:resolvedBy rdf:resource="https://rtc:9443/jazz/oslc/users/_YNh3MOlsEdq4xpiOKg5hvA"/>
  <rtc_cm:startDate/>
  <rtc_cm:plannedFor/>
  <rtc_cm:timeSpent/>  
  <rtc_cm:teamArea rdf:resource="https://rtc:9443/jazz/oslc/teamareas/_hY_RIJu-Ed6cerS9lb5AWw"/>
  <rtc_cm:com.ibm.team.connector.ccbridge.common.act2wi.s oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.connector.ccbridge.common.act2wi.s"/>
  <rtc_cm:com.ibm.team.build.linktype.includedWorkItems.com.ibm.team.build.common.link.includedInBuilds oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.build.linktype.includedWorkItems.com.ibm.team.build.common.link.includedInBuilds"/>
  <oslc_cm:relatedChangeManagement oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/oslc_cm:relatedChangeManagement"/>
  <calm:blocksTestExecutionRecord oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/calm:blocksTestExecutionRecord"/>
  <calm:affectsExecutionResult oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/calm:affectsExecutionResult"/>
  <calm:implementsRequirement oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/calm:implementsRequirement"/>
  <calm:testedByTestCase oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/calm:testedByTestCase"/>
  <rtc_cm:com.ibm.team.workitem.linktype.textualReference.textuallyReferenced oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.textualReference.textuallyReferenced"/> 
  <rtc_cm:com.ibm.team.workitem.linktype.attachment.attachment oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.attachment.attachment"/>
  <rtc_cm:com.ibm.team.workitem.linktype.relatedartifact.relatedArtifact oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.relatedartifact.relatedArtifact"/>
  <rtc_cm:com.ibm.team.build.linktype.reportedWorkItems.com.ibm.team.build.common.link.reportedAgainstBuilds oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.build.linktype.reportedWorkItems.com.ibm.team.build.common.link.reportedAgainstBuilds"/>
  <rtc_cm:com.ibm.team.workitem.linktype.relatedworkitem.related oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.relatedworkitem.related"/>
  <rtc_cm:com.ibm.team.scm.svn.linkType.workItem.s oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.scm.svn.linkType.workItem.s"/>
  <rtc_cm:com.ibm.team.workitem.linktype.copiedworkitem.copies oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.copiedworkitem.copies"/>
  <rtc_cm:com.ibm.team.workitem.linktype.copiedworkitem.copiedFrom oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.copiedworkitem.copiedFrom"/>
  <rtc_cm:com.ibm.team.workitem.linktype.blocksworkitem.blocks oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.blocksworkitem.blocks"/>
  <rtc_cm:com.ibm.team.workitem.linktype.blocksworkitem.dependsOn oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.blocksworkitem.dependsOn"/>
  <rtc_cm:com.ibm.team.workitem.linktype.duplicateworkitem.duplicates oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.duplicateworkitem.duplicates"/>
  <rtc_cm:com.ibm.team.workitem.linktype.duplicateworkitem.duplicateOf oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.duplicateworkitem.duplicateOf"/>
  <rtc_cm:com.ibm.team.filesystem.workitems.change_set.com.ibm.team.scm.ChangeSet oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.filesystem.workitems.change_set.com.ibm.team.scm.ChangeSet"/>
  <rtc_cm:com.ibm.team.workitem.linktype.parentworkitem.parent oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.parentworkitem.parent"/>
  <rtc_cm:com.ibm.team.workitem.linktype.parentworkitem.children oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.parentworkitem.children"/>
</oslc_cm:ChangeRequest>

You can see from the response, that different kinds of attributes are used:

Some attributes are defined by OSLC CM. These attributes are listed in the Change Management Resources Definition document and typically use the namespace dc and oslc_cm
```
<dc:title>My First Bug</dc:title>
```

All other attributes are not standardized in OSLC CM and are RTC specific

<rtc_cm:state rdf:resource="https://rtc:9443/jazz/oslc/workflows/_gasc4Ju-Ed6cerS9lb5AWw/states/com.ibm.team.workitem.defectWorkflow/1"/>

Some attributes reference other resources

<rtc_cm:filedAgainst rdf:resource="https://rtc:9443/jazz/resource/itemOid/com.ibm.team.workitem.Category/_hckJkpu-Ed6cerS9lb5AWw"/>

Some attributes reference attribute collections

<oslc_cm:relatedChangeManagement oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/oslc_cm:relatedChangeManagement"/>

Partial Resource Representation

To avoid the transfer of a large number of attributes you can use an attribute profile as an additional request parameter. The attribute profile specifies a subset of attributes. The response will be a partial representation of the resource and only contain the attributes from the attribute profile.

oslc_cm.properties=dc:title,rtc_cm:comments

The request and result look as follows:

GET https://rtc.com:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_0J39QJu-Ed6cerS9lb5AWw?oslc_cm.properties=dc:title,rtc_cm:comments
Accept: application/x-oslc-cm-change-request+xml

<oslc_cm:ChangeRequest
  xmlns:rtc_cm="https://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"
  xmlns:dc="http://purl.org/dc/terms/" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
  xmlns:jp="https://jazz.net/xmlns/prod/jazz/presentation/1.0/" xmlns:jd="https://jazz.net/xmlns/prod/jazz/discovery/1.0/"
  xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:calm="https://jazz.net/xmlns/prod/jazz/calm/1.0/">

  <dc:title>My First Bug</dc:title>
  <rtc_cm:comments oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:comments"/>

</oslc_cm:ChangeRequest>

Collection Resources

Attribute collections are resources that can be accessed using GET:

GET https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:comments
Accept: application/x-oslc-cm-change-request+xml

<?xml version="1.0" encoding="UTF-8"?>
<oslc_cm:Collection
   xmlns:rtc_cm="https://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"
   xmlns:dc="http://purl.org/dc/terms/" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
   xmlns:jp="https://jazz.net/xmlns/prod/jazz/presentation/1.0/" xmlns:jd="https://jazz.net/xmlns/prod/jazz/discovery/1.0/"
   xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" xmlns:atom="http://www.w3.org/2005/Atom"
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:calm="https://jazz.net/xmlns/prod/jazz/calm/1.0/"
  oslc_cm:totalCount="2">

  <rtc_cm:Comment rdf:resource="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:comments/0">
    <dc:created>2009-09-07T15:57:51.614Z</dc:created>
    <dc:creator rdf:resource="https://rtc:9443/jazz/oslc/users/_6I8ZMJu9Ed6cerS9lb5AWw"/>
    <dc:description>My first comment</dc:description>
  </rtc_cm:Comment>
  <rtc_cm:Comment rdf:resource="https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:comments/1">
    <dc:created>2009-09-07T15:57:59.505Z</dc:created>
    <dc:creator rdf:resource="https://rtc:9443/jazz/oslc/users/_6I8ZMJu9Ed6cerS9lb5AWw"/>
    <dc:description>My second comment</dc:description>
  </rtc_cm:Comment>
</oslc_cm:Collection>

It is recommended to use an attribute profile to limit the result to a subset of attributes. As explained above, this is done with using the oslc_cm.properties parameter.

Here is an example of the resource collection for related work items:

GET https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:com.ibm.team.workitem.linktype.relatedworkitem.related?oslc_cm.properties=dc:title,rtc_cm:comments
Accept: application/x-oslc-cm-change-request+xml

<?xml version="1.0" encoding="UTF-8"?>
<oslc_cm:Collection
  xmlns:rtc_cm="https://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"
  xmlns:dc="http://purl.org/dc/terms/" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
  xmlns:jp="https://jazz.net/xmlns/prod/jazz/presentation/1.0/" xmlns:jd="https://jazz.net/xmlns/prod/jazz/discovery/1.0/"
  xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:calm="https://jazz.net/xmlns/prod/jazz/calm/1.0/"
  oslc_cm:totalCount="2">

  <oslc_cm:ChangeRequest rdf:resource="https://rtc:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_CD62QJu_Ed6cerS9lb5AWw"
    oslc_cm:label="10: My Second Bug">

    <dc:title>My Second Bug</dc:title>
    <rtc_cm:comments oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_CD62QJu_Ed6cerS9lb5AWw/rtc_cm:comments"/>
  </oslc_cm:ChangeRequest>

  <oslc_cm:ChangeRequest rdf:resource="https://rtc:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_7Z5cAJvDEd6cerS9lb5AWw"
    oslc_cm:label="11: My Third Bug">

    <dc:title>My Third Bug</dc:title>
    <rtc_cm:comments oslc_cm:collref="https://rtc:9443/jazz/oslc/workitems/_7Z5cAJvDEd6cerS9lb5AWw/rtc_cm:comments"/>
  </oslc_cm:ChangeRequest>

</oslc_cm:Collection>

Resource Representation in JSON

OSLC also offers a change request representation in JSON. JSON is easier to consume, especially in JavaScript.

The JSON representation has some differences to the XML representation

The JSON representation does not declare any namespaces, but uses the common namespace prefixes
Collection attributes do not point to a collection resource, but directly contain the array of referenced resources (‘inlined representation’)

To illustrate this, we do the previous call with application/x-oslc-cm-change-request+json as Accept header. In addition, we define an attribute profile including title, comments and related work items.

GET https://rtc.com:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_0J39QJu-Ed6cerS9lb5AWw?oslc_cm.properties=dc:title,rtc_cm:comments,rtc_cm:com.ibm.team.workitem.linktype.relatedworkitem.related
Accept: application/x-oslc-cm-change-request+json

{
   "dc:title":"My First Bug",
   "rdf:resource":"https://rtc:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_0J39QJu-Ed6cerS9lb5AWw",
   "rtc_cm:comments":[
      {
         "rdf:resource":"https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:comments/0"
      },
      {
         "rdf:resource":"https://rtc:9443/jazz/oslc/workitems/_0J39QJu-Ed6cerS9lb5AWw/rtc_cm:comments/1"
      }
   ]

   "rtc_cm:com.ibm.team.workitem.linktype.relatedworkitem.related":[
      {
         "rdf:resource":"https://rtc:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_CD62QJu_Ed6cerS9lb5AWw",
         "oslc_cm:label":"10: My Second Bug"
      },
      {
         "rdf:resource":"https://rtc:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_7Z5cAJvDEd6cerS9lb5AWw",
         "oslc_cm:label":"11: My Third Bug"
      }
   ]
}

Updating a Change Request

The steps to update a change request are as follows:

Get a change request representation in JSON or XML
Modify it by adding, removing or changing values
Send the modified representation back to the originating URL by using PUT

Note the following:

Avoid overwriting changes done by someone else: A change request may have changed in the time between fetching it, doing modifications and sending it back. In general, clients should not blindly overwrite the work item contents, but make sure that the changes are applied to the state that they fetched from the server. This is done by including the ETag received on load in the If-Match header when PUTting the work item back to the server. If the state on the server is still the same, the update will succeed with a 200 OK status. If the work item was modified in the meantime, it will fail with a 412 Precondition Failed status.
Partial Updates: PUT generally has the semantics of updating the entire resource (and removing what is not included). To perform a partial update you can specify a subset of properties to update using the oslc_cm.properties parameter. PUT will modify all the attributes that are contained in the subset: Attributes are either set to the value defined in the request, or will be removed if not included in the request.

This example updates the bug summary and shows the usage of the ETag. The ETag is received with the response header and used again in the PUT. The PUT will only succeed if the resource has not changed since the GET.

GET https://rtc.com:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_0J39QJu-Ed6cerS9lb5AWw?oslc_cm.properties=dc:title
Accept: application/x-oslc-cm-change-request+xml

ETag: "_1am9cFm0Ed6ELJg2MQ68Kg"

<oslc_cm:ChangeRequest
  xmlns:rtc_cm="https://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"
  xmlns:dc="http://purl.org/dc/terms/" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
  xmlns:jp="https://jazz.net/xmlns/prod/jazz/presentation/1.0/" xmlns:jd="https://jazz.net/xmlns/prod/jazz/discovery/1.0/"
  xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:calm="https://jazz.net/xmlns/prod/jazz/calm/1.0/">

  <dc:title>My First Bug</dc:title>

</oslc_cm:ChangeRequest>

The second call is using the ETag received in the first call:

PUT https://rtc.com:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_0J39QJu-Ed6cerS9lb5AWw?oslc_cm.properties=dc:title
Accept: application/x-oslc-cm-change-request+xml
If-Match: _1am9cFm0Ed6ELJg2MQ68Kg
Content-Type: application/x-oslc-cm-change-request+xml

<oslc_cm:ChangeRequest
  xmlns:dc="http://purl.org/dc/terms/" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
  xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/">

  <dc:title>My First Major Bug</dc:title>

</oslc_cm:ChangeRequest>

Modifying a Collection Resource

Modifying a collection, for example the list of comments or the list of related work items, is done the same way as described above: A GET followed by a PUT. In addition it is possible to add a new collection entry with a POST to the collection resource.

Removing a collection entry must be done with a GET/PUT as described above.

More examples and more details about resource modification can be found in RTC’s Resource Oriented Work Item API 2.0. Note: this WIKI entry describes some RTC specific operations not standardized by OSLC CM.

Security and Authentication

Often, accessing and modifying resources requires authentication. Operations might be restricted based on the rights of the user. The same applies to resource representations. They can differ depending on the logged-in user.

OSLC CM specifies that implementers should support:

HTTP basic authentication
HTTP basic authentication specifies how providers signal that authorization is required and how clients provide credentials when making a request.
OAuth
With OAuth a user can allow a server A to access change requests on server B using the user’s access rights. To do this, an access token is used. No user credentials are passed to server A.
HTTPS
HTTPS encrypts communication and provides secure identification of the accessed services

Service Discovery

Clients that want to interact with a Change Management system need a mechanism for discovering its capabilities, and the URLs used to access the capabilities.

There are several aspects to the discovery process:

First, clients may need to discover the existence of the Change Management system itself
Next, clients need to discover the contexts in which change requests may exist, often referred to as projects or user databases (e.g. ClearQuest)
Finally, clients need to discover the services that are provided within that context

The first step consists of getting the pointer to the OSLC CM service catalog. In Jazz Foundation this is done through the root service document, which contains references to the OSLC service catalog if the application implements an OSLC specification.

The service catalog lists all contexts and provides a service document for each context. Finally, the service document contains the pointers to the actual services, such as a work item query service.

This leads to the following service document hierarchy:

Clients should not rely on specific URLs or perform ‘path math’ on URLs. Instead, they should use the discovery chain defined by OSLC. All clients need to know is the URL of the root service document.

Root Services Document

Products built on Jazz provide a root services document. The document lists pointers to OSLC service catalogs as well as to other Jazz services. The root services document is Jazz specific and not part of OSLC. It is available at ‘/rootservices’ under in the Jazz web application root in all products based on Jazz Foundation 1.0 or later. The specification of the Jazz root service document can be found on https://jazz.net/wiki/bin/view/Main/RootServicesSpec.

In our example of a RTC server with repository URL https://rtc:9443/jazz, the root service document URL is https://rtc:9443/jazz/rootservices

A GET request to this resource returns a XML document in the following form:

<rdf:Description rdf:about="https://rtc:9443/jazz/rootservices">
   ...
   <oslc_cm:cmServiceProviders rdf:resource="https://rtc:9443/jazz/oslc/workitems/catalog"/>
   ...
</rdf:Description>

If the server is an OSLC CM service provider, it will specify an entry oslc_cm:cmServiceProviders as shown above. Likewise, an OSLC quality management system will contain an entry oslc_qm:qmServiceProviders, a requirements management system oslc_rm:rmServiceProviders.

Following the URL specified in the service provider element will bring us to the OSLC service catalog.

OSLC Service Catalog

Change management systems can group their change requests into separate contexts, and each context has its own service document. The service catalog lists all ‘contexts’ of an application. Contexts correspond to project areas in RTC, so in the case of RTC, the service catalog lists all project areas.

OSLC applications can also nest contexts. Applications can also choose to not provide any contexts at all. Consult the Service Discovery section in the OSLC CM Service Description specification for the full information on how to follow service catalogs to find a service document. Also see the OSLC Service Catalog specification for more details on service catalogs.

In our example, a GET to https://rtc:9443/jazz/oslc/workitems/catalog will return the following response:

<?xml version="1.0" encoding="UTF-8" ?>

<oslc_disc:ServiceProviderCatalog
  xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"
  xmlns:dc="http://purl.org/dc/terms/"
  xmlns:jd="https://jazz.net/xmlns/prod/jazz/discovery/1.0/"
  xmlns:jp="https://jazz.net/xmlns/prod/jazz/process/1.0/"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  rdf:about="https://rtc:9443/jazz/oslc/workitems/catalog.xml">
  <dc:title>Project Areas</dc:title>
  <oslc_disc:entry>
    <oslc_disc:ServiceProvider>
      <dc:title>MyProject</dc:title> 
      <oslc_disc:details rdf:resource="https://rtc:9443/jazz/process/project-areas/_gasc4Ju-Ed6cerS9lb5AWw"/> 
      <oslc_disc:services rdf:resource="https://rtc:9443/jazz/oslc/contexts/_gasc4Ju-Ed6cerS9lb5AWw/workitems/services.xml"/> 
      <jp:consumerRegistry rdf:resource="https://rtc:9443/jazz/process/project-areas/_gasc4Ju-Ed6cerS9lb5AWw/links"/> 
    </oslc_disc:ServiceProvider>
  </oslc_disc:entry>
  <oslc_disc:entry>
    <oslc_disc:ServiceProvider>
      <dc:title>Blue Project</dc:title> 
      <oslc_disc:details rdf:resource="https://rtc:9443/jazz/process/project-areas/_S3zYEJ4NEd6vEvRAo2erQg"/> 
      <oslc_disc:services rdf:resource="https://rtc:9443/jazz/oslc/contexts/_S3zYEJ4NEd6vEvRAo2erQg/workitems/services.xml"/> 
      <jp:consumerRegistry rdf:resource="https://rtc:9443/jazz/process/project-areas/_S3zYEJ4NEd6vEvRAo2erQg/links"/> 
    </oslc_disc:ServiceProvider>
  </oslc_disc:entry>
</oslc_disc:ServiceProviderCatalog>

As you can see in our example, there are currently two contexts named ‘MyProject’ and ‘Blue Project’, corresponding to the project areas in the example RTC repository.

Both catalog entries contain a link to a OSLC service document in oslc_disc:services.

OSLC CM Service Document

Finally we have the address to an OSLC CM service document. The OSLC CM service document is a XML document describing all services offered for the given context.

In our example we use the service document of project ‘MyProject’ and do a GET on https://rtc:9443/jazz/oslc/contexts/_gasc4Ju-Ed6cerS9lb5AWw/workitems/services.xml:

<?xml version="1.0" encoding="UTF-8" ?> 
<oslc_cm:ServiceDescriptor
  xmlns:dc="http://purl.org/dc/terms/"
  xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:calm="https://jazz.net/xmlns/prod/jazz/calm/1.0/"
  rdf:about="https://rtc:9443/jazz/oslc/contexts/_gasc4Ju-Ed6cerS9lb5AWw/workitems/services.xml">
  <dc:title>MyProject</dc:title> 
    <dc:description>IBM Rational Team Concert OSLC CM Service Description for Project 'MyProject'</dc:description> 
    <dc:contributor>
      <dc:title>IBM Rational Team Concert Work Items</dc:title> 
      <dc:identifier>com.ibm.team.workitem</dc:identifier>        
      <oslc_cm:icon>https://rtc:9443/jazz/web/com.ibm.team.rtc.web/ui/graphics/UICustomizations/RationalTeamConcert.ico</oslc_cm:icon>
    </dc:contributor>

    <oslc_cm:changeRequests oslc_cm:version="1.0">
      <oslc_cm:home>
        <dc:title>Work Items Home</dc:title> 
        <oslc_cm:url>https://rtc:9443/jazz/web/projects/MyProject#action=jazz.viewPage&id=com.ibm.team.workitem</oslc_cm:url>
      </oslc_cm:home>

      <oslc_cm:factory oslc_cm:default="true">
        <dc:title>Default location for creation of change requests</dc:title> 
        <oslc_cm:url>https://rtc:9443/jazz/oslc/contexts/_gasc4Ju-Ed6cerS9lb5AWw/workitems</oslc_cm:url>
      </oslc_cm:factory>

      <oslc_cm:factory calm:id="drafts">
        <dc:title>Location for creation of draft change requests</dc:title> 
        <oslc_cm:url>https://rtc:9443/jazz/oslc/contexts/_gasc4Ju-Ed6cerS9lb5AWw/drafts/workitems</oslc_cm:url>
      </oslc_cm:factory>

      <oslc_cm:simpleQuery>
        <dc:title>CQL based change request queries</dc:title> 
        <oslc_cm:url>https://rtc:9443/jazz/oslc/contexts/_gasc4Ju-Ed6cerS9lb5AWw/workitems</oslc_cm:url>
      </oslc_cm:simpleQuery>

      <oslc_cm:creationDialog oslc_cm:default="true" calm:id="defect" oslc_cm:hintWidth="740px" oslc_cm:hintHeight="510px">
        <dc:title>New Defect</dc:title> 
        <oslc_cm:url>https://rtc:9443/jazz/_ajax-modules/com.ibm.team.workitem.WICreationDialog?projectAreaName=MyProject&dc%3Atype=defect</oslc_cm:url>
      </oslc_cm:creationDialog>

      <oslc_cm:creationDialog calm:id="planItem" oslc_cm:hintWidth="740px" oslc_cm:hintHeight="510px">
        <dc:title>New Plan Item</dc:title> 
        <oslc_cm:url>https://rtc:9443/jazz/_ajax-modules/com.ibm.team.workitem.WICreationDialog?projectAreaName=MyProject&dc%3Atype=com.ibm.team.apt.workItemType.story</oslc_cm:url>
      </oslc_cm:creationDialog>

      <oslc_cm:selectionDialog oslc_cm:default="true" oslc_cm:hintWidth="550px" oslc_cm:hintHeight="360px">
        <dc:title>Work Item Selection</dc:title> 
        <oslc_cm:url>https://rtc:9443/jazz/_ajax-modules/com.ibm.team.workitem.WIPicker?projectAreaName=MyProject</oslc_cm:url>
      </oslc_cm:selectionDialog>

      <oslc_cm:selectionDialog calm:id="defect" oslc_cm:hintWidth="550px" oslc_cm:hintHeight="360px">
        <dc:title>Defect Selection</dc:title> 
        <oslc_cm:url>https://rtc:9443/jazz/_ajax-modules/com.ibm.team.workitem.WIPicker?projectAreaName=MyProject&dc%3Atype=defect</oslc_cm:url>
      </oslc_cm:selectionDialog>

      <oslc_cm:selectionDialog calm:id="planItem" oslc_cm:hintWidth="550px" oslc_cm:hintHeight="360px">
        <dc:title>Plan Item Selection</dc:title> 
        <oslc_cm:url>https://rtc:9443/jazz/_ajax-modules/com.ibm.team.workitem.WIPicker?projectAreaName=MyProject&dc%3Atype=com.ibm.team.apt.workItemType.story</oslc_cm:url>
      </oslc_cm:selectionDialog>


      <calm:filter calm:id="openItems">
        <dc:title>Open Change Requests Filter</dc:title> 
        <calm:url>https://rtc:9443/jazz/oslc/calm-filter/_gasc4Ju-Ed6cerS9lb5AWw/openItems</calm:url>
      </calm:filter>
      <calm:filter calm:id="resolvedItems">
        <dc:title>Resolved Change Requests Filter</dc:title>          
        <calm:url>https://rtc:9443/jazz/oslc/calm-filter/_gasc4Ju-Ed6cerS9lb5AWw/resolvedItems</calm:url>
        </calm:filter>
      <calm:filter calm:id="readyForTesting">
        <dc:title>Ready for Testing Change Requests Filter</dc:title>
        <calm:url>https://rtc:9443/jazz/oslc/calm-filter/_gasc4Ju-Ed6cerS9lb5AWw/readyForTesting</calm:url>
      </calm:filter>
    </oslc_cm:changeRequests>
</oslc_cm:ServiceDescriptor>

OSLC Services

The example above shows the service document returned by RTC. It includes services specified by OSLC CM, but also services that are RTC specific.

The oslc_cm:changeRequests node contains all services related to change requests:

home provides an URL to the main Web UI which clients may use to navigate to
factory provides an URL to create new change requests
simpleQuery provides an URL for work item queries
creationDialog is a creation dialog that products can embed in their user interface
selectionDialog is a selection dialog (‘picker’) that products can embed in their user interface
filter is a RTC specific extension to query requests for a given state

Each service can be offered multiple times. OSLC CM clients should take the instance marked with oslc_cm:default="true". All other instances are RTC specific and can be differentiated by the RTC attribute calm:id

We briefly describe these services in the following sections. For more documentation see the OSLC CM service document specification.

Create a Change Request

There are two possibilities to create a change request:

Use the ‘factory’ service to create a change request programmatically
Use the ‘creationDialog’ service to create a change request with a creation dialog provided by the OSLC CM provider. We call this ‘delegated creation’.

A change request can be created as follows: Construct a change request description using the OSLC change request description described in the chapter Change Request Resource Specification

Then POST this description to the factory service URI. The representation of the newly created resource is returned and contains the URI of new resource.

POST https://rtc:9443/jazz/oslc/contexts/_gasc4Ju-Ed6cerS9lb5AWw/workitems
Content-Type: application/x-oslc-cm-change-request+xml

<oslc_cm:ChangeRequest
  xmlns:dc="http://purl.org/dc/terms/" 
  xmlns:rtc_cm="https://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/">
  <dc:title>A new Bug</dc:title>
  <dc:description>This is new bug</dc:description>
  <dc:type rdf:resource="https://rtc:9443/jazz/oslc/types/_gasc4Ju-Ed6cerS9lb5AWw/defect"/>
  <rtc_cm:filedAgainst rdf:resource="https://rtc:9443/jazz/resource/itemOid/com.ibm.team.workitem.Category/_hckJkpu-Ed6cerS9lb5AWw"/>
</oslc_cm:ChangeRequest>

The creation service will only create the change request if the description contains all required attributes. The required attributes are defined by the change management system. In the case of RTC, required attributes are defined the project area process. It includes attributes and values that are not standardized by OSLC CM 1.0. In the example work items need a ‘type’ and a ‘filedAgainst’ attribute. Two ways for providing required attributes, by defining a more robust common vocabulary for change requests or by discovering the schema of a change request, are currently being discussed in OSLC CM 2.0.

These problems are avoided with the delegated creation. The service document specifies an URL pointing to a Web page that can be embedded in a browser widget or in an iframe. The dialog contains the controls to select or create a new item and the OK / Cancel buttons.

OSLC creation dialog offered by RTC

The dialog will force the user to set all required fields until the OK button is enabled. When the user clicks on the OK button, the Web page will send the URI of the created element back to the client. The Delegated Resource Selection and Creation document describes the API and code snippets to do this.

To show a dialog in rich UI applications like an Eclipse application, a browser widget can be embedded in a dialog
To show a dialog in a Web UI, an iframe can be embedded in a dialog
The service document specifies the expected width and height of the dialog and also contains the dialog title

Find a Change Request

To find a change request you can use

the ‘simpleQuery’ service to programmatically find change requests matching the given search criteria
the ‘selectionDialog’ service to show a change request selection dialog

The simple query supports a query syntax defined in the Change Management Query Syntax document.

Queries are run by appending the parameter oslc_cm.query=[query] to the simpleQuery URL from the services discovery document.

For instance the query for all change requests that contain the word “Bug” can be written as oslc_cm:searchTerms="Bug".

The results can be fetched in JSON, ATOM and XML, depending on the used Accept header. Getting partial representations is especially useful in conjunction with query results. Fetching only a small set of attributes improves performance by reducing the size of transferred data.

GET https://rtc:9443/jazz/oslc/contexts/_gasc4Ju-Ed6cerS9lb5AWw/workitems?oslc_cm.query=oslc_cm%3AsearchTerms%3D%22Bug%22&oslc_cm.properties=dc:title
Accept: application/x-oslc-cm-change-request+xml

<?xml version="1.0" encoding="UTF-8"?>
<oslc_cm:Collection xmlns:rtc_cm="https://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"
   xmlns:dc="http://purl.org/dc/terms/" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:jp="https://jazz.net/xmlns/prod/jazz/presentation/1.0/"
   xmlns:jd="https://jazz.net/xmlns/prod/jazz/discovery/1.0/" xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" xmlns:atom="http://www.w3.org/2005/Atom"
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:calm="https://jazz.net/xmlns/prod/jazz/calm/1.0/"
   oslc_cm:totalCount="3">
  <oslc_cm:ChangeRequest rdf:resource="https://rtc:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_0J39QJu-Ed6cerS9lb5AWw">
    <oslc_cm:score>100</oslc_cm:score>
    <dc:title>My First Bug</dc:title>
  </oslc_cm:ChangeRequest>
  <oslc_cm:ChangeRequest rdf:resource="https://rtc:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_CD62QJu_Ed6cerS9lb5AWw">
    <oslc_cm:score>100</oslc_cm:score>
    <dc:title>My Second Bug</dc:title>
  </oslc_cm:ChangeRequest>
  <oslc_cm:ChangeRequest rdf:resource="https://rtc:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/_7Z5cAJvDEd6cerS9lb5AWw">
    <oslc_cm:score>100</oslc_cm:score>
    <dc:title>My Third Bug</dc:title>
  </oslc_cm:ChangeRequest>
</oslc_cm:Collection>

The selection dialog works similar to the creation dialog. The URL points to a Web page that needs to be embedded in an iframe or browser widget.

Filter

The filter service is not part of OSLC 1.0, but offered by RTC. It takes a list of resource URLs and returns a filtered list, containing only the resources that match the filter. An example of such a filter is the ‘openItems’ filter, which only returns change requests that are open. An addition of a similar service to OSLC 2.0 is currently discussed.

Conclusion

In this article we have introduced OSLC CM using RTC as an example. We have shown how tools can access change request resources and services represented in OSLC.

Complete examples are used to illustrate resource representations in XML and JSON, and show how HTTP operations can be used to access and modify complete and partial change requests.

This article shows how OSLC CM services are discovered through a hierarchy of service documents. Different services are used to create and query change requests programmatically or by an user interface. Moreover, we discuss limitations of the OSLC specifications and give an outlook to features of the OSLC 2.0 specification.

References

Open Service home page: http://open-services.net/html/Home.html
OSLC CM 1.0 specification: http://open-services.net/bin/view/Main/CmSpecificationV1
Change Management Resources Definition: http://open-services.net/bin/view/Main/CmResourceDefinitionsV1
Change Management Service Description: http://open-services.net/bin/view/Main/CmServiceDescriptionV1
Firefox Poster Add-On: https://addons.mozilla.org/de/firefox/addon/2691
HTTP4e Eclipse HTML plugin: http://www.ywebb.com/eclipse-restful-http-client-plugin-http4e/

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Feedback

Was this information helpful?

Yes

No 14 people rated this as helpful.