Get to know Open Services for Lifecycle Collaboration Change Management

How to use OSLC delegated Web dialogs

This article highlights some of the key features of the new OSLC Change Management 1.0 specification (OSLC-CM), which is part of the OSLC group of specifications. The authors use a simple HTML + Javascript interface to illustrate how you can take advantage of these features quickly and easily.


Steve Speicher ( ), Senior Software Engineer, EMC

Photo of Steve SpeicherSteve Speicher, an IBM senior software engineer, focuses on Rational change management solutions and integrations. He is the lead for the Open Services for Lifecycle Collaboration (OSLC) Change Management topic area, which delivers open REST-based specifications, as well as implementations within the Rational change management products. Steve formerly worked in emerging standardization efforts in healthcare and compound documents (W3C).

developerWorks Contributing author

Sam Padgett (, Advisory Software Engineer, WSO2 Inc

Photo of Sam PadgettSam Padgett is an IBM advisory software engineer who works within the Rational Team Concert and Rational ClearQuest development teams on Web-based technologies, OSLC Change Management (OSLC-CM), and Application Lifecycle Management (ALM) product integrations.

25 February 2010

Also available in Chinese Portuguese


A growing community focused on Application Lifecycle Management (ALM) interoperability is forming at This initiative, referred to as the Open Services for Lifecycle Collaboration (OSLC), brings together community members to define interoperability specifications that are based on key scenarios. The initial working group focused on change management integration scenarios. These specifications provide the guidance needed for service providers (the ALM tools that receive the requests) to be invoked by a variety of consumers (the ALM tools that generate the requests).

IBM® Rational® software provides many service provider implementations in products such as IBM® Rational® Team Concert™, IBM® Rational® ClearQuest®, IBM® Rational® Change, and IBM® Rational® Change Management Express. Also, there are quite a few IBM products that use these services, such as IBM® Rational® Quality Manager, IBM® Rational® Requirements Composer, and IBM® Rational® Asset Manager.

What this article covers

In this article, we use a sample application that is available in the Download section to illustrate how you can leverage several aspects of the OSLC Change Management (OSLC-CM) Version 1.0 specification:

  • Service discovery
  • Delegated resource creation
  • Delegated resource selection
  • Presentation of resources – HTML

We cover many key areas of the specifications here, although there is much more to explore. In particular, the variety authentication models and technology choices for leveraging these services deserve your attention.

This article does not cover these specification items:

  • Query
  • Resource (defect, bug) property retrieval
  • Resource creation and modification

Nonetheless, this article gives you with a good starting point for taking advantage of these services quickly, with minimal effort.

Sample application setup

This article features a sample OSLC Change Management consumer that is written entirely in Javascript, using the Dojo Javascript Toolkit. The sample helps readers connect to an OSLC Change Management provider and create or find change requests.

Server proxies in Jazz-based software

The same-origin policy in browsers can pose problems when building real-world integrations between Web applications. These restrictions protect users from a host of cross-site scripting exploits, but Web applications from different domains often legitimately need to communicate. The OSLC-CM specifications offer a solution for delegated Web UIs, which is discussed in the IFrame Communication section here. Web developers who need to perform service discovery tasks still need to wrestle with this problem, however.

IBM® Jazz™ technology-based products, such as Rational Team Concert and Rational Quality Manager, solve this problem by using server proxies. Requests flow through the origin server but are forwarded to the CM-provider server. See "Interacting with Remote Data" on for more details (see Resources).

In this sample, the Javascript client connects directly with the OSLC-CM provider. Browsers typically restrict Javascript HTTP requests to the source domain of the document. This is known as the same-origin policy (see sidebar). Therefore, to run the sample, you must work around this issue in one of two ways:

  1. Extract the files to your local file system, and open the oslc.html file in a browser that permits local HTML files to access the Internet through XMLHttpRequest. (Of the major browsers, only the Apple Safari Version 4.0 browser allows this.)
  2. Deploy the files to the same Web server as the CM provider. Consult your CM provider's application server documentation for appropriate location.
    • On an IBM® WebSphere® Application server, place the files in the htdocs directory.
    • On an Apache Tomcat server, place the files in the webapps directory

After you have loaded the sample page into your browser, simply enter the base REST URI into the Service URL text field, and click Go!

For Rational Team Concert, this is typically the path to enter (where <bracketInfo> is a variable for your location):


Create change requests to use

To create change requests, click New Change Request or, to find an existing change request, click Find Change Request.

As you create and select items, the sample adds them as links to the page. Clicking the link opens the change request in a new browser window.


To access protected data in a change management system such as Rational Team Concert, you typically must furnish a user name and password. OSLC takes a "just enough" approach to integrations, by reusing existing standards where it makes sense. Authentication is no exception, and the OSLC-CM 1.0 REST API specification states that providers should support Basic HTTP Authentication and OAuth (see Change Management REST API: Security and Authentication).

Therefore, for simplicity, we've assumed here that the change management provider is configured for Basic HTTP Authentication. This lets the browser take care of any login prompts for you, making it transparent in the Javascript sample client (see Figure 1).

Figure 1. A basic HTTP authentication dialog
The browser prompts for a name and password

IBM Rational Team Concert, Rational ClearQuest, and Rational Change can all be configured for Basic HTTP Authentication of their OSLC services. For the examples in this article, we use Rational Team Concert Version 2.0 configured for Basic HTTP Authentication.

It is also possible to enable this sample to work with other authentication approaches. For example, you can simply log into the CM provider's Web user interface first so that the browser will establish the necessary authentication prerequisites, and then subsequent requests will be successful.

Service discovery

The OSLC-CM 1.0 service discovery model offers the flexibility that you need for various change management providers by using a nesting structure for service provider catalogs. From these catalogs, you can locate further information regarding additional catalogs or documents that describe the completed configuration, which are known as service description documents. Figure 2 shows an example from Rational Team Concert that provides a single service provider catalog that has entries for each of its projects, which in turn reference a service description document for each project hosted by that server.

Figure 2. Sample of service discovery using Rational Team Concert
Diagram: service catalogs point to descriptors

The service provider catalog is an optional part of the service discovery process. The catalog provides references to additional catalogs or entries for service description documents. The service description document provides the discovery end point.

The sample included in the Download section here starts with a URL for either a service provider catalog or a service description document, as shown in Figure 3.

Figure 3. Enter a URL for service discovery
The Rational Team Concert service URL

If you are new to Dojo and Javascript, this may not be obvious. The code in Listing 1 is simply performing an HTTP GET operation on the URL provided, requesting the acceptable content types of either a PROVIDER_CATALOG or SERVICE_DESCRIPTION.

Listing 1. Requesting service discovery documents
    url: url,
    headers: {
load: dojo.hitch(this, function (data, ioArgs) {
    var catalog, serviceDescription;
    var rh = ioArgs.xhr.getResponseHeader("Content-Type").split(";", 1);
        this.catalog = this.parseServiceProviderCatalog(data);
      if (typeof callback.loadCatalog == 'function') {
      this.serviceDescription = this.parseServiceDescriptionDoc(data);
      if (typeof callback.loadServiceDescription == 'function') {

Listings 2 and 3 highlight the HTTP request and response.

Listing 2. HTTP request for service discovery
GET https://localhost:9443/jazz/oslc/workitems/catalog.xml
Accept: application/x-oslc-disc-service-provider-catalog+xml, 
Listing 3. Service provider catalog response
Content-Type: application/x-oslc-disc-service-provider-catalog+xml

<?xml version="1.0" encoding="UTF-8"?>
  <dc:title>Project Areas</dc:title>
      <dc:title>JUnit Project</dc:title>
        rdf:resource="https://localhost:9443/jazz/process/project/1" />
        rdf:resource="https://localhost:9443/jazz/oslc/1/wi/services.xml" />
    <dc:title>Test Automation</dc:title>
       rdf:resource="https://localhost:9443/jazz/process/project/2" />
       rdf:resource="https://localhost:9443/jazz/oslc/2/wi/services.xml" />

The response has been altered a bit for this article, but it illustrates the key elements of the catalog. There are two <oslc_disc:entry> elements, and each has a <oslc_disc:ServiceProvider> element. Knowing that these are references to service provider's service description documents, we know that we are close. It would also be possible to have more catalogs as entries, which the attached sample code does handle. From the catalog, we see that is has a title of Project Areas, which can be used as a label for a selection list. Likewise, each service provider entry has a <dc:title> element, which can be used as an entry to the selection list. Figure 4 shows JUnit Project and Test Automation as options in the drop-down menu for the Rational Team Concert Project Areas selection.

Figure 4. Display of service providers
Project Areas field highlighted

The Javascript used to parse and present the choices simply parses the catalog to locate the needed elements, then instantiates the appropriate controls.

After a selection is made from the sample, the sample makes another request (Listing 4) in a similar way, although this time the expected response is a service description document.

Listing 4. HTTP request for service description document
GET https://localhost:9443/jazz/oslc/contexts/1/workitems/services.xml
Accept: application/x-oslc-disc-service-provider-catalog+xml,

At this point, you can use the <oslc_disc:services> to determine the URL to request the document. Listings 5 and 6 show the responses.

Listing 5. Response of service description document (contributor fragment)
Content-Type: application/x-oslc-cm-service-description+xml
<?xml version="1.0" encoding="UTF-8"?>
  <dc:title>JUnit Project</dc:title>
  <dc:description>IBM Rational Team Concert OSLC CM Service Description for Project
  'JUnit Project'</dc:description>
    <dc:title>IBM Rational Team Concert Work Items</dc:title>

The <dc:contributor> fragment in Listing 5 provides information about the service provider tool and vendor for informational purposes. There is further configuration information in the <oslc_cm:changeRequests> section of the document that indicates URLs used later in this article for creating and selecting change requests. See Listing 6.

Listing 6. Response of service description document (changeRequest fragment)
Content-Type: application/x-oslc-cm-service-description+xml
  <oslc_cm:changeRequests oslc_cm:version="1.0">
      <dc:title>Work Items Home</dc:title>
    <oslc_cm:creationDialog oslc_cm:default="true"
        oslc_cm:hintWidth="740px" oslc_cm:hintHeight="510px">
      <dc:title>New Defect</dc:title>
    <oslc_cm:creationDialog oslc_cm:hintWidth="740px" oslc_cm:hintHeight="510px">
      <dc:title>New Plan Item</dc:title>
    <oslc_cm:selectionDialog oslc_cm:default="true"
        oslc_cm:hintWidth="550px" oslc_cm:hintHeight="360px">
      <dc:title>Work Item Selection</dc:title>
    <oslc_cm:factory oslc_cm:default="true">
      <dc:title>Default location for creation of change requests</dc:title>
      <dc:title>CQL based change request queries</dc:title>

The key elements for this article are from this discovery document:

  • <oslc_cm:creationDialog>
  • <oslc_cm:selectionDialog>

These elements provide the information that you need to create an IFrame that can be used to host these Web page fragments. The following sections will explain, in detail, how this information is used to present these dialogs, with code examples.

Figure 5 shows the sample application after service discovery has been completed. Service discovery is considered complete when a service description document has been obtained.

Figure 5. Service discovery finished
Selection and creation dialog buttons

Delegated Web UIs

OSLC Change Management providers offer more than just REST APIs for accessing data programmatically. They also give you a way to embed change management dialogs inside of your applications. These delegated Web UIs are a key aspect of many OSLC integrations.

This approach enables developers to build loosely coupled, seamless integrations between ALM tools. You can display feature-rich dialogs from the change management application with minimal knowledge about the application. Additionally, different change management providers can be swapped with virtually no code impact to the change management consumer.

Providers support two kinds of delegated Web UIs:

  • Creation dialogs
  • Selection dialogs

Resource creation

You can use creation dialogs to submit new change requests. The change management provider renders the content of these dialogs and, thus, controls both layout and validation. An OSLC Change Management consumer can then display a fully functioning Submit dialog without duplicating all of the business logic behind the dialog.

Figure 6. Creating a new change request
Rational Team Concert
Figure 7. Resulting link to the new change request
The new work item is saved as a link

Imagine that Sue, a tester, is working in a quality management application, such as Rational Quality Manager. She finds a bug in the product she tests and needs to file a defect. Ideally, she should be able to create the defect record directly from within the quality management application and then store a link in the test execution record to the newly created defect report. By using OSLC delegated Web UIs, she can do this and do all of her work within one application.

A provider's creation dialogs are listed as creationDialog elements in the service description XML document, as highlighted in previous sections on service discovery.

Resource selection

What if Sue knows that there is already a defect record for a bug, which is blocking her testing? This time, she uses a delegated selection dialog to link her test execution record to an existing defect. She can launch this dialog from the sample by clicking the Find Change Request button, which launches the contributed Rational Team Concert window.

Figure 8. Selecting an existing change request
Work Item Selection dialog
Figure 9. Resulting links to change requests
The selected work item is saved as a link

Again, the change management provider controls the content of this dialog. Therefore, Sue can use any search and query capabilities of the change management application to find the defect record that she is looking for. When she finds the defect, she adds it as a link in her test execution record, never leaving the quality management tool.

A CM provider's selection dialogs are listed as selectionDialog elements in the service description document.

IFrame communication

So how does all of this work?

OSLC delegated Web UIs are designed to work across domains, where the change management provider is located on a server different from the host application. For security reasons, modern Web browsers prohibit HTTP requests to different domains. However, OSLC delegated Web UIs are embedded in HTML IFrame elements (see Figure 10). This means that they appear directly within a host application even when the two applications are on entirely different servers in different domains. (See the diagram in Figure 10.)

Figure 10. An ALM tool embeds a change management dialog in an IFrame
The IFrame URL points to an embedded dialog

Embedded dialogs send messages back to the host application in one of two ways: by using either the Post Message protocol or the Window Name protocol. The host application determines which protocol to use, based on the browser's capabilities. Listing 7 shows Javascript code to test to see which mode to use and how to create an iFrame from using the results of this test.

Listing 7. Choosing an IFrame protocol
// Tests to see if this browser supports window.postMessage
OslcCmConsumer.prototype.isPostMessageSupported = function () {
    // Older versions of IE define a method window.postMessage() that does
    // something else, so we can't simply test for typeof (window.postMessage).
    if (dojo.isIE && dojo.isIE < 8) {
        return false;

    return typeof window.postMessage == 'function';

// Creates an IFrame to show a Delegated Web UI.
OslcCmConsumer.prototype.createIFrame = function (url, container) {
    // Determine which IFrame protocol to use.
    if (this.isPostMessageSupported()) {
        this.postMessage(url, container);
    } else {
        this.windowName(url, container);

In Listing 7 there was a function referenced postMessage(), which is a local function defined in Listing 8. This function uses the Post Message protocol and works in the latest versions of most browsers and is preferable. It uses the window.postMessage() function in HTML 5 to send events to the observing host application.

Listing 8. Post Message example
OslcCmConsumer.prototype.postMessage = function (url, container) {
    // Step 1
    url += '#oslc-postMessage-1.0';

    // Step 2
    var iframe;
    var listener = dojo.hitch(this, function (e) {
        var HEADER = "oslc-response:";
        if (e.source == iframe.contentWindow && === 0) {
            // Step 4
            window.removeEventListener('message', listener, false);
    window.addEventListener('message', listener, false);
    // Step 3
    iframe = document.createElement('iframe');
    iframe.src = url;
    // Display the IFrame.

To display a dialog by using the Post Message protocol, you must complete these steps:

  1. Tell the OSLC-CM provider to use the Post Message protocol by appending this to the dialog URL:
  2. Add an event listener for window message events. The listener tests to see whether the message content begins with the oslc-response: header, which indicates that this is an OSLC message.
  3. Create an IFrame element, and set the IFrame src to the dialog URL.
  4. When the window message event is received, remove the event listener, and handle the message that is returned.

The Window Name protocol is more involved, but it must be used in older browsers that do not support window.postMessage(). As Listing 9 shows, it works around cross-site scripting restrictions by passing the OSLC results message as one of the content window properties of the IFrame, which the host application can read.

Listing 9. Window Name example
OslcCmConsumer.prototype.windowName = function (url, container) {
    // Step 1
    url += '#oslc-windowName-1.0';

    // Step 2
    var iframe = document.createElement('iframe');
    var frameState = 0;
    iframe.onload = dojo.hitch(this, function () {
        var data;
        if (!frameState) {
            // Step 5
            try {
                // May throw an exception if the IFrame's location is
                // still a different origin
                data =;
                if (data != this.returnLocation) {
                    frameState = 1; // we are done now
                    if (data) {
            } catch(e) {
                // ignore: access exception when trying to access window name
    // Step 3
    // Set to a URL of a blank page on the observer's domain. = this.returnLocation;
    // Step 4
    iframe.src = url;

To display a dialog by using the Window Name protocol, you must follow these steps:

  1. Tell the OSLC-CM provider to use the Window Name protocol by appending this to the dialog URL:
  2. Create an IFrame element and assign a listener for onload events.
  3. Set the IFrame's Name property to a blank page on the host application's domain. (When the dialog has been closed, the OSLC-CM provider will set the IFrame src to this URL so that the observer can read properties of the IFrame.)
  4. Set the IFrame src to the dialog URL.
  5. In the onload event handler, read the IFrame's property, which now contains the OSLC response message. The client's onload event handler is invoked when the CM provider sets the IFrame src to the return URL.

Unfortunately, working with IFrames in Microsoft® Internet Explorer has a few quirks. This example omits Internet Explorer workarounds for clarity. See the attached code sample for details (in the Download section).

The OSLC response message is a Javascript Object Notation (JSON) object that contains an oslc_cm:message property, indicating what operation was performed, and an oslc_cm:results property, an array of resources. Each resource is a JSON object with two properties: oslc_cm:label property, which defines a simple display label, and the rdf:resource property, which is the URI of the resource being referenced.

Listing 10. Handling an OSLC response message
var response = dojo.fromJson(message);
var messageType = response['oslc_cm:message']; // "oslc_cm:create" or "oslc_cm:select"
dojo.forEach(response['oslc_cm:results'], function (next) {
    var label = next['oslc_cm:label'];
    var uri = next['rdf:resource'];
    // ...

A little bit about the final resource URL

After a change request has been created or selected from the previous examples, the result is a URL of a change request resource that can be used to retrieve, update or even delete that change request. Because this article focused on browser-based access to these services, it would be natural to expect an HTML version of the change request that can be used as a presentation form of the change request. As the OSLC-CM specification indicates, other formats can be requested, such as XML or JSON variants. This article highlights only the HTML format by allowing a clickable hyperlink within the sample page. See the Resources section for additional information.


This article has taken you through a simple process that starts with a URL and discovers the services available by using the Rational Team Concert OSLC-CM provider. A working sample is included (see Download) that you can use to get a better understanding of OSLC-CM, to help validate your own provider, or to jump start your own consumer implementation. From the service descriptor, you could use delegated Web user interfaces for creating and selecting change request resources. This discovery and delegation provides a quick and powerful method for achieving a loosely coupled integration. There are many other features in the OSLC-CM specification, including resource manipulation, query capabilities, other creation models, and more.


Sample application.oslc-sample.zip7KB



  • See Interact with Remote Data for more details (requires registration).
  • Check the latest developments of OSLC by visiting the Web site.
  • Learn more about the Rational software mentioned in this article:
    • IBM Rational Asset Manager helps you catalog, organize, use, reuse, manage, and report on any type of asset – business, technology or software – across your enterprise
    • IBM Rational Change integrated, Web-based, enterprise change management
    • IBM Rational Change Management Express, which is included in Rational Team Concert, with integrated work item tracking
    • IBM Rational ClearQuest provides change tracking, process automation, reporting and traceability for better visibility and control
    • IBM Rational Quality Manager offers a Web-based, centralized test management environment that provides a collaborative and customizable solution for test planning, workflow control, tracking, and metrics reporting
    • IBM Rational Requirements Composer for collaborative requirements definition and updates for fast-paced projects with high stakeholder involvement
    • IBM Rational Team Concert provides work item, change management, and build management for real-time collaboration that makes software teams more productive and processes more transparent
  • Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management. You can find product manuals, installation guides, and other documentation in the IBM Rational Online Documentation Center.
  • Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  • Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Some of the "Getting Started" courses are available free of charge.
  • Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.

Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

Zone=Rational, DevOps
ArticleTitle=Get to know Open Services for Lifecycle Collaboration Change Management