OSLC DXL services for Rational DOORS

The IBM® Rational® DOORS® implementation of the OSLC Requirements Management (RM) specification version 2 includes a service that enables you to execute Rational DOORS DXL scripts using HTTP protocol.

One of the primary strategies of the Rational division is to improve the integration of Rational and non-Rational tools. The technology for this strategy is based on Open Services for Lifecycle Collaboration (OSLC).

Because the OSLC service discovery is extensible, it is possible for Rational and third party developers to add services which are not currently available in the implemented standard or which are considered too specialized for inclusion in the standard, and therefore not planned for future versions of the standard. To support the ongoing commitment to extensibility, Rational DOORS introduces OSLC DXL Services to help bridge these gaps. The OSLC RM V2 interface exposes a service that enables users to execute Rational DOORS DXL scripts across HTTP. This service is based on the concept of a DXL script library:
  1. The user looks up the required OSLC DXL script.
  2. The user calls this script to package the required parameters in the OSLC call. If you submit a GET request for the DXL service URI, the response contains help information about the script, as supplied by the author. If you submit a PUT request with optional parameters for the DXL service URI, this invokes the service.
  3. The script is run on an Interop Server.
  4. The results are posted back.

The scripts that are made available are completely under the control and customization of the Rational DOORS administrator, who can decide which DXL scripts are exposed across the service interface. The administrator can lock out the ability to call certain functions that could be regarded as a potential security risk, such as "runDXL".

Note that certain DXL, such as user interface widgets, will never be supported.

Because service discovery is protected by OAuth, users of this functionality are also required to first authenticate using their user name and password.

The typical steps for using this feature are:
  1. Create a DXL script.
  2. Install this DXL script as a service.
  3. Locate this service via service discovery.
  4. Call the service.
  5. Extract the return value from the response.

Example

Create a DXL file called helloWorld.inc that contains the following code:

void getHelloString(string language)
{
	string hello = null

	if ("French" == language)
	{
		hello = "Bonjour le monde"
	} 
	else if ("Finnish" == language)
	{
		hello = "Hei maailma"
	} 
	else if ("Latin" == language)
	{
		hello = "Ave mundi"
	}
	else 
	{
		hello = "Hello world"
	}

	setDxlServiceResult hello
    
	print hello "\n"
}

Copy the helloWorld.inc file into the /addins/services directory. The default location of this directory is C:\Program Files (x86)\IBM\Rational\DOORS\9.5\lib\dxl\addins\services.

Launch a Rational DOORS client and log in as the Administrator.

To install the DXL, open a DXL window and type the following DXL code. This creates a service called helloWorld.

OSLCDXLService os = null
string err = null

string dxlCode = "#include <addins/services/helloWorld.inc>\n"  
err = addOrUpdateOSLCDXLService("helloWorld", "Hello world in several languages", dxlCode, "getHelloString")  
if (!null err) 
{ 
	print err 
}  
else  
{ 
	print "Installed Service\n" 
}

Then, call the service. The URI is similar to the following example: http://servername:portnumber/dwa/rm/dxl/helloWorld

Set both the accept and content-type headers to the following entry: application/rdf+xml

The request content should be similar to the following code:

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:doors="http://jazz.net/doors/xmlns/prod/jazz/doors/2.0/">
  <doors:Arguments>
  <doors:arguments>English</doors:arguments>
  </doors:Arguments>
</rdf:RDF>

The most important fields are the doors:arguments fields. These contain all of the parameters necessary for the script to function. If any of these are missing or incorrectly ordered, then the call will fail.

The response content would be similar to the following code:

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:doors="http://jazz.net/doors/xmlns/prod/jazz/doors/2.0/">
  <doors:DxlServiceResult rdf:about="http://my-desktop:8080/dwa/rm/dxl/helloWorld>
  <doors:result>Hello world</doors:result>
  </doors:DxlServiceResult>
</rdf:RDF>

No marshalling is performed by the service. Arguments are specified in a string format, from which the DXL script extracts values and then converts them into the expected individual parameters.


Feedback