OSLC DXL Services

One of the primary strategies of the IBM Rational division is to continually improve upon the integration capabilities of Rational and non-Rational products.

Keystone to this strategy is Open Services for Lifecycle Collaboration (OSLC). 

However a common complaint heard from providers / consumers of OSLC functionality is that there can be certain business problems that cannot be addressed because they rely on data and/or functionality that are (a) not currently available in the implemented standard or (b) considered too specialized for inclusion in the standard and therefore not planned for future versions.

Yet all is not lost and as OSLC service discovery is extensible it is possible to add services to help close such gaps. 

An excellent example of this can be seen in the introduction of OSLC DXL Services to Rational DOORS.

What are OSLC DXL Services?

Put simply they are an extension to the Rational DOORS OSLC RM V2 interface which allows users to execute Rational DOORS DXL scripts safely and securely across HTTPS.

Yes you can run DXL scripts from DWA! Well not all DXL scripts you have of course and only those registered by Administrator as OSLC DXL service but still this gives your project new possibilities and powers.

What makes DXL Script a OSLC DXL Service?

If you looked at IBM OSLC DXL Service introduction you came across helloWorld.inc:

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

If you are familiar with DXL you can spot setDxlServiceResult PERM. That is exactly what will set value of hello as the result of the service.

Registering DXL Service

Currently DOORS Database Administrator has to add those services manually using DOORS Perms.

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

Quick PERM reference (as it's not yet documented in DOORS DXL Reference Manual)

void setDxlServiceResult(string s)
sets s as the result for DXL Service

string addOrUpdateOSLCDXLService(string n, desc, dxlcode, entryPoint) 
registers dxlcode as the service with name n and description desc. entryPoint specifies the function in dxlcode to be run as entry point of service.

To make life easier OSLC DXL Services management will be soon available in File menu in IBM DOORS client.

Call OSLC DXL Service

Once you have your service registered you can send GET and PUT requests.
Set both the accept and content-type headers to this entry: application/rdf+xml and submit:
 

• GET request for the DXL service description.
• PUT request with optional parameters to invoke the service.

helloWorld service registered above could be accessed with URI like https://servername:portnumber/dwa/rm/dxl/helloWorld

As you notice before helloWorld function takes one parameter which should be supplied. You can provide parameters for DXL Services with aid of request content:

<?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>French</doors:arguments>
  </doors:Arguments>
</rdf:RDF>

If you have more then one argument, separate those with comas ','. All arguments are passed to DXL service as strings. If you need to have other types use DXL conversions in your service.

The results

Once DXL Service will finish its operation DWA server will return response with a content in following form:

  dwaOauth.js

was used to GET only protected information from DWA. But calling OSLC DXL Services requires PUT request which should be added.

There's nothing easier:

exports.getDXLServiceResult = function(req, res, dxlService, lang, next, onError) {
    var oa = new OAuth(req.session.oa._requestUrl,
              req.session.oa._accessUrl,
              req.session.oa._consumerKey,
              req.session.oa._consumerSecret,
              req.session.oa._version,
              req.session.oa._authorize_callback,
              req.session.oa._signatureMethod);

        // Try to get protected data
        var post_body = '<?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/">'
        post_body += '<doors:Arguments><doors:arguments>' + lang +'</doors:arguments></doors:Arguments></rdf:RDF>';

        oa._headers['accept'] = "application/rdf+xml";

        var host = url.parse(location);
        console.log('requesting service ' +host.protocol+"://"+host.host+'/dwa/rm/dxl/'+dxlService + ' with param: '+lang);

        oa.put(host.protocol+"//"+host.host+'/dwa/rm/dxl/'+dxlService,
            req.session.oauth_access_token,
            req.session.oauth_access_token_secret,
            post_body, 
            'application/rdf+xml',
            function (error, data, response) {
                if (!error && next) {
                    next(req, res, data);
                }
                else if (onError) {
                    onError(error);
                }
            }
        );
}

And that's it!.