Consuming Rational Team Concert’s OSLC Change Management V2 Services
Abstract
Do you want to know how other applications use the Rational Team Concert UI to create and link change requests? Do you want to use HTTP protocols to query, create and modify change requests in Rational Team Concert? This article demonstrates these techniques using examples, and explains how to apply them to your application.
This article explains how software lifecycle tools can consume the services of an OSLC (Open Services for Lifecycle Collaboration) CM (Change Management) v2.0 Service Provider like Rational Team Concert (RTC). It introduces the CM specifications defined by OSLC, and describes the fundamental services and UI delegation dialogs offered by a CM Service Provider for creating, querying and updating change requests. After going through this article, you will understand how to integrate with an OSLC CM v2.0 Service Provider by consuming its services.
Table of Contents
- Introduction
- Consuming an OSLC CM Creation Dialog – A Walkthrough
- Overview of OSLC CM v2.0 Specifications
- Consuming Services of an OSLC CM v2.0 Service Provider
- Advanced Concepts
- Conclusion
Introduction
Rational Team Concert (RTC) is a Jazz-based team collaboration software development environment in the Change Management (CM) domain that implements both the OSLC CM v1.0 and the OSLC CM v2.0 specifications. In RTC v3.0 we started to support all MUST and SHOULD requirements of the OSLC CM v2.0 specification, including OSLC CM v2.0 service capabilities and the discovery mechanism for finding the Service Provider and services. These services can be easily consumed by applications, as they are based on industry open standards like HTTP and REST, and defined by an open body called OSLC. Using these services, applications can use RTC’s dialogs within their UIs for creating and linking change requests. Applications can also access, modify, delete and create change requests with an HTTP-based client by using GET, PUT, DELETE and POST methods. In this article we discuss the capabilities of OSLC CM v2.0 Service Providers, and how to discover and consume their services.
NOTE:
- In this article, OSLC CM v2.0 Service Providers will be referred to as CM providers, and applications consuming their services as CM consumers.
- RTC is used as the reference implementation for a CM provider while explaining concepts and illustrating examples.
- Unless specified, all example HTTP requests mentioned in this article are assumed to contain the following HTTP headers: OSLC-Core-Version=2.0, Accept=application/rdf+xml, Content-Type=application/rdf+xml
Consuming an OSLC CM Creation Dialog – A Walkthrough
Before diving into the concepts and in-depth details of the OSLC and CM provider service specifications, let us go through a scenario that explains how to consume the Delegated User Interface Dialog service of a CM provider. Imagine a tester with a quality management tool – say Rational Quality Manager (RQM) – wants to create a defect in a bug tracking tool when a test case fails. In this case, the quality management tool would have to implement the user interface for creating defects, requiring detailed knowledge of all the fields of a defect. This can be a lot of work and could result in poor user experience, because the complete internal structure of a defect is not exposed to the quality management tool. RTC, as a CM provider, offers Delegated UI Dialogs for integration with other applications. The quality management tool, as a CM consumer, can request such a dialog and display it to the tester within its own user interface. below shows the RTC dialog within RQM’s UI for creating a change request.
shows how a tester using RQM can create a defect in RTC for failing test cases. The tester provides required information like Summary and Filed Against values in this creation dialog. After providing all these details, the defect can be created by clicking the OK button.
Now, let us understand how a CM consumer like RQM can fetch a dialog from RTC for submitting a defect, and display it within its own user interface.
Discovering Services
CM consumer applications that want to interact with RTC need a mechanism for discovering its services, and the URLs used to access those services. In order to interact with RTC, the application must:
- Get the Root Services Document
- Find the CM Service Catalog
- Fetch the CM Service Provider Document
Consumers should not rely on or remember any specific URLs, or perform ‘path math’ on URLs. Instead, they should use the discovery chain. All they need to know is the URL of the root services document.
Root Services Document
Root services documents are exposed by every Jazz-based application. The document publishes all root services provided by the application. In RTC the root services document is available at the context /rootservices under the application’s root context. The specification of the root services document can be found in the Root Services specification. For example, the URL of a root services document for the RTC application might look like this: https://rtc:9443/ccm/rootservices
| HTTP GET | https://rtc:9443/ccm/rootservices |
|---|---|
| HTTP Response |
<rdf:Description rdf:about="https://rtc:9443/ccm/rootservices"> ..... <oslc_cm:cmServiceProviders xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" rdf:resource="https://rtc:9443/ccm/oslc/workitems/catalog" /> ..... </rdf:Description> RTC publishes the Service Provider Catalog resource using the property <oslc_cm:ServiceProviders> as shown in the example above. CM consumers can now fetch the service provider catalog using the URL from the above property.
NOTE: The Root Services Document is Jazz-specific and is not part of OSLC specification.
Service Provider Catalog
The Service Provider Catalog is a collection of all Service Provider documents. A Service Provider document is defined for every project area in RTC and contains references to the services exposed by that project area.
| HTTP GET | https://rtc:9443/ccm/oslc/workitems/catalog |
|---|---|
| HTTP Response |
<oslc_disc:ServiceProviderCatalog> <dc:title>Project Areas</dc:title> ..... <oslc_disc:entry> <oslc_disc:ServiceProvider> <dc:title>JUnit Project</dc:title> <oslc_disc:details rdf:resource="https://rtc:9443/ccm/process/project-areas/_FckdEKD8EeGCjPo2EBGANQ"/> <oslc_disc:services rdf:resource="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems/services.xml"/> ..... </oslc_disc:ServiceProvider> </oslc_disc:entry> ..... </oslc_disc:ServiceProviderCatalog> The Service Provider Catalog resource contains as many entries of <oslc_disc:ServiceProvider> as project areas exist in the repository. The Service Provider Catalog contains a reference for each Service Provider document in the property <oslc_disc:services>.
Work Item Creation Dialog
Choose and fetch the Service Provider document of the project area in which the defect resource has to be created. It contains references to various services like Querying, Creation and Selection dialogs.
| HTTP GET | https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems/services.xml |
|---|---|
| HTTP Response |
<rdf:RDF> <oslc:ServiceProvider rdf:about="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems/services.xml"> <oslc:service> <oslc:Service> <oslc:domain rdf:resource="http://open-services.net/ns/cm#"/> ..... <oslc:creationDialog> <oslc:Dialog> <dcterms:title rdf:parseType="Literal">New Defect</dcterms:title> <oslc:usage rdf:resource="http://open-services.net/ns/core#default"/> <oslc:usage rdf:resource="http://open-services.net/ns/cm#defect"/> <oslc:dialog rdf:resource="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/modules/com.ibm.team.workitem.WICreationDialog?projectAreaId=_FckdEKD8EeGCjPo2EBGANQ&showLoginLink=true&dc%3Atype=defect"/> <oslc:hintWidth>680px</oslc:hintWidth> <oslc:hintHeight>505px</oslc:hintHeight> </oslc:Dialog> </oslc:creationDialog> ..... </oslc:service> </oslc:Service> </oslc:ServiceProvider> </rdf:RDF> The value of the <oslc:creationDialog> property is a <oslc:Dialog> resource that contains details including the URL of the Creation Dialog for creating change requests. The CM consumer – in this case RQM – gets RTC’s CM Service Provider and finds the creation dialog URL to embed the dialog in its user interface. below explains the interactions among the CM consumer and its UI with the CM provider and its UI.
shows the RTC creation dialog in RQM’s Web UI after RQM has fetched it. This dialog enables the user to set all fields required in order for the OK button to be enabled, and also contains a Cancel button to cancel the create operation. On successful creation of the change request, it sends notification back to the CM consumer with the created change request resource’s URL – https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/85. The CM consumer can now show this URL to the user within its own user interface and wait for further interaction from the user to link the resulting URL to one of its resources. This is completely independent from the specification, and consumers are free to take any approach for handling this returned URL.
NOTE: For technical details on how to integrate user interfaces with OSLC dialogs please refer to the document OSLC Delegated User Inteface Dialogs.
Compact Rendering Representation & Preview
After receiving the change request URL from the CM provider, the CM consumer can display it in its UI using Compact Rendering Representation. The CM consumer can fetch this representation using the OSLC-defined media type called application/x-oslc-compact+xml. This representation contains title, icon and references to UI previews of the requested change request resource.
| HTTP GET | https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/85 | ||||
|---|---|---|---|---|---|
| HTTP Headers |
| ||||
| HTTP Response |
<?xml version="1.0" encoding="UTF-8"?> <rdf:RDF> <oslc:Compact rdf:about="https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/85"> <dc:title>Failing Test Case "Verify dividend transfer frequency"</dc:title> <oslc:shortTitle><span color="#BBBBBB">85</span></oslc:shortTitle> <oslc:icon rdf:resource="https://rtc:9443/ccm/service/com.ibm.team.workitem.common.internal.model.IImageContentService/processattachment/_1w8aQEmJEduIY7C8B09Hyw/workitemtype/bug.gif?bl=bundleentry/748.fwk1080770667/icons/ovr16/wi_complete_ovr.gif&dim=true" /> <oslc:smallPreview> <oslc:Preview> <oslc:document rdf:resource="https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/85?_mediaType=text%2Fhtml&_selector=smallHover&_context=web" /> ... </oslc:Preview> </oslc:smallPreview> <oslc:largePreview> <oslc:Preview> <oslc:document rdf:resource="https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/85?_mediaType=text%2Fhtml&_selector=hover&_context=web" /> ... </oslc:Preview> </oslc:largePreview> </oslc:Compact> </rdf:RDF>
RQM fetches this compact rendering representation of the created change request from RTC, and displays it in its web UI with its title and icon as shown in the figure below.
When a CM consumer is presenting the linked change request to its user, it is common to include some relevant information about it. This information might be included in a pop-up window when the mouse is over the link. Such information can be retrieved and displayed as a preview of the linked change request when hovering on it using its small and large previews. The change request provides its preview URLs in its compact rendering representation as shown in the Example. RQM shows the preview for the change request when the user hovers on the change request link by fetching its preview from RTC using the preview URL – https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/85?_mediaType=text%2Fhtml&_selector=hover&_context=web.
This section explained how to display RTC’s change request creation dialog in the consumer’s user interface. An interesting fact is that the CM consumer application can easily replace RTC’s dialog with a dialog from any other OSLC CM provider by following the same steps as explained above. This is because the CM providers, like RTC, follow the specifications defined by OSLC, which abstracts from the tool’s underlying data model and architecture. This allows OSLC consumers to simply swap in another OSLC application without spending much effort.
OSLC CM providers also provide other OSLC services in addition to the creation dialog service which are useful for integration. The following sections will give an overview of these OSLC CM services, and will demonstrate how to consume these services using RTC as an example.
Overview of OSLC CM v2.0 Specifications
Open Services for Lifecycle Collaboration (also known as OSLC or Open Services) is an open community that defines specifications for integrating tools in software lifecycle domains such as requirements, change and quality management. The OSLC Change Management (CM) specifications document defines a common set of resources, formats and RESTful services for the use in CM tools as well as ALM and PLM tools. OSLC has two versions – 1.0 and 2.0 – for CM specifications.
The OSLC CM v2.0 specification defines a RESTful web services interface for Change Management activities, tasks and relationships between those and related resources such as project, category, requirements, test case, and plan. To support these scenarios, it defines a set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP codes, content type handling and resource formats. It extends and restricts the OSLC Core specification, while referencing resources defined in other domain specifications like QM and RM.
Briefly, OSLC CM v2.0 consists of the following parts:
- Base Requirements – OSLC CM v2.0 is based on the OSLC Core specification. Its providers and consumers MUSTbe compliant with both the core specification and this specification, and SHOULD follow all the guidelines and recommendations in both these specifications. The OSLC Core specification sets out common features like authentication, service discovery, common resources, query and paging capabilities, and error responses that every OSLC Service can be expected to support. It specifies what OSLC Services MUST, SHOULD and MAY do.
- Resource Definitions – OSLC CM v2.0 defines a single resource called Change Request to describe many kinds of change requests such as defect, enhancement, task, bug, and activity. It defines a minimal set of standardized attributes that are common properties between these different kinds of change requests.
- Service Specifications – OSLC CM v2.0 defines a set of service capabilities that can or must be offered by OSLC CM service providers. These include services to find and create change request resources programmatically, to define the shape of the change request resource, and to integrate applications using delegated UI dialogs. Services are addressable through service URLs and can return results in RDF, JSON, XML and HTML formats.
Integration Techniques
OSLC offers two primary techniques for integrating tools. Both of these are built on the HTTP and RDF foundation of OSLC.
- Linking data via HTTP – Protocol for creating, retrieving, updating and deleting (CRUD) lifecycle data based on internet standards like HTTP and RDF using the Linked Data model.
- Linking data via HTML User Interface – Protocol that allows a tool or other client to cause a fragment of the web user interface of another tool to be displayed, allowing a user to link to a new or existing resource in the other tool or see a preview of information about a resource in another tool.
OSLC has written specifications for the tools to provide services for the above integration behaviors. To achieve this, OSLC also defined a core set of resources like Service Provider and Service Provider Catalog which have to be supported by every tool implementing the OSLC specifications.
Service Provider
A Service Provider is the central organizing concept of OSLC, enabling tools to expose resources and allowing consumers to navigate to all of these resources, and create new ones. It partitions the overall space of artifacts in the tool into smaller containers. Each artifact created in the tool is created within the context of one of these containers. The Service Provider is the fundamental resource that is essential for any client integrating with OSLC-based applications. It is a metadata or single publishing document for all services offered by one of the contexts/containers of the tool. By obtaining access to it, clients can start querying for artifacts or creating them in the tool. The Service Provider has three fundamental sections for enabling consumers to link artifacts:
- Creation Factory
- Query Capability
- Delegated UI Dialogs
In RTC, all work items residing in the repository are logically grouped, at the top, by a project area where attributes, scope, accessibility and permissions of a work item are configured. Hence, RTC defines a Service Provider for each project area that allows clients to link and integrate at a project area level.
| HTTP GET | https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems/services.xml |
|---|---|
| HTTP Response |
<rdf:RDF> <oslc:ServiceProvider rdf:about="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems/services.xml"> <oslc:service> <oslc:Service> <oslc:domain rdf:resource="http://open-services.net/ns/cm#"/> <oslc:creationFactory> <oslc:CreationFactory> ..... <oslc:queryCapability> <oslc:QueryCapability> ..... <oslc:creationDialog> <oslc:Dialog> ..... <oslc:selectionDialog> <oslc:Dialog> ..... <calm:filter> <calm:Filter> ..... </rdf:RDF>
Services
A Service Provider publishes all the services provided by a context (in RTC it is Project Area) of an OSLC application. A Service Provider can contain services from more than one domain. The domain of the service is determined by the property oslc:domain. Following are the four basic services that any Service Provider will have:
- Creation Factory – An HTTP integration service for creating resources programmatically. Consumers of this service can use an HTTP client and perform an HTTP
POSTmethod for creating resources. This is explained with examples in the section Consuming the Creation Service. - Query Capability – An HTTP integration service for querying resources programmatically. Consumers of this service can use an HTTP client and perform an HTTP
GETmethod for fetching resources. This is explained with examples in the section Consuming the Query Service. - Creation Dialog – An HTML User Interface integration service for creating resources. is an example of this.
- Selection Dialog – An HTML User Interface integration service for picking resources. Consumer applications can use this dialog in place of a creation dialog for selecting resources from the provider application. It works similar to the selection dialog, except that it returns the set of resource URLs selected to the requesting application.
Change Requests Selection Dialog
NOTE: Refer to the wiki for a sample complete Service Provider Document.
Service Provider Catalog
A Service Provider defines services for just one of the contexts of a tool. A tool can expose more than one Service Provider if it has more contexts. OSLC provides the concept of a Service Provider Catalog for defining sets of Service Providers. An example of such a resource from RTC is shown here – Service Provider Catalog.
Consuming Services of an OSLC CM v2.0 Provider
Consuming an OSLC Creation Dialog demonstrated how a CM consumer can bring the UI dialogs of a CM provider into its user interface for creating and selecting change requests. This section explains how to consume the rest of the OSLC services provided by a CM provider using RTC as an implementation example. As services and resources are all based on web technologies such as HTTP, RDF, JSON and HTML, it is easy to experiment 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 assumes that the RTC repository is running on https://rtc:9443/ccm. Fill in your host name instead of ‘rtc’.
To make the REST calls, use Firefox with an add-on like Poster, or use a standalone REST utility like curl or HTTP4e.
RTC’s Change Request Resource Definition and Representations
RTC extends the OSLC Change Request resource and defines its own CM resource called Work Item. A work item resource is composed of properties from multiple vocabularies:
- OSLC CM v2.0 Change Request properties
- OSLC extended Change Request experimental properties
- RTC defined Work Item properties
- Jazz defined properties
The OSLC Core specification mandates every resource published by a Service Provider should be represented in RDF/XML (the most widely adopted RDF notation), but can have representations in other formats such as JSON or HTML. RTC, as a OSLC CM Service Provider, supports the mandatory RDF/XML representation for all resources exposed by it. In addition to this, RTC also provides other representations like JSON, XML, HTML, ATOM and TURTLE. A change request representation can be requested by specifying its accept type in the request’s header; e.g. Accept=application/rdf+xml.
| HTTP GET | https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/81 |
|---|---|
| HTTP Response | RDF/XML Representation |
RTC also offers a change request representation in JSON. JSON is easier to consume, especially in J avaScript. A sample JSON representation of a change request can be found here
Partial Representations
A CM provider also supports responding with partial resource representations that contain only requested properties. This can reduce the HTTP traffic over the wire by not transferring data that is not needed by the clients. Requests for partial representations should contain the list of properties to be included in the response. This can be done using the URL parameters oslc.properties and oslc.prefix. If the oslc.properties parameter is omitted in the request, then all resource properties are included in the response. Refer to Selective Property Values to understand their usage and syntax.
| HTTP GET | https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/81? oslc.properties=oslc_cmx:priority,dcterms:contributor%7B*%7D& oslc.prefix=dcterms=%3Chttp://purl.org/dc/terms/%3E,oslc_cmx=%3Chttp://open-services.net/ns/cm-x%23%3E | ||||||
|---|---|---|---|---|---|---|---|
| URL Parameters |
| ||||||
| HTTP Response |
<rdf:RDF> <rdf:type rdf:resource="http://xmlns.com/foaf/0.1/Person"/> <dcterms:modified rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">2012-05-18T15:13:46.147Z</dcterms:modified> <foaf:img rdf:resource="https://rtc:9443/ccm/resource/content/_EAYy8KD8EeGCjPo2EBGANQ"/> <foaf:mbox rdf:datatype="http://www.w3.org/2001/XMLSchema#string">mailto:jason_mitchell%40example.jazz.net</foaf:mbox> <foaf:name rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Jason Mitchell</foaf:name> <foaf:nick rdf:datatype="http://www.w3.org/2001/XMLSchema#string">jason</foaf:nick> </rdf:Description> <rdf:Description rdf:about="https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/81?..."> <rdf:type rdf:resource="http://open-services.net/ns/cm#ChangeRequest"/> <dcterms:contributor rdf:resource="https://rtc:9443/jts/users/jason"/> <oslc_cmx:priority rdf:resource="https://rtc:9443/ccm/oslc/enumerations/_FckdEKD8EeGCjPo2EBGANQ/priority/priority.literal.l01"/> </rdf:Description> </rdf:RDF>
NOTE: The oslc.prefix parameter is not included in further examples. It should be noted that even though this parameter is not mentioned, it should be used while trying out these examples.
Creation Service
The Creation Factory service published by the CM provider contains the Creation URL used to create new resources via the HTTP POST protocol.
<oslc:CreationFactory> <dcterms:title rdf:parseType="Literal">Location for creation of Defect change requests </dcterms:title> <oslc:usage rdf:resource="http://open-services.net/ns/core#default"/> <oslc:usage rdf:resource="http://open-services.net/ns/cm#defect"/> ... <oslc:resourceShape rdf:resource="https://rtc:9443/ccm/oslc/context/_FckdEKD8EeGCjPo2EBGANQ/shapes/workitems/defect"/> <oslc:creation rdf:resource="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems/defect"/> </oslc:CreationFactory> To create a new Change Request resource, the consumer POSTs a representation of that resource to a Creation Factory’s creation URL. In RTC, a change request can be divided into multiple user-defined types called work item types; e.g. defect, plan item, or task. RTC’s CM provider contains creation factories for each work item type, and marks one of them for default usage. A creation factory can be defined for multiple usages. Refer to the advanced section on Change Request Usages to learn about usages. A change request creation factory in RTC is defined for at most three usages.
- Default usage – Can be used as a default. The Service resource defines only one such default creation factory.
<oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
- OSLC usage – Defines the creation factory for oslc change request types usage.
<oslc:usage rdf:resource="http://open-services.net/ns/cm#defect"/>
- RTC usage – Defines the creation factory for RTC work item types usage.
<oslc:usage rdf:resource="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/com.ibm.team.apt.workItemType.epic"/>
Creating a Change Request Resource
To create a change request resource of a given type, a client first forms a representation of that type, including desired and required property values. The client can learn what properties are allowed in the resource via the specifications that define the resource, or via the Resource Shape resource. The client should then use HTTP POST to post that representation to the creation URL. On successful creation, the CM provider returns with the HTTP status 201 - Created, and includes the URL of the newly created resources in the HTTP Location header of the response. The response also includes the representation of the newly created resource.
| HTTP POST | https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems/story |
|---|---|
| Content |
<rdf:RDF> <rdf:Description rdf:nodeID="A0"> <dcterms:title rdf:parseType="Literal">Work Item Implementing Requirement</dcterms:title> <dcterms:title>A new plan item</dc:title> <dcterms:description>This is new plan item</dc:description> <oslc_cm:implementsRequirement rdf:resource="https://rmhost:9443/rm/resources/_mmRJ6VQxEeGgT7AW-H3Hfw"/> </rdf:Description> </rdf:RDF>
Query Service
RTC, as a CM provider, provides a single Query Capability for querying its change request resources. It contains a base URL for forming Query Resource URLs, and provides Resource Shapes that describe the property values that may be expected in the resources that are queryable via the Query Capability. Thus the Query Capability provides a way to discover the change request resources.
<oslc:QueryCapability> <dcterms:title rdf:parseType="Literal">Change request queries</dcterms:title> <oslc:usage rdf:resource="http://open-services.net/ns/core#default"/> ... <oslc:queryBase rdf:resource="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems"/> </oslc:QueryCapability> The base URL itself is a resource managed by the service, and acts as the starting subject resource for the queries based on it. Since the list may contains hundreds of thousands of members, queries are used to filter the list for members that satisfy certain conditions, e.g. defects that have high severity and are planned for current iteration.
| HTTP GET | https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems |
|---|---|
| HTTP Response |
<rdf:RDF> <rdf:Description rdf:about="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems"> <oslc:totalCount>62</oslc:totalCount> ..... <rdfs:member rdf:resource="https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/6"/> <rdfs:member rdf:resource="https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/7"/> ..... </rdf:Description> </rdf:RDF>
Querying a Change Request Resources
To perform a query, a client first creates a URL by starting with the Query Capability’s base URL and adding a URL Query String to express the query criteria. The resulting URL is the query URL. The client should then use an HTTP GET request to the query URL, optionally specifying the preferred content media type for the query response in the HTTP Accept header. The query response contains the Query Resource representation of the query results. The Query Resource representation will contain property values about the query and a collection of resources that match the query criteria. The OSLC Core Query Specification document defines a standard set of OSLC query parameters that clients can use to query resources. Here are some commonly used query parameters:
oslc.where oslc.searchTerms oslc.orderBy oslc.select
| HTTP GET | https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems?oslc.where=dcterms:created%3E%222011-07-06T18%3A13%3A35.336Z%22&oslc.prefix=dcterms=%3Chttp%3A//purl.org/dc/terms/%3E | ||||
|---|---|---|---|---|---|
| Query Parameters |
|
Partial Representations
Getting partial representations is especially useful in conjunction with query results. Top-level and nested properties of the change request resources in the matching members list can be specified using the oslc.select query parameter. It is like the SELECT clause of a SQL statement.
| Query Parameters |
| ||||||
|---|---|---|---|---|---|---|---|
| HTTP Response |
<rdf:RDF> <rdf:Description rdf:about="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems?...."> <oslc:totalCount>15</oslc:totalCount> <rdf:type rdf:resource="http://open-services.net/ns/core#ResponseInfo"/> </rdf:Description> <rdf:Description rdf:about="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems"> <rdfs:member rdf:resource="https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/9"/> <rdfs:member rdf:resource="https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/4"/> </rdf:Description> <rdf:Description rdf:about="https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/9"> <rdf:type rdf:resource="http://open-services.net/ns/cm#ChangeRequest"/> <dcterms:contributor rdf:resource="https://rtc:9443/jts/users/bill"/> </rdf:Description> ..... ..... <rdf:Description rdf:about="https://rtc:9443/jts/users/bill"> <rdf:type rdf:resource="http://xmlns.com/foaf/0.1/Person"/> ..... <foaf:name rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Bill Cassavelli</foaf:name> </rdf:Description> </rdf:RDF>
The results can also be fetched in JSON, ATOM and XML depending on the Accept header used. Refer to the wiki for more examples – Query Examples.
Change Request Operations
Change Request resources can be programmatically updated or deleted by using the HTTP protocols PUT and DELETE. This section explains how to use these operations.
Updating a Change Request
To update a change request resource, a client should fetch its representation first using HTTP GET. The client updates the representation, and then uses HTTP PUT to send the new representation to the resource’s URL. Two cases here deserve special attention:
- Avoid overwriting changes done by someone else – Because the update process involves first getting the change request representation, then modifying it and then putting it back to the server, there is a possibility of conflict; e.g. some other client may have updated the change request at the same time. In general, clients should not blindly overwrite the change request contents, but should make sure that the changes are applied to the state that they fetched from the server. To mitigate this problem, the client should use the HTTP If-Match header. This is done by including the ETag received on load in the If-Match header when PUTting the work item back to the server.
ETag information can be fetched from the HTTP response headers that are returned when a change request representation is requested usingHTTP GETrequestHTTP/1.1 200 OK ETag: "_DrhL0KDHEeCbuLDfakk_jw" ...
- If the HTTP If-Match header is missing, the CM provider will return an HTTP
400 - Bad Requeststatus to indicate the header is required - If the HTTP If-Match is present and it does not match to the existing state (the change request was modified since it was fetched), the CM provider behaves as described in the HTTP specification, returning an HTTP
412 - Precondition Failedstatus. - If the HTTP If-Match header is present and matched, the update will be executed, and on success an HTTP
200 - OKstatus is returned
- If the HTTP If-Match header is missing, the CM provider will return an HTTP
- Updating a Subset of Properties (Partial Updates) – PUT generally has the semantics of updating the entire resource, and removing what is not included. In order to allow partial updates via the more generally supported PUT, and to selectively remove entire attributes from a change request, the client can specify the set of properties to update via the oslc.properties parameter. If the parameter contains a valid change request property which is not present in the PUT representation, the CM provider removes the property. If the parameter contains an invalid property, then the CM provider returns an HTTP
409 - Conflictstatus.
| HTTP PUT | https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/81 | ||||
|---|---|---|---|---|---|
| HTTP Headers |
| ||||
| Content |
<rdf:RDF> <rdf:Description rdf:about="https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/81"> ..... <dcterms:title rdf:parseType="Literal">Updating Typo: wrong package for JUnitCore</dcterms:title> <dcterms:subject>tag1, tag2</dcterms:subject> ..... </rdf:Description> </rdf:RDF>
| HTTP PUT | https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/81? oslc.properties=dcterms:contributor,oslc_cm:implementsRequirement& oslc.prefix=dcterms=%3Chttp%3A//purl.org/dc/terms/%3E,oslc_cm=<http://open-services.net/ns/cm%23> | ||||||
|---|---|---|---|---|---|---|---|
| HTTP Headers |
| ||||||
| Content |
<rdf:RDF> <rdf:Description rdf:about="https://rtc:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/81"> <dcterms:contributor rdf:resource="https://rtc:9443/jts/users/rick"/> </rdf:Description> </rdf:RDF>
For more examples refer to the wiki – Examples – Updating work items using OSLC CM v2.0.
Deleting a Change Request
Clients can programmatically delete a change request by making an HTTP DELETE request on its resource URL. On successfully deleting, the CM provider returns the HTTP status 200 - OK to the client.
Advanced Concepts
Service Usage Identifiers
OSLC CM providers can identify the usage of various services with additional property values defined for the OSLC Core: oslc:usage property on oslc:Dialog, oslc:CreationFactory, and oslc:Capability. The oslc:usage property value of http://open-services.net/ns/core#default will be used to designate the default or primary service to be used by consumers when multiple entries are found.
The additional property values for oslc:usage are:
http://open-services.net/ns/cm#defecthttp://open-services.net/ns/cm#planItemhttp://open-services.net/ns/cm#taskhttp://open-services.net/ns/cm#requirementsChangeRequest
RTC provides customization for mapping the defined work item types with the Change Request types defined above. It is possible to map a single work item type to one or more OSLC Change Request types. The Service Provider uses the mapped change request type as a value for the oslc:usage property while defining a creation factory or a dialog for the work item type.
Work Item State Groups
Probably the most important property of a Change Request is the oslc_cm:status property. It specifies the location of a Change Request in a workflow. Workflows are customizable in RTC, and can vary among work item types and project areas. The meaning of the status property may not be the same for all work items. It can be difficult to define a query that fetches all work items that are fixed or open. One should understand the semantics of each workflow defined for each work item type in all project areas for writing such a query. To simplify this, OSLC defined some Boolean properties to help understand the state of a change request. RTC provides customization under each workflow, and defines a set of state groups which can be mapped to OSLC predicate groups for computing the values of state predicates.
With the above state groups mapping, if the work item is in a state that falls into the In Progress category, then values for state predicates will be as follows:
<oslc_cm:closed>false</oslc_cm:closed> <oslc_cm:inprogress>true</oslc_cm:inprogress> <oslc_cm:fixed>false</oslc_cm:fixed> <oslc_cm:approved>false</oslc_cm:approved> <oslc_cm:reviewed>false</oslc_cm:reviewed> <oslc_cm:closed>false</oslc_cm:closed> <oslc_cm:verified>false</oslc_cm:verified>
Pagination
In some cases, the Change Requests Query representation resource may be so large that a client might not want to retrieve the entire resource in one HTTP response. In such situations, clients can use Resource Paging, a technique defined by the OSLC Core specification. To get a paged version of the Query Representation, a client can add oslc.paging=true as a query parameter to the query URL. The returned Query Representation page contains the partial result set. All pages, except the last page, contain the link to the resource that represents the next page of the result set. Because paging is unstable, by the time a client follows the next page link there may be no longer be a next page. In this case, RTC responds with an HTTP 410 Expired status code to indicate to clients that the next page link they requested is expired. A client can also request paging by adding oslc.pageSize=value as a query parameter to the query URL. By adding this, the query service will return the result set in pages with each page sized as requested by the client.
| Query Parameters |
| ||||||
|---|---|---|---|---|---|---|---|
| HTTP Response |
<rdf:RDF> <rdf:Description rdf:about="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/work items"> .... </rdf:Description> <rdf:Description rdf:about="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems? oslc.paging=true&oslc.pageSize=10&oslc.where=oslc_cm:closed=false&_pretty=true"> <oslc:nextPage rdf:resource="https://rtc:9443/ccm/oslc/contexts/_FckdEKD8EeGCjPo2EBGANQ/workitems? oslc.pageSize=5&_resultToken=_qg0kgaq3EeC3j9Q8Ijg_4Q&_startIndex=5"/> <dcterms:title>Work Items</dcterms:title> <oslc:totalCount>60</oslc:totalCount> <rdf:type rdf:resource="http://open-services.net/ns/core#ResponseInfo"/> </rdf:Description> </rdf:RDF>
If the query service finds that the Query Representation resource to be returned is too big or contains a large result set, it redirects the client to a location where a Query Representation with an appropriate size is returned. This is true even when the clients make a paging request with a large page size. In these cases, the query service returns an HTTP Status 302 redirect with a URL that includes the paging parameters, as follows:
- If the client did not indicate paging, the new redirect URL includes the
oslc.pagingpair - If the client indicated a page size, then the redirect URL includes the
oslc.pageSizevalue that is acceptable to the service
Resource Shape
The Resource Shape resource provides a machine-readable definition of an OSLC resource type and lets clients learn which properties are commonly used or required while creating, updating or querying the resources. It describes the properties that are allowed or required by one type of resource. It does not define the properties, but it does explain how the properties are to be used in OSLC for one or more specific scenarios: the value-type to be used for the property, the number of times the property is expected to occur, and whether the property is required. For more information on Resource Shape and its definition refer to OSLC Resource Shape. RTC defines shape resources for two of its resources – Work Item and Query resource.
Work Item shape resource is one of the types of OSLC Resource Shape resources that defines the possible representations for a work item while creating and updating. This should not be confused with the vocabulary for the work item. Vocabulary defines the generic representation of the work item, whereas the shape defines all allowed representations based on the given state of the work item. Also, the vocabulary for any work item will never change, but shape varies from work item to work item ,and from state to state of the same work item. For example, the shape resource for a work item of type defect could be different from that of a work item of type task.
| HTTP GET | https://rtc:9443/ccm/oslc/context/_FckdEKD8EeGCjPo2EBGANQ/shapes/workitems/story |
|---|---|
| HTTP Response |
<rdf:RDF> <rdf:Description rdf:about="https://rtc:9443/ccm/oslc/context/_FckdEKD8EeGCjPo2EBGANQ/shapes/workitems/story"> <oslc:describes rdf:resource="http://open-services.net/ns/cm#ChangeRequest"/> ... <oslc:property rdf:resource="https://rtc:9443/ccm/oslc/context/_FckdEKD8EeGCjPo2EBGANQ/shapes/workitems/story/property/com.ibm.team.apt.attribute.complexity"/> ... </rdf:Description> ... <rdf:Description rdf:about="https://rtc:9443/ccm/oslc/context/_FckdEKD8EeGCjPo2EBGANQ/shapes/workitems/story/property/com.ibm.team.apt.attribute.complexity/allowedValues"> ... <oslc:allowedValue rdf:resource="https://rtc:9443/ccm/oslc/enumerations/_FckdEKD8EeGCjPo2EBGANQ/complexity/10"/> ... </rdf:Description> <rdf:Description rdf:about="https://rtc:9443/ccm/oslc/context/_FckdEKD8EeGCjPo2EBGANQ/shapes/workitems/story/property/com.ibm.team.apt.attribute.complexity"> <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">false</oslc:readOnly> <oslc:occurs rdf:resource="http://open-services.net/ns/core#Zero-or-one"/> <oslc:allowedValues rdf:resource="https://rtc:9443/ccm/oslc/context/_FckdEKD8EeGCjPo2EBGANQ/shapes/workitems/story/property/com.ibm.team.apt.attribute.complexity/allowedValues"/> <oslc:defaultValue rdf:resource="https://rtc:9443/ccm/oslc/enumerations/_FckdEKD8EeGCjPo2EBGANQ/complexity/0"/> <oslc:name rdf:datatype="http://www.w3.org/2001/XMLSchema#string">com.ibm.team.apt.attribute.complexity</oslc:name> <oslc:propertyDefinition rdf:resource="http://jazz.net/xmlns/prod/jazz/rtc/ext/1.0/com.ibm.team.apt.attribute.complexity"/> <oslc:valueType rdf:resource="http://open-services.net/ns/core#Resource"/> <oslc:representation rdf:resource="http://open-services.net/ns/core#Either"/> </rdf:Description> </rdf:RDF>
Work Items shape resources are of two types:
- Creation Shape – Defines the shape of a work item for creation. Creation factories have the reference to this shape resource. It is defined for every work item type.
<oslc:resourceShape rdf:resource="https://rtc:9443/ccm/oslc/context/_FckdEKD8EeGCjPo2EBGANQ/shapes/workitems/defect"/>
- Instance Shape – Defines the shape of a work item’s instance for update. Every representation of a work item resource contains the reference to its instance shape. It provides the possible values of the work item’s properties for update.
<oslc:instanceShape rdf:resource="https://rtc:9443/ccm/oslc/shapes/workitems/_Kss58KD8EeGCjPo2EBGANQ"/>
Version Compatibility
As RTC supports both the 1.0 and 2.0 versions of OSLC CM specifications, this section will clarify the compatibility with 1.0 specification. Network addressable resource URLs used for 1.0 resources should not have to change. Consumers who support both 1.0 and 2.0 should only preserve the resource URLs. Some new resources defined in 2.0 like Resource Shape are not supported with the 1.0 protocol.
Media Types
For a Change Request Resource format identification of RDF/XML and XML, the media type used should be application/rdf+xml or application/xml. The usage of the OSLC CM 1.0 defined media types of application/x-oslc-cm-change-request+xml, application/x-oslc-cm-service-description+xml and application/x-oslc-disc-service-provider-catalog+xml is not supported in the OSLC CM 2.0 protocol.
For a Change Request Resource format identification of JSON, the media type used should be application/json. The usage of the OSLC CM 1.0 defined media type of application.x-oslc-cm-change-request+json is not supported for OSLC CM 2.0 requests.
Requesting formats
CM 1.0 consumers wanting to request 1.0 resource formats will not need to change if they used 1.0 defined media types. CM 2.0 consumers should use media types as defined in the specification for resource formats. Refer to the Representations section for supported formats.
Conclusion
This article explained the OSLC CM v2.0 specifications using RTC as an example. It also demonstrated how tools can access change request resources and services represented in OSLC. Complete examples are used to illustrate resource representations in RDF/XML and JSON, and show how HTTP operations can be used to access and modify complete and partial change requests. This article also showed how OSLC CM v2.0 services are discovered through a hierarchy of service documents. Different services are used to create and query change requests programmatically or by a user interface. We also discussed the compatibility of media types and formats with 1.0 specifications, and the experimental usage of properties in 2.0.
References
- Consuming RTC CM v1.0 services: How to consume the Rational Team Concert change management services
- Open Service home page: http://open-services.net/html/Home.html
- OSLC CM 2.0 specification: http://open-services.net/bin/view/Main/CmSpecificationV2
- OSLC CM Vocabulary: http://open-services.net/bin/view/Main/CmVocabulary
- OSLC User Interface Previews: http://open-services.net/bin/view/Main/OslcCoreUiPreview
- Work Items OSLC CM v2.0 wiki: https://jazz.net/wiki/bin/view/Main/WorkItemAPIsForOSLCCM20
- 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/
About the author
Sandeep Somavarapu is a developer in the Tracking and Planning team working on the Work Item component of Rational Team Concert, with main contributions to the OSLC CM services of RTC. For additional information about the topic presented in the article, add your comments or questions directly in the discussion part, or visit our Jazz.net Forum
Copyright © 2012 IBM Corporation