OSLC-CM REST API Help

The Open Services for Lifecycle Collaboration Change Management specification (OSLC-CM) defines a lightweight, RESTful API for software change management systems. It acts as a common language for Application Lifecycle Management (ALM) tools so that you to mix-and-match your choice of tools, while maintaining an integration between them. For more details on OSLC-CM, refer to to the Open Services Web site and wiki.

IBM® Rational® Change supports the OSLC-CM 1.0 REST API specification. You can leverage this API to integrate Rational Change with OSLC-CM consumers like IBM Rational Quality Manager, expose CRs to RESTful Web service consumers like IBM Rational Publishing Engine, or to integrate your own tools and scripts with Rational Change. (This is separate from the existing SOAP-based Web services.)

Discovering services

OSLC services can be found through a series of linked XML documents. This process is known as service discovery and is fully explained in the OSLC Service Description Specification. In Rational Change, the root service discovery document can be found at:

http://<change_host>:<port>/<context>/oslc

For example: http://myserver:8600/change/oslc

If you are setting up a tool that integrates with Rational Change and already knows about the OSLC-CM API, then you may not need to examine the services yourself. The tool discovers the services on its own from the root document. If you are setting up a tool that works with RESTful Web services but does not know specifically about OSLC-CM, then you will to examine the service documents yourself.

The root discovery document contains a URL for each of your Rational Change databases. Opening a database URL lists all of your login roles, and opening a role URL lists the available services. In addition to the services described in the OSLC-CM API specification, Rational Change specific queries and reports services are also available, so you can access your your saved queries and reports.

Tools based on the Jazz platform expect a slightly different root discovery document, which is found at:

http://<change_host>:<port>/<context>/rootservices

Integrating with IBM Rational Quality Manager

IBM Rational Quality Manager 2.0 can use the Rational Change OSCM-CM API to submit new change requests and link execution results to them directly from the Rational Quality Manager Web interface. You must be a Rational Quality Manager administrator to perform this setup.

Whenever you enter the host of your Rational Change server, you must match the style that Rational Change uses for its generated links. By default, this is the IP address of the host. If you have configured Rational Change to use the hostname instead, enter the hostname into Rational Quality Manager as well.

  1. Tell Rational Change where Rational Quality Manager is.

    1. If Rational Quality Manager is running on port 9443, skip this step. Otherwise, edit the file <CHANGE_APP_HOME>\WEB-INF\wsconfig\pt.cfg.
    2. At the end of the file, add the line:
      [CCM_SYSTEM][RQM_URL]https://<RQM_HOST>:<RQM_PORT>[/RQM_URL][/CCM_SYSTEM]
      Be sure to replace the host and port for your Rational Quality Manager server.
    3. Reload your Rational Change configuration data. Log in to Rational Change in the Admin role. Click Administration > General. Click Load under Configuration Data.
  2. Add Rational Change to the whitelist.

    1. Edit the file <RQM_HOME>\server\tomcat\webapps\jazz\WEB-INF\web.xml.
    2. Create or edit context-param element for net.jazz.jfs.ServerWhitelist immediately before the first servlet element.
    3. Add your Rational Change host name and IP address (if static) to the comma-separated list value. For example:
      <context-param>
      	<param-name>net.jazz.jfs.ServerWhitelist</param-name>
      	<param-value>http://change_hostname:8600/,http://192.168.0.1:8600/</param-value>
      </context-param>
      						
  3. Restart Rational Quality Manager to reload web.xml.

  4. Setup cross-server communication.

    1. In Rational Quality Manager, click Admin > Jazz Server Administration > Cross-Server Communication.
    2. Type or select the following:
      Title: Rational Change
      Jazz URI: Your Rational Quality Manager URL to the jazz context, for example: https://rqm_host:9443/jazz
      Root Services: http://<change_host>:<change_port>/change/rootservices?rcm.nestedCatalogs=false
      Password: Anything—this is not used. Instead, users are prompted for their Rational Change password as they use Rational Quality Manager.
      Trusted: Check this option.
  5. Add links.

    1. Click Admin > Jazz Project Administration > <Your Rational Quality Manager Project Area>.
    2. Scroll down to the Links section and click Add.
    3. Choose either Implemented By or Tests.
    4. From Service Providers, choose the Rational Change database and role you will use to log in to Rational Change. Click Finish.
    5. Scroll to the top and click Save.

    If you see an error message here, you may want to access Rational Quality Manager through its fully-qualified hostname. If the error message contains an address to your Rational Change server, you should double check that that address is one you entered into the whitelist above.

  6. Update your Rational Change lifecycle (optional).

    To allow Rational Quality Manager to automatically create links from CRs back to their related execution results, add the following string attributes to your lifecycle and show forms with the OSLC_LINK Web type:

    • affectsExecutionResult
    • blocksTestExecutionRecord

Integrating with IBM Rational Publishing Engine and other REST clients

Rational Publishing Engine 1.1 can report on Rational Change CRs by adding the Rational Change OSLC-CM API as a REST data source. For more details about adding a new data source, see the Rational Publishing Engine documentation. The details below can also help you use Rational Change with other tools capable of consuming RESTful Web services.

Using existing queries and reports

To make use of your existing Rational Change CR queries or reports:

  1. Follow the steps above under Discovering Services to find the URL to either the queries or reports service.
  2. Type that URL into Internet Explorer 7 or Firefox 3 or newer to easily browse your queries or reports. If using Internet Explorer 6, download the XML file when prompted.
  3. Locate the query or report you want and copy its URL. Reports that require additional user input, like trend analysis reports, are not available.
    If using Internet Explorer 6, the document you downloaded will contain URLs to top-level folders. Type those URLs in the browser to find the contents of those folders. Repeat this process until you find the URL to the query or report you want.
  4. Optionally, you can customize the exact attributes that are returned from the URL by passing the oslc_cm.properties parameter as described in the API specification. This is not normally necessary with Rational Publishing Engine though: it will automatically request the attributes it needs based on your document specification.
  5. When creating your document specification in Rational Publishing Engine, use the URL your copied as the URI of your REST Data Source. Also, be sure to type the username and password of the user you wish to run the query or report.

Retrieving a schema

When designing your document in Rational Publishing Engine Document Studio, you will need a Data Source Schema that describes the CRs returned from your query or report. To retrieve the schema, use the same URL for your query or report, but append ?metadata=schema to it. For example:

.../reports/personal/Assigned%20CRs?metadata=schema

You can also use the metadata=schema parameter with CRs returned from the simpleQuery service if you prefer to embed an OSLC-CM query directly into your URL.

When browsing the schema in Rational Publishing Engine, the change request element is located under feed/entry/content/ChangeRequest.

Integrating with Rational Change through OSLC

If you are developing a tool to integrate with Rational Change through the OSLC-CM API, refer to the API specification for a detailed description of the API. However, understand the following Rational Change-specific implementation details:

  • Rational Change specific properties are defined in the namespace: http://www.ibm.com/xmlns/prod/rational/change/1.0/. The namespace prefix is required to be change. XML results returned from Rational Change define this prefix in the XML document. JSON results use the change prefix without defining it. Requests sent to Rational Change must follow the same convention. The oslc_cm.properties parameters assume any properties without an explicit namespace are in the change namespace.
  • Only HTTP basic authentication is supported.

Variations from OSLC-CM 1.0

  • Attribute properties with multiple values are not supported. Local and remote link properties can link to multiple resources, but attributes can only ever have one value at a time.
  • Non-admin users cannot delete CRs. This call fails if the user does not have the process admin privilege. In Rational Change, CRs should normally be sent to a terminal state instead of being deleted.

OSLC terms in Rational Change

The OSLC-CM API specification uses terms that can be shared among many change management providers and vary slightly from what you might be used to in Rational Change. These include:

Change Request
In Rational Change, this terms is the same as a normal Rational Change change request. Other OSLC-CM tools may use this term to describe other, similar resources.
Property
OSLC-CM properties are equivalent to Rational Change attributes and CR-to-CR relationships. When requesting properties, you can continue to use the existing attribute names you are already familiar with from your lifecycle. Additionally, there are a few OSLC-CM common properties, like dc:title and dc:identifier, that Rational Change automatically maps to existing attributes.
Link
OSLC-CM links are special types of properties that represent links between different OSLC resources. In Rational Change, they are normally used for traditional CR-to-CR relationships. However, when used with attributes with the OSLC_LINK Web type, they can also be used to store hyperlinks to OSLC-CM resources in other CM repositories. Remote hyperlinks can be viewed from show forms, but can only be created through this API.

© Copyright IBM Corporation 2000, 2009
US Government Users Restricted Rights--Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Notices