This article discusses a method to access OSLC Requirements Management V2 Services provided by the Rational DOORS Web service from ATEasy.
There are several source code highlights within this document and the complete ATEasy project is attached at the end of the article. The code examples discussed are located within the example program (see link below), in the "Accessing Rational DOORS" ATEasy Task.
The provided examples also explain how to consume RESTful web services and using OAuth protocol to login to Twitter (see also: Wikipedia, RESTtful web services, IETF, The OAuth 1.0 Protocol). | |
The Root services document
The root services document contains information about your organization's specific DOORS instance. ATEasy uses the information contained within this document to negotiate authentication to access the protected requirements as well as primary service catalog which all sub-catalogs and services are contained within.
The first Test in the ATEasy example, "Access RTN DOORS from Sample File", reads through a root services document that has been saved locally as an XML file. Because this root services document is not located on a web server, no special authentication is required to access and read it. We use a System.Xml.XmlReader to parse through the document.
xmlReader = XmlReader.Create("public_rootservices_copy.xml", settings, context)
Once the file is open, the example parses it node to node from beginning to end using a while loop. This example looks specifically with a node named oslc:ServiceProviderCatalog.
while (xmlReader.Read())
select (xmlReader.Name)
case "oslc:ServiceProviderCatalog"
if xmlReader.HasAttributes
sCatalogLocation=xmlReader.GetAttribute(iAttributes)
endif
endselect
endwhile
This test proves the ability to parse through a root services document and is built upon in subsequent tests.
ServiceProviderCatalog and ServiceProvider
In the previous section, we searched a root services document for a node named olsc:ServiceProviderCatalog. This node is the entry point for discovering services within the DOORS webservice. The olsc:ServiceProviderCatalog node in the root services document has an attribute which specifies the URL to the primary service provider catalog. This primary service provider catalog and all other catalogs contains a listing of Service Providers and/or child Service Provider Catalogs.
See also: IBM, Access OSLC services from IBM Rational DOORS
OAuth Credentials and Tokens
To access any services beyond the root services document, transaction requests must be authenticated with OAuth, an open authorization protocol (see also: IETF, The OAuth 1.0 Protocol). In addition to the location of the primary service provider catalog, the root services document contains information required for access with OAuth.
In the second Test of the example, Access RTN DOORS from RootService w/ OAuth, we retrieve the OAuth URLs from the root services document, provide our credentials and retrieve an access identifier. This exercise requires a functional DOORS Web service which has been configured for web / automated access. Your DOORS administrator will need to provide you with a consumer key and consumer secret. The second Test has a header section which the end user must fill with their own implementation-specific information:
!============================================================================
!This data is generic, configure the server and port before running this demo
sDwaServer="doors9501.com"
lPort=8443
sConsumerKey=""
sConsumerSecret=""
sRootservices="http://"+sDwaServer+":"+Str(lPort)+"/dwa/public/rootservices"
!============================================================================
- sDwaServer is the URL of your DOORS web service
- lPort is the port of the DOORS web service
- sConsumerKey is provided by your DOORS administrator
- sConsumerSecret is provided by your DOORS administrator
- sRootservices is the address of the root services document. I assumed Rational DOORS Web Access version 1.4.0.2 or later.
With the correct information, the Test will retrieve the jfs:oauthRequestTokenUrl, jfs:oauthUserAuthorizationUrl, jfs:oauthAccessTokenUrl and use these URLs along with the user-provided information to load a log-in screen (via a pop-up Internet browser). After the user has put is his or her DOORS credentials, the Internet browser will respond with an identifier: a six digit query string value. This identifier is the access token required for access to documents beyond the root services document.
Depending on your organization's needs, the log-in process described can be optimized. For instance, instead of an external browser an ATEasy form can launch the log-in screen and automatically record and store the identifier.
An example: Crawling through your Database
All access attempts beyond the root services document must make use of the OAuth access token (identifier). The final Test in the example demonstrates an algorithm for crawling through the DOORS web service. The purpose of the crawler is to record the URL of all service provider catalogs and service providers within the database.
ATEasy keeps track of a list of to-be-searched URLs and already-searched URLS. Each URL in the to-be-searched list is accessed and parsed for service provider catalogs and service providers. The URLs of these provider entities are added to the to-be-searched list as long as they do not already exist in either of the lists. As URLs are searched, they are moved to the already-searched list.
Initially, the root services documents is the only URL in the to-be-searched list.
When the Test completes, the user can examine the already-searched list to see all of the service provider catalogs and service provider URLs. While this Test is not particularly functional in itself, it demonstrates how a user may programmatically search for and locate a specific requirement with no previous knowledge of the database architecture.
ATEasy Example Code