OSLC DXL services for Rational DOORS

You can use OSLC DXL services to run IBM® Rational® DOORS® DXL scripts with the HTTP or HTTPS communications protocol.
Note: The example includes steps for installing a DXL file as a service by using the OSLC DXL Services utility. This utility is available in Rational DOORS version 9.6.1.3 and later. To install the DXL file without this utility, see the documentation for a previous release.

Rational uses technology that is based on Open Services for Lifecycle Collaboration (OSLC) to improve integration with Rational applications and other IBM and third-party tools. OSLC service discovery is extensible. Therefore, Rational and third-party developers can add services that are not currently available in the implemented standard or that are considered too specialized for inclusion in current or future versions.

The Rational DOORS implementation of the OSLC Requirements Management (RM) specification version 2 includes an API that you can use to run Rational DOORS DXL scripts with the HTTP or HTTPS protocol. This API adds extra value to integrations by enabling you to access and manipulate Rational DOORS data securely and safely. It is based on the concept of a DXL script library. Administrators can easily add, edit, and remove DXL scripts by using the OSLC DXL Services user interface.

These steps describe the process to use an OSLC DXL service:
  1. Look up the OSLC DXL script.
  2. Call 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 run.
  3. The script is run on an interoperation server.
  4. The results are posted.

The scripts are controlled and customized by the Rational DOORS administrator, who can decide which DXL scripts are available in 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, are not 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.

These steps are typical for the use of an OSLC DXL service:
  1. Create a DXL script.
  2. Install the DXL script as a service.
  3. Locate the service through service discovery.
  4. Call the service.
  5. Extract the return value from the response.

Example

  1. Create a DXL file that is 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"
    }
  2. Copy the helloWorld.inc file into the /addins/services directory. The default location of this directory is C:\Program Files\IBM\Rational\DOORS\9.version\lib\dxl\addins\services.
  3. Open the Rational DOORS client and log in as the administrator.
  4. To install the DXL, click to FILE > OSLC > DXL Services.
  5. In the OSLC DXL Services window, click Add.
  6. In the Add OSLC DXL Service window, enter these values:
    • Name: helloWorld
    • Description: Hello world in several languages
    • DXL: #include <addins/services/helloWorld.inc>
    • Function Name: getHelloString
    A service that is 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" 
    }
  7. Call the service. The URI is like this example: http://servername:portnumber/dwa/rm/dxl/helloWorld
  8. Set both the accept and content-type headers to this entry: application/rdf+xml
  9. 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>
  10. To pass arguments to the service, use the <doors:arguments> element. Type 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.
  11. 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 do any marshalling. Specify arguments as a single string. The DXL script parses and extracts values from the string before it converts them to the expected individual parameters.

Sample files are included in the Rational DOORS client installation. The sample file hierarchy.dxl shows how to use the OSLC DXL service to obtain information about module hierarchy.
Related concepts:
Back links and link discovery
Related reference:
Rational DOORS as an OSLC service consumer
Rational DOORS as an OSLC service provider
Links across OSLC domains
Additional OSLC integration services and requirements
Related information:
DXL Reference Manual
Using DXL (the Rational DOORS Extension Language)

Feedback