Access OSLC services from IBM Rational DOORS



IBM® Rational® DOORS® is requirements management software designed to assist in complex and embedded systems development. Rational DOORS V9.3 implements OSLC Requirements Management V1 and, from V9.4 onwards, implements OSLC Requirements Management V2 interface. This article references DOORS V9.4.

In order to use these services, IBM Rational DOORS Web Access, the web interface for DOORS, must be installed and configured.

The services provided by DOORS can be easily used by any application using HTTP. As per OSLC RM V2 specifications, services provided by DOORS can be categorized as follows:

Delegated User Interfaces
Provide a mechanism to display DOORS Web Access user interface in the consuming application to create or select a requirement.
Query Capability
Provides a base URI for an artifact container on which queries can be run.
Operations on resources
Provides mechanism to perform basic operations on the given resource using GET, PUT, or DELETE.
Creation Factory
Provides a base URI to create a requirement using POST.

Each of these capabilities is accessible via a chain of URIs. How to discover these URIs and how to use these services is explained in the following sections. All of the services and resources are protected using OAuth with the exception of the rootservices document which is the starting point of discovery. DOORS supports both OAuth 1.0 and OAuth 1.0a. This article does not cover negotiating OAuth in detail, but some basic pointers are provided in the Notes section towards the end of the article. To explain each of the capabilities, I've used RESTClient (add-on for Mozilla Firefox), demonstrating how to use these services.

Discovering services

Rootservices document serves as the starting point for discovering services provided by DOORS. This document can be accessed at the following URI:

Performing a GET on the above URI will return a document in Resource Description Framework (RDF)/XML, listing the services at the root level of the application along with other configuration details like OAuth related URIs. Listing 1 shows a sample rootservices document returned by DOORS:

Listing 1. Rootservices document
<rdf:Description rdf:about=""> <jd:registration rdf:resource=""/> <jfs:oauthDomain></jfs:oauthDomain> <jfs:oauthUserAuthorizationUrl rdf:resource=""/> <dc:title>RM on DOORS9501</dc:title> <jfs:oauthAccessTokenUrl rdf:resource=""/> <trs:trackedResourceSet rdf:resource=""/> <jfs:oauthRequestConsumerKeyUrl rdf:resource=""/> <oslc_rm:rmServiceProviders rdf:resource=""/> <jfs:oauthRealmName>DWA</jfs:oauthRealmName> <jfs:oauthRequestTokenUrl rdf:resource=""/> <jd:oslcCatalogs> <oslc:ServiceProviderCatalog rdf:about=""> <oslc:domain rdf:resource=""/> </oslc:ServiceProviderCatalog> </jd:oslcCatalogs> </rdf:Description>

The Mozilla Firefox add-on RESTClient was used on most the URLs to perform the GET, PUT, POST. Where headers used aren't explicitly mentioned, Content-Type was set to "application/rdf+xml" and "oslc-core-version" was set to "2.0".

As Listing 1 shows, the lines in JFS namespace are configuration details related to gaining access to protected resources/services using OAuth. The last section of this article explains how to gain access via OAuth.

The URI necessary to discover the OSLC services provided by DOORS is Service Provider Catalog (ServiceProviderCatalog), found in oslc namespace. Service Provider URIs is a collection of services that allows access to the actual resources.

Figure 1. Diagrammatic representation of this discovery chain
Discovering chain of links
Discovering chain of links

From a comparison point of view, the Service Provider Catalog can be viewed loosely as a Project / Folder and Service Provider as a Module / View.

Service Provider Catalogs, Service Providers, and services

A Service Provider Catalog is a list of Service Providers or more Service Provider Catalogs. A Service Provider can be seen as the actual gateway to the artifacts in the tool, made available for further manipulation like creating/updating/linking etc, by the consuming application. Such capabilities provided for further manipulation are referred to as Services.

Figure 2. Diagrammatic representation found in OSLC Core Specification V2, depicting implementation in DOORS.
Representation of OSLC Service provider
Representation of OSLC Service provider

The icons above the Service Provider Catalog and Service Provider boxes denote the mapping to the hierarchical items in Rational DOORS.

Requirements in DOORS are always contained within a Formal Module, thus acting as a basic container of artifacts. Formal Modules thus act as Service Providers, providing accessing applications with the capabilities to interact with the data it contains. In OSLC terminology, we refer to such a container of artifacts as Requirement Collection. Thus, Views within Formal Modules also act as separate Service Providers. This allows the accessing application to access specific set of requirements as defined within the View

Listing 2 is an excerpt from Service Provider Catalog and shows how Service Providers are defined. The URL specified by oslc:serviceProvider allows you to access the Service Provider

Listing 2. Reference to Service Providers in Service Provider Catalog
<oslc:serviceProvider rdf:resource=" 515ad1367be43903:1-515ad1367be43903-M-00000080"/> <oslc:serviceProvider rdf:resource=" 515ad1367be43903:1-515ad1367be43903-M-00000080/view:00000004"/>

Formal Modules in turn are always contained within a Project or a Folder, which further allows for partitioning of data in DOORS. Thus, Project and Folder, serve as Service Provider Catalogs, providing the ability to the consuming application to request for artifacts in specific contexts. Rootservices document contains the initial catalog, listing Service Provider Catalogs for each Project / Folders directly under DOORS database root.

Now that we have an understanding of how to discover Service Providers starting from rootservices document, let us look at the actual services that DOORS provides. As defined by OSLC RM V2 Specifications, DOORS provides 3 types of services

  • Delegated User Interfaces (UIs)
  • Query Capability
  • Creation Factory

Let's explore on each of these services and their capabilities in the following sections.

Delegated UIs

Delegated UI dialogs provide a mechanism to either create or select an artifact through a web interface native to the providing application, within the context of accessing application. For example, if you would like to provide an option to create an artifact in DOORS from within your application, Creation Dialog URI would help you achieve this. Invoking the Creation Dialog URI will bring up a DOORS Web Access UI that allows for creation of the artifact. Figure 3 shows sample Creation UI flow.

Figure 3. Using Creation UI
Creation UI workflow
Creation UI workflow

Note 1:
The screenshots in Figure 3 are from DOORS version The delegated UIs have been modified slightly in the recent version, with user friendly messages at the top of each screen indicating what action is expected.

Note 2:
Delegated UI Service provided in each of the Service Providers allows the user to select any artifact in DOORS, not limited to the context of the Service Provider. This behavior would be changed to make it specific to the context provided by the Service Provider.

There are two types of Delegated UI are offered by DOORS:

  • Creation UI
  • Selection UI

Creation UI allows for creating an artifact. The user is able to choose the hierarchical location within the Formal Module where the artifact is to be created. When a user chooses the location, an object, the Create button offers the option of creating artifact After or Below the selected object as shown in Figure 3. After making the selection, the user can provide values for Object Heading, Object Text and Object Short Text. Once the artifact is created, the user will be prompted to enter the value for Label, which will be the OSLC Title* for that artifact. After the artifact is created, the URL of the artifact / object is returned to the accessing application. This can be in turn used to create a link / reference in the accessing application.

Selection UI allows for selecting an artifact. Typical usecase of this UI is for linking artifacts in the providing and consuming application. Selection of an artifact returns the URI of that artifact in DOORS, which can be used to create a link / reference in the consuming application.

A link to the artifact in consuming application can be created in the providing application (DOORS), by making a GET request on the URI, adding the link information to the obtained RDF content and then making a PUT on the resource URI. This process of link creation is often called Backlink creation. We will cover this in detail in the Updating Artifacts section.

By default, OSLC Title unless provided by the user, will be first 50 characters of the Object Heading; if Object Heading does not have a value, then first 50 characters of the Object Text.

Listing 3 is an excerpt from Service Provider document that shows details of Delegated UIs. The <oslc:CreationDialog> identifies the node that provides details of Creation UI. In this node, <oslc:dialog rdf:resource> refers to the actual URL to be used to use this UI. Similarly, <oslc:CreationDialog> identifies the node that provides details of Selection UI. Note that there are two Selection UIs, one for selecting Requirement and another for selecting a Requirement Collection.

Listing 3. Delegated UI definition in Service Provider document
<oslc:service> <oslc:Service> <oslc:domain rdf:resource=""/> <oslc:selectionDialog> <oslc:Dialog> <dcterms:title rdf:parseType="Literal"> Select requirement from User Requirements Document</dcterms:title> <oslc:label>User Requirements Document</oslc:label> <oslc:dialog rdf:resource=" selectRequirement/urn:rational:ers-515ad1367be43903:1-515ad1367be43903-M-000000a2"/> <oslc:hintWidth>600px</oslc:hintWidth> <oslc:hintHeight>500px</oslc:hintHeight> <oslc:usage rdf:resource=""/> <oslc:resourceType rdf:resource=""/> </oslc:Dialog> </oslc:selectionDialog> <oslc:creationDialog> <oslc:Dialog> <dcterms:title rdf:parseType="Literal"> Create requirement in User Requirements Document</dcterms:title> <oslc:label>User Requirements Document</oslc:label> <oslc:dialog rdf:resource=" createRequirement/urn:rational:ers-515ad1367be43903:1-515ad1367be43903-M-000000a2"/> <oslc:hintWidth>600px</oslc:hintWidth> <oslc:hintHeight>500px</oslc:hintHeight> <oslc:usage rdf:resource=""/> <oslc:resourceType rdf:resource=""/> </oslc:Dialog> </oslc:creationDialog> <oslc:selectionDialog> <oslc:Dialog> <dcterms:title rdf:parseType="Literal"> Select requirement collection from User Requirements Document </dcterms:title> <oslc:label>User Requirements Document</oslc:label> <oslc:dialog rdf:resource=" selectRequirementCollection/urn:rational:ers-515ad1367be43903:1- 515ad1367be43903-M-000000a2"/> <oslc:hintWidth>600px</oslc:hintWidth> <oslc:hintHeight>500px</oslc:hintHeight> <oslc:usage rdf:resource=""/> <oslc:resourceType rdf:resource=" rm#RequirementCollection"/> </oslc:Dialog> </oslc:selectionDialog>

Query capability

Query capability, offered by DOORS, provides the mechanism to the consuming application necessary to get a list of artifacts meeting a specific criteria. Criterias can be one or a set of conditions to be met, for the values of different properties of the objects in the Formal Module. Properties can be loosely viewed as attributes of the objects; but not limited to attributes alone. It can also represent the state of the object (if soft-deleted or not), links to other artifacts etc.

Syntax for specifying query parameters, is as per the OSLC Core Specifications V2. DOORS supports use of, oslc.where, oslc.orderBy, oslc.searchTerms. The link above describes in detail on how to use each of these parameters.

The scope of query is defined by the context of the Service Provider. Each Service Provider provides a base URI for querying, tagged as oslc:queryBase. The base URI must be used along with one or more query parameters such as oslc.where / / oslc.searchTerms / oslc.orderBy. The resulting RDF response will contain URI of the object that meets the criteria along with the Title of the object.

Constructing a query

To construct a query, one needs the following details:

  • Query Base URL
  • Resource Shape URL – The definition of properties based on which queries can be made
  • Syntax of query

Query Base URL can be found in the Service Provider document, tagged as <oslc:queryBase> within the node <oslc:queryCapability> This forms the first part of the URL that we would use to send a query. The second part will contain the query parameters.

Before we dive into query parameters, we need to know what properties of the artifact can be queried. This is defined in the Resource Shape. URI to the Resource Shape is also included in the definition of the Query Capability. Listing 4 is an excerpt from a Service Provider document and shows the Query Capability node.

Listing 4. Excerpt of queryCapability from a Service Provider document
<oslc:queryCapability> <oslc:QueryCapability> <dcterms:title rdf:parseType="Literal">Query in User Requirements Document</dcterms:title> <oslc:label>User Requirements Document</oslc:label> <oslc:queryBase rdf:resource=" query/urn:rational:ers-515ad1367be43903:1-515ad1367be43903-M-000000a2"/> <oslc:resourceShape rdf:resource=" oslc/shape/requirement/urn:rational:ers-515ad1367be43903:1- 515ad1367be43903-M-000000a2"/> <oslc:resourceType rdf:resource=""/> <oslc:usage rdf:resource=""/> </oslc:QueryCapability> </oslc:queryCapability>

Performing a GET on the Resource Shape will return the properties of the artifacts in that container (Formal Module). The definition of the property will include specifics such as whether that property is modifiable and what kind of value is accepted by that property. Listing 5 is an excerpt of couple of properties of an artifact found in the Resource Shape of a Formal Module.

Listing 5. Sample properties from ResourceShape
<oslc:Property> <oslc:readOnly rdf:datatype="">true</oslc:readOnly> <dcterms:title rdf:parseType="Literal">Created By</dcterms:title> <oslc:valueType rdf:resource=""/> <oslc:occurs rdf:resource=""/> <oslc:propertyDefinition rdf:resource=" M-000000a2/types/attrDef-4"/> <oslc:name rdf:datatype="">attrDef-4</oslc:name> </oslc:Property> </oslc:property> <oslc:property> <oslc:Property> <oslc:representation rdf:resource=""/> <oslc:readOnly rdf:datatype="">false</oslc:readOnly> <dcterms:description rdf:parseType="Literal"> Link to a resource, such as a test case, which validates this resource. </dcterms:description> <dcterms:title rdf:parseType="Literal">Validated By</dcterms:title> <oslc:valueType rdf:resource=""/> <oslc:occurs rdf:resource=""/> <oslc:propertyDefinition rdf:resource=""/> <oslc:name rdf:datatype="">validatedBy</oslc:name> </oslc:Property> </oslc:property> <oslc:Property> <oslc:readOnly rdf:datatype="">true</oslc:readOnly> <dcterms:description rdf:parseType="Literal">Modified date of the DOORS object</dcterms:description> <dcterms:title rdf:parseType="Literal">Modified</dcterms:title> <oslc:valueType rdf:resource=""/> <oslc:occurs rdf:resource=""/> <oslc:propertyDefinition rdf:resource= ""/> <oslc:name rdf:datatype= "">modified</oslc:name> </oslc:Property> </oslc:property>

The first property definition in Listing 5 excerpt is that of Last Modifiedy By attribute of an object.
The value of readOnly tag, indicates that it is Read Only property and the valueType indicates the value to be of type String.

The occurs tag represents the multiplicity of the value of the property, where One-Or-More would mean the property is a multivalued enumerated attribute.

The second property definition in the above excerpt is that of a Link Type – Validated By. This is one of the Collaboration Link, which is to be used while linking an artifact from QM domain, like a Test Case or Test Plan.

Note the last property in the above excerpt, which is one of the mandatory property of a Requirement Resource. A list of such mandatory properties can be found Resource Requirement section of OSLC RM Specifications V2. Native attributes of Rational DOORS are to be identified using the dcterms:title in each oslc:property. Note that query syntax however uses oslc:name and not dcterms:title.

Syntax of query

For detailed information about syntax, it is best to refer to the OSLC Core Specifications V2 Query Syntax. However, following is an attempt to get you started with some simplified illustrations.

Basic structure of a query URL:
<queryBase URL>?<query parameters –>

Each of these query parameters will use properties of the artifact in the following format:

Each property definition in the Resource Shape consists of oslc:propertyDefinition and oslc:name. Former identifies the namespace and latter name of the property. Comparison operators like =, !=, >, >=, <, <= are used to define the conditions. Boolean operator "and" can be used with However, "or" is not supported.

Example Queries:

All the following samples needs to be URL encoded, appended to the queryBase URL.

  • Simple query - Created by John
  • Compound query - Modified date is greater than 31st January 2013 AND attribute "isReq" is set to True (attrDef1002 is the name to be used for isReq, as obtained from the instance shape for the queryBase)
    ?oslc.where=dcterms:modified>"31 January 2013" and rm_property:attrDef1002=true
  • Using multiple query parameters - Modified date is greater than 31st January 2013 AND attribute isReq is set to true, select Creator, Title and Implemented By relationship
    ?oslc.where=dcterms:modified>"31 January 2013" and rm_property:attrDef1002=true&amp;,dcterms:title,dcterms:creator{*}

Note the usage of {*} in the above query. Creator is a property represented as foaf, where the name of the user is a nested property. Details of nested property can be queried/obtained using {} operators and wildcards too can be used while constructing a query.

Creation Factory

Creation Factory provides a mechanism to create artifacts in a container without user intervention. An artifact is created by doing a POST on the Creation Factory URL. A definition of Creation Factory can be found in the Service Provider document, tagged as creationFactory.

Similar to Query Base capability, the definition of Creation Factory capability contains a Resource Shape URL. Listing 6 is a snippet of Creation Factory capability defined in a Service Provider document.

Listing 6. Excerpt of Creation Factory definition from Service Provider document
<oslc:creationFactory> <oslc:CreationFactory> <dcterms:title rdf:parseType="Literal">Create requirement in User Requirements Doc</dcterms:title> <oslc:label>User Requirements Doc</oslc:label> <oslc:creation rdf:resource=" 515ad1367be43903:1-515ad1367be43903-M-000000a2"/> <oslc:hintWidth>600px</oslc:hintWidth> <oslc:hintHeight>500px</oslc:hintHeight> <oslc:usage rdf:resource=""/> <oslc:resourceShape rdf:resource=" 515ad1367be43903:1-515ad1367be43903-M-000000a2"/> <oslc:resourceType rdf:resource=""/> </oslc:CreationFactory> </oslc:creationFactory>

Use the Resource Shape URL as reference to determine what properties needs to be supplied while creating an artifact. For example, identify the mandatory properties and ensure the body of POST contains those.

Following is a sample content, to be used with Creation Factory:

Action: POST
Header: Content-Type: application/rdf+xml
oslc-core-version: 2.0

<rdf:RDF xmlns:dcterms="" xmlns:rdf="" xmlns:doors="" xmlns:oslc="" xmlns:rm_property=" 515ad1367be43903-M-00000080/types/" xmlns:oslc_rm="" xmlns:rm="" > <oslc_rm:Requirement> <oslc:resourceShape rdf:about=" requirement/urn:rational:ers-515ad1367be43903:1-515ad1367be43903-M-000000a2" /> <rm_property:attrDef-12 rdf:datatype=""> Created using OSLC Creation Factory</rm_property:attrDef-12> <rm_property:attrDef-11 rdf:datatype=""> Just some text for Object Text</rm_property:attrDef-11> </oslc_rm:Requirement> </rdf:RDF>

A successful POST will return Status Code 201 – Created. One of the Response Header, Location will return the URL of the object created in DOORS and the response body in itself will contain the RDF representation of the object created.


  1. Artifacts created using Creation Factory are always created as the first object in a DOORS module. It is not possible to control the location of the artifact using this method.
  2. Its important to include <oslc:resourceShape> in the body of POST, else creation of resource will fail.

Updating artifacts

Update operation is mainly used to create relationships between artifacts in two application domains, one of the objectives of OSLC.

Update operation typically involves 3 steps:

  1. Perform a GET on the artifact that needs updated
  2. Modify the response body as required
  3. Perform a PUT on the artifact

Artifact URL, to perform a GET can be obtained in multiple ways, as explained in the earlier sections. Using Query Capability, artifact URL can be obtained from the body of the response; rest all the methods (Creation/Selection UI, Creation Factory) returns artifact URL in the Response Header named "Location".

Identify modifiable properties of the artifact using the Resource Shape, before modifying the body. Relationships to other artifacts can be created (inserted) into the body. For a list of relationships that a Requirement artifact can contain, refer to the "Relationship properties" table in the section Resource Requirement of OSLC RM V2 Specs.

To perform a PUT, it is necessary to include Etag value in If-Match header. Etag can be obtained as part of Response Header from the previous GET operation on the resource.

Following is a sample body, along with URL and Request Headers to be used, to create a Validated By relationship, to a QM artifact – Test case.

Action: PUT
Content-Type: application/rdf+xml
If-Match: Etag value obtained from GET on the resource

<rdf:RDF xmlns:dcterms="" xmlns:rdf="" xmlns:rm_property=" 515ad1367be43903-M-000000a2/types/" xmlns:rm="" xmlns:acp="" xmlns:oslc="" xmlns:foaf="" xmlns:oslc_rm=""> <oslc_rm:Requirement rdf:about=" 515ad1367be43903-O-49-000000a2"> <oslc:instanceShape rdf:resource=" requirement/urn:rational::1-515ad1367be43903-M-000000a2"/> <rm_property:attrDef-12 rdf:datatype=""> Created using OSLC Creation Factory</rm_property:attrDef-12> <rm_property:attrDef-4 rdf:datatype=""> Administrator</rm_property:attrDef-4> <rm_property:attrDef-7 rdf:datatype=""> 2013-05-01</rm_property:attrDef-7> <dcterms:created rdf:datatype=""> 2013-05-01</dcterms:created> <acp:accessControl rdf:resource=""/> <rm_property:attrDef-5 rdf:datatype=""> 2013-05-01</rm_property:attrDef-5> <dcterms:contributor> <foaf:Person> <foaf:name>Administrator</foaf:name> </foaf:Person> </dcterms:contributor> <rm_property:attrDef-13 rdf:datatype=""> </rm_property:attrDef-13> <dcterms:title rdf:parseType="Literal"> 49: Created using OSLC Creation Factory</dcterms:title> <oslc:shortTitle rdf:parseType="Literal"> 49: Created using OSLC Creation Factory</oslc:shortTitle> <rm_property:attrDef-9 rdf:datatype=""> 49</rm_property:attrDef-9> <oslc:serviceProvider rdf:resource=" service/urn:rational::1-515ad1367be43903-M-000000a2"/> <rm_property:attrDef-8 rdf:datatype=""> 2013-05-01T06:10:24Z</rm_property:attrDef-8> <rm_property:attrDef-6 rdf:datatype=""> Administrator</rm_property:attrDef-6> <rm_property:attrDef-10 rdf:resource=" 000000a2/types/attrDef-10#1"/> <dcterms:description rdf:parseType="Literal"></dcterms:description> <dcterms:creator> <foaf:Person> <foaf:name>Administrator</foaf:name> </foaf:Person> </dcterms:creator> <dcterms:identifier rdf:datatype=""> 49</dcterms:identifier> <dcterms:modified rdf:datatype=""> 2013-05-01T06:10:24Z</dcterms:modified> <rm_property:attrDef-11 rdf:datatype=""> Just some text for Object Text</rm_property:attrDef-11> <oslc_rm:validatedBy rdf:resource=" _EUB0tIJpEeKjaIQNt_0suA/resources/ _Jjh4EIJsEeKjaIQNt_0suA"/> </oslc_rm:Requirement> </rdf:RDF>

Sample use case

Let us consider a scenario where you need to create a relationship between an artifact in your application and an artifact (Requirement or Requirement Collection) in DOORS. To keep this example simple, let us use Selection UI service provided at the root level of DOORS.

Here's a simple walk-through of steps you'd need to perform in your code:

  1. Access rootservices document
  2. Obtain oAuth details and authorize
  3. Obtain Service Provider Catalog URL from rootservices
  4. Access Service Provider Catalog to find Service Provider URL
  5. Acces Service Provider document and identify Selection URI
  6. Access Selection URI, which will provide user ability to select an artifact in Rational DOORS
  7. Upon selection, URL of the artifact is returned in response header named "Location".
  8. Perform a GET on the URL of selected artifact. Capture the Etag and body of response.
  9. Insert link to the artifact in your application into the body of response returned by GET. Use appropriate relationship type as defined by the resource shape of artifact.
  10. Perform a PUT with the modified body and If-Match header (specifying Etag)

Notes on oAuth

OAuth 1.0 typically involves 3 steps:

  1. Obtain a Request Token
  2. Authorize Request Token
  3. Exchange the Request Token for an Access Token

Before requesting a token, you should register your application as a Consumer in DOORS. You can do this from DOORS Database Properties -> Local Keys. Add an entry for your application and make note of the Consumer Key and Consumer Secret (these will be used while requesting for a token).

Rootservices document contains information about the URLs to be used for all the 3 steps mentioned above. Nodes jfs:oauthRequestTokenUrl, jfs:oauthUserAuthorizationUrl, jfs:oauthAccessTokenUrl respectively contain the URLs for each of the 3 steps.

Obtaining a Request Token:
Action: POST
URL: https://<dwaServer>:<dwaPort>/dwa/oauth-request-token
oauth_signature_method = "HMAC-SHA1"

Response to the above request will be of text/html Media Type, which will contain oauth_token and oauth_secret.

Authorizing the Request Token:
Login to DWA using the following URL, to authorize the oauth_token obtained in the previous step:

Obtaining Access Token:
Once the Request token is authorized, exchange it with access tokens using the URL for jfs:oauthAccessTokenUrl.
Action: GET
oauth_token = <request Token>
oauth_signature_method = "HMAC-SHA1"

Note, oauth_secret should always be URL encoded before creating a signature.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Access OSLC services from IBM Rational DOORS