OSLC DXL services for Rational DOORS

In IBM® Rational® DOORS®, the implementation of version 2 of the OSLC Requirements Management (RM) specification includes a service that you can use to run Rational DOORS DXL scripts by using HTTP protocol.

Rational uses technology based on Open Services for Lifecycle Collaboration (OSLC) to provide integration with Rational and non-Rational tools. Rational DOORS supplements the standard OSLC capabilities with an OSLC DXL service that you can use to run Rational DOORS DXL scripts across HTTP. The service is based on the concept of a DXL script library. The process to use the service is as follows:

The user looks up the required OSLC DXL script.
The user calls the 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, the service is invoked.
The script is run on an interoperation server.
The results are posted.

The scripts that are controlled and customized by the Rational DOORS administrator, who can decide which DXL scripts are exposed across the service interface. The administrator can lock the ability to call certain functions that might be regarded as a potential security risk, such as "runDXL".

Certain DXL, such as user interface widgets, will never be supported.

Because service discovery is protected by OAuth, if you use the OSLC DXL service, you must authenticate by typing your user name and password.

The typical steps for using the OSLC DXL service are as follows:

Create a DXL script.
Install the DXL script as a service.
Locate the service through service discovery.
Call the service.
Extract the return value from the response.

Example

Create a DXL file named helloWorld.inc that contains this 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.version\lib\dxl\addins\services.
Open a Rational DOORS client and log in as the administrator.

To install the DXL, open a DXL window and type the following DXL code. A service named helloWorld is created.

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" 
}

Call the service. The URI is like this example: http://servername:portnumber/dwa/rm/dxl/helloWorld
Set both the accept and content-type headers to this entry: application/rdf+xml

Make sure that the request content is like this 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>

To pass arguments to the service, use the <doors:arguments> element. Enter a string in the element text that represents the required arguments. The DXL service transforms that string into the arguments that are required by the services DXL function. The earlier example shows a single parameter, English, that is passed to the getHelloString function. If a DXL function expects two parameters, the request looks like this example:
```
<doors:Arguments>
<doors:arguments>English,French</doors:arguments>
</doors:Arguments>
```
The receiving DXL service splits the comma-separated list into the separate English and French strings.
If you have arguments that are not of the string type, you must convert them into the appropriate type by using DXL. For example, if an argument is an integer, you can use the intOf operation to convert the string that was extracted from the comma-separated list into an int type value. Then, you can pass the value into the method.
The response content is like this 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>
```

The service does not perform any marshalling. Arguments are specified in a string format, from which the DXL script extracts values and then converts them into the expected individual parameters.