Blogs about Jazz

Blogs > Jazz Team Blog >

OSLC and Rational Team Concert

by Patrick Streule Fri, 11 Sep 2009 | 3 Comments
Tags: , , , —

First of all, what is OSLC? A quick search on Google returns the “Oregon Social Learning Center,” “Our Savior Lutheran Church,” and “Ontario Student Leadership Conference,” but then you will find “Open Services for Lifecycle Collaboration.” Lifecycle resources are change requests, test cases, defects, requirements, builds, and all the other things that we use daily when developing software. These resources are valuable by themselves, but they become much more useful when they are tightly integrated. For example, I would like to instantly see the changes that belong to a work item and which build they were first included in. This high level of integration is one of the key values of Rational Team Concert (RTC). Now, RTC is not an island. What if there are other products in use that manage parts of the application lifecycle, like Rational Quality Manager, Rational Requirements Composer or even Product X? I would like to see the same level of integration, but of course without forcing them all into the same code base. In RQM, I would like to see the work items that are ready for testing or be able to create a new defect directly from a test case (please read Carolyn Pampino’s blog post to learn more about the RQM-RTC integration). And that is just one example of many — see the Scaling Agile with C/ALM eBook for the big picture.

This is where OSLC comes into play. It defines a small but important set of methods for applications (or components thereof) to interact with each other. Complicated interfaces that impose a lot of requirements onto clients are unlikely to be used and are an obstacle on the way to the desired level of integration. So simplicity, stability, and standards compliance are key for such an interface, and are the driving factors behind OSLC. It shouldn’t take much more than an HTTP client and an XML or JSON parser to use the interface. Resource representations must be stable and self-explanatory; assumptions and out-of-band knowledge imposed on clients must be kept to a minimum. And it shouldn’t be a big effort to implement the interface.

Here, I am focusing on the Change Management part of OSLC (OSLC-CM) that allows you to query, link, fetch, create, and update change requests. OSLC is a community effort and the RTC Work Item team was part of the OSLC-CM specification group. Others in the workgroup included Mik Kersten and Robert Elves of Tasktop Technologies and the Eclipse Mylyn project; Randy Vogel and Gary Dang of Accenture, and Steve Speicher, Steve Abrams, and Andre Weinand from IBM. Version 1.0 of OSLC-CM is fully implemented in RTC 2.0.

Consuming OSLC-CM

Examples explain more than words alone, so let’s look at what we would leverage from OSLC-CM in RTC to implement a mobile web application which allows us to search for change requests.

Mobile Search UI

Mobile Search UI

We have a UI where a user enters some search terms. The matching change requests can be found using a simple HTTP GET to the following URL (not escaped for better legibility), which contains the search terms as a parameter:

https://example.org/jazz/oslc/contexts/_QwUc0I_YEd6lV_dBYBhShg/workitems?oslc_cm.query=oslc_cm:searchTerms="syntax"

But how does our application know this URL? It looks quite RTC-specific and it contains this weird UUID segment. The OSLC specification describes a discovery chain (as known from AtomPub) where clients need to know just a single entry point to find all other necessary URLs. In the case of Jazz based products like RTC, this is:

https://example.com/jazz/rootservices

The root services document allows us to discover the query URL we need by following the references to the services document:

The Discovery Chain

The Discovery Chain

So the required out-of-band knowledge to get at the query results is limited to this root URL plus some XML elements and their attributes that point to the catalog.xml, services.xml and eventually to the query URL. All of them are defined by OSLC. This means that our application will still work if RTC decides to expose querying under a different URL. The best part is that our application will also work with any other system that implements OSLC-CM 1.0 — ClearQuest, for example. We only have to configure this single entry point in our application.

Now, what does the search response look like? We have to get the change request title in order to show it in the list. As the application is written in JavaScript, JSON is our favorite representation because we get the JS object structure for free. OSLC-CM allows us to fetch resources in various formats like JSON, XML, and ATOM. In RTC, we also support HTML (for hovers) and there are more to come, like CSV or maybe PDF. Requesting the results in a specific format is done using the standard HTTP mechanism, by setting an “Accept:” header:

GET {query URL from the discovery document}?oslc_cm.query=...
Accept: "application/json"

The result is a JSON document that describes all attributes of the matching change requests. The document looks quite big, so we take a closer look at the transferred data size:

Transfer Sizes for Full Representations

Transfer Size for Full Representation

We are developing a mobile application so we have to keep the data transfers small, as bandwidth is limited (and maybe expensive). For the result list, we only need the summary for now, and everything else just slows down our application (and the server as well).

OSLC-CM specifies a solution for this in the form of the oslc_cm.properties parameter. It defines the shape of a resource, which can be tailored to any specific need. We can limit the number of included attributes, but we can also inline reference resources to avoid separate roundtrips for fetching them.

GET {query URL from the discovery document}?oslc_cm.query=...&oslc_cm.properties=dc:title
Accept: "application/json"

Let’s take another look at the data and the transfer size:

{
    "oslc_cm:totalCount":4,
    "oslc_cm:results":
    [
        {
            "dc:title":"Specify new assertThat syntax",
            "oslc_cm:score":100,
            "rdf:resource":"https:\/\/example.org\/jazz\/resource\/itemOid\/com.ibm.team.workitem.WorkItem\/_oU16MH0YEd6xQ8_tWGUF5g"
        },
        {
            "dc:title":"Provide improved Assertion syntax",
            "oslc_cm:score":100,
            "rdf:resource":"https:\/\/example.org\/jazz\/resource\/itemOid\/com.ibm.team.workitem.WorkItem\/_of-MIH0YEd6xQ8_tWGUF5g"
        },
        {
            "dc:title":"Based on the assertThat syntax we should provide assumptions and theories support",
            "oslc_cm:score":63,
            "rdf:resource":"https:\/\/example.org\/jazz\/resource\/itemOid\/com.ibm.team.workitem.WorkItem\/_oehaoH0YEd6xQ8_tWGUF5g"
        },
        {
            "dc:title":"Implement new assertThat ",
            "oslc_cm:score":25,
            "rdf:resource":"https:\/\/example.org\/jazz\/resource\/itemOid\/com.ibm.team.workitem.WorkItem\/_obk0UH0YEd6xQ8_tWGUF5g"
        }
    ]
}
Transfer Size for Tuned Representation

Transfer Size for Tuned Representation

The response document is now eighteen times smaller, only 850 Bytes instead of 15KB for the 4 results. Now we are ready to render the change requests, which doesn’t take more than a couple of lines of JavaScript. Note that we also get a reference to each change request’s URL, which we would use to get at the full data, again by a simple GET and Accept header.

var response= eval("(" + responseJSON + ")");
var results= response["oslc_cm:results"];
for (var i= 0; i < results.length; i++) {
   var changeRequest= results[i];
   var title= changeRequest["dc:title"];
   var url= changeRequest["rdf:resource"];
   ...
}

While querying for text looks quite easy, what about more structured queries or creating a new change request? This is usually harder, especially in a highly customizable environment like RTC. Work item types and their attributes are freely configurable, and so are enumerations like “Severity.” A client cannot assume that there is a “Defect” type or a specific severity. OSLC-CM has three ways to address this:

  1. Delegated UI: Instead of having all clients deal with the details of how to fetch the right value sets, finding out which attributes are required and so on, OSLC-CM specifies a way for change management service providers to expose ready-to-use HTML modules for creating and searching change requests that can be embedded into client applications. The URLs of these modules are found via the discovery document. Client applications are completely shielded from the implementation details of the module and will profit from any improvements and new features that may be added in the future. There is only a thin JavaScript interface to these components, e.g. to get the URL of the selected change request. The following screenshot shows the embeddable HTML module of a simple work item editor:

    Create Plan Item Module

    Create Plan Item Module

  2. Facades: Many clients have the need to work with conceptual values like a type “Plan Item,” a severity “High” or a state “Ready for testing.” In a freely customizable environment, these conceptual values must be mapped to actual Types, Severities, or States. This is what we call a facade. A client can work with the facade values and mapping these to the actual values is done as part of the process customization. An example from OSLC-CM is the UI module dialogs mentioned above. A client can express that the dialog should only be able to create plan items, and doesn’t have to worry about how the project is configured and which process is used. This screenshot shows the (admittedly small) UI of RTC 2.0 to map some facade entities to the concrete entities of a customized process:
    Facade Configuration

    Facade Configuration

    Future work in the OSLC-CM area will push this concept even further. Clients will have a way to express what conceptual values they want to work with. RTC will then provide the mapping UI and the runtime bindings between the facade and actual values generically.

  3. Metadata API: For the cases where both Delegated UI and Facades are not sufficient, OSLC-CM 2.0 will specify how to get at the metadata. This will allow us to build applications like a Work Item Editor that can handle any OSLC-CM compliant change request.

Implementing OSLC-CM

So far, we have seen what OSLC-CM does for consumers. With an increasing number of clients that work with OSLC-CM, it may become interesting for other change management applications to expose the same interface. OSLC-CM 1.0 was created with integration scenarios in mind and it doesn’t specify many attributes of a change request or complex meta-data structures. It focuses on linking and querying change requests, the two building blocks for surfacing interesting relationships between lifecycle resources. So the specification is rather small and was easy to implement for RTC.

The concept of a Delegated UI allows us to reuse existing components and to make them available in a standardized way. In RTC, we actually reused the existing Dojo-based widgets for this.

And finally, the discovery documents allow us to surface more functionality over time. Clients should be able to deal with the missing parts.

An interesting aspect of implementing OSLC-CM for RTC Work Items (and thinking in terms of resources and representations) was that many things fell into their place: An HTML hover is just another representation of a work item resource, and we leverage that both in the Web UI and the Eclipse UI and make it available to other parties via the Compact Rendering specification.

HTML Hover Representation

HTML Hover Representation

The CSV format as a mechanism to export query results to spreadsheets is also just another representation of a work item collection. The shape defined by oslc_cm.properties determines the exported columns in this case.

Where is OSLC-CM going?

Work has already started on OSLC-CM 2.0, which will specify more functionality for more demanding clients. There will be access to metadata, allowing clients to dynamically find out more about attributes, like their value sets and their type. More of the common change request attributes will become part of the specification.

RTC will also consume OSLC-CM in more places. Importing work items from arbitrary sources could be one application. Such an importer would create the work items using the OSLC-CM API, enabling it to import from Bugzilla, CSV etc. into any OSLC-CM compliant repository. OSLC-CM resources would also be supported as an import format, which brings it full circle: Transfer resources from any OSLC-CM compliant repository to any other.

Who is using the RTC OSLC-CM* implementation now?

  • OSLC-CM enables Mylyn to write a single connector that can work with any OSLC-CM compliant change management system
  • Rational Quality Manager uses OSLC-CM to link test cases to defects and plan items, to find out which plan items are ready for testing and more.
  • Rational Requirements Composer uses OSLC-CM to link requirements to change requests
  • The Git integration uses OSLC-CM to link work items to Git change sets.
  • RTC Build uses OSLC-CM to create work items from failed builds and to link build results to existing work items.
  • RTC Work Items uses the OSLC-CM mechanism of exposing resources in different formats for rich hovers.

* Some clients use single change request attributes that are not specified by OSLC-CM 1.0

Learn more about OSLC and OSLC-CM