Jazz Library Developing an OSLC consumer to collaborate with the Requirements Management application
Author name

requirements-management-doors-next,rational-doors-next-generation,rational-requirements-composer

Fri, 03 Jan 2014
5 min read
0

Developing an OSLC consumer to collaborate with the Requirements Management application

Gabriel Ruelas, IBM
Last updated: November 06, 2013
Build basis: Rational Requirements Composer 4.0 and Rational Doors Next Generation 4.0.1

You can develop an Open Services for Lifecycle Collaboration (OSLC) consumer, by using Eclipse Lyo, to collaborate with the Requirements Management (RM) application.

Note: The capabilities that are provided by the RM application are licensed as IBM Rational DOORS Next Generation or IBM Rational Requirements Composer.

Development teams use OSLC to enhance the collaboration between different software products. For instance, IBM applications that run on the Jazz platform offer a high level of collaboration that is based on OSLC. That collaboration helps to provide a more complete solution to development lifecycle. Third-party programs can join in this collaboration by adopting OSLC, and thereby increase the impact of their role in the product development lifecycle.

You can use Eclipse Lyo to develop an OSLC consumer for IBM requirements management products, such as Rational DOORS Next Generation and IBM Rational DOORS. Eclipse Lyo is an software development kit (SDK) that the Eclipse community uses to adopt OSLC specifications and build OSLC-compliant tools. By using Eclipse Lyo, you can reduce the effort to develop an OSLC consumer or provider.

Eclipse Lyo 2.0 offers a couple of OSLC consumer samples that can collaborate with Rational DOORS Next generation ( RRCFormSample.java ) and Rational DOORS Web Access ( DoorsOauthSample.java ). For more information, see the samples.

The high-level process to develop an OSLC consumer by using Eclipse Lyo is as follows:

  1. Install Eclipse Lyo.
  2. Authenticate to the server of a requirements management product.
  3. Obtain OSLC capabilities from a project area.
  4. Create and modify requirements.
  5. Query for requirements.
  6. Manage requirement’s user attributes.

Installing Eclipse Lyo

You can install the plug-ins and code for Eclipse Lyo, or the plug-ins only. If you want to debug the Eclipse Lyo libraries, install both the plug-ins and the code.

To gain access to the Eclipse Lyo libraries, add the software that you downloaded to your Eclipse project.

Authenticating to the server of a requirements management product

  1. Create a JazzRootServicesHelper object. This class is used to retrieve attributes from the application rootservices document. The class requires these parameters:
    • First parameter: The base URL of the application server; for example: https://server:port/rm
    • Second parameter: The name space of the OSLC domain; for example, the OSLC domain for requirements management is http://open-services.net/ns/rm#

    Example: 
    	JazzRootServicesHelper helper = new JazzRootServicesHelper( "https://myserver.com:9443/rm" , OSLCConstants.OSLC_RM_V2 );
  2. Obtain a JazzFormAuthClient object that will be used to communicate with the server application. Use the initFormClient() method, which requires these parameters:
    • First parameter: User name
    • Second parameter: Password
    • Third parameter: Authentication URL; for example, https://server:port/jts

    Example:
    	JazzFormAuthClient client = helper.initFormClient("myUser", "myPassword", "https://myserver.com:9443/jts");
  3. Log in to the server by using the formLogin() client method. No parameters are required.

    Example: 
    	client.formLogin();
  4. Check the return code from the formLogin() method. If it is HttpStatus.SC_OK ( 200 ), your client object is ready to make OSLC requests.

Obtaining OSLC capabilities from a project area

Obtain the service provider URL of the project that you want to work with. With the service provider URL, you can get the information that you need to manage requirements in that project. For instance, you can get the creation factory so that you can create requirements, get the query capability so that you can request information about requirements, get requirements, or modify requirements.

Use the lookupServiceProviderUrl() method, which requires these parameters:

  • First parameter: URL of the server OSLC catalog. This URL can be provided by the helper object.
  • Second parameter: The project area name.

Example:

	String serviceProviderUrl = client.lookupServiceProviderUrl(helper.getCatalogUrl(),"myProjectArea");

To get the requirement creation factory, use the lookupCreationFactory() method, which requires these parameters:

  • First parameter: The service provider URL
  • Second parameter: The OSLC domain; for exmaple, http://open-services.net/ns/rm#
  • Third parameter: The OSLC resource type; for example, http://open-services.net/ns/rm#Requirement or http://open-services.net/ns/rm#RequirementCollection

Example:

	String requirementFactory = client.lookupCreationFactory(serviceProviderUrl, OSLCConstants.OSLC_RM_V2, OSLCConstants.RM_REQUIREMENT_TYPE);

To get the OSLC query capability, use the lookupQueryCapability method, which requires these parameters:

  • First parameter: The service provider URL
  • Second parameter: The OSLC domain; for example, http://open-services.net/ns/rm#
  • Third parameter: The OSLC resource type; for example, http://open-services.net/ns/rm#Requirement or http://open-services.net/ns/rm#RequirementCollection

Example:

	String queryCapability = client.lookupQueryCapability(serviceProviderUrl, OSLCConstants.OSLC_RM_V2, OSLCConstants.RM_REQUIREMENT_TYPE);

To get the instance shape of an specific requirement type, the RmUtil.lookupRequirementsInstanceShapes static method, which requires these parameters:

  • First parameter: The service provider URL
  • Second parameter: The OSLC domain; for example, http://open-services.net/ns/rm#
  • Third parameter: The OSLC resource type; for example, http://open-services.net/ns/rm#Requirement or http://open-services.net/ns/rm#RequirementCollection
  • Fourth parameter: The authenticated client
  • Fifth parameter: The requirement type name; for example, “Feature”

Example:

	ResourceShape featureInstanceShape = RmUtil.lookupRequirementsInstanceShapes( serviceProviderUrl, OSLCConstants.OSLC_RM_V2, OSLCConstants.RM_REQUIREMENT_TYPE, client, "Feature");

Creating and modifying requirements

After you obtain OSLC capabilities, you are ready to create and modify requirements.

To create a requirement, follow these steps:

  1. Create a requirement object; for example: 
    Requirement myRequirement = new Requirement();
  2. Add the requirement’s type, title, description and a implemented by link: 
      		myRequirement .setInstanceShape(featureInstanceShape.getAbout());   		myRequirement .setTitle("Requirement 01");   		myRequirement .setDescription("Created By EclipseLyo");   		myRequirement .addImplementedBy(new Link(new URI("https://myserver/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/62036"), "Link to RTC"));
  3. Add primary text. Primary text needs extra processing because it is exposed as an extended property, and Rational DOORS Next Generation requires that it be in XML format. 
      		String primaryText = "My Primary Text";   		org.w3c.dom.Element obj = RmUtil.convertStringToHTML(primaryText);   		// Add to the extended properties.   		myRequirement .getExtendedProperties().put(RmConstants.PROPERTY_PRIMARY_TEXT, obj);
  4. Send the requirement object to the server. Use the createResource() method, which requires these parameters:
    • First parameter: The requirement factory URL
    • Second parameter: The requirement object
    • Third parameter: The content type; for example, application/rdf+xml
    • Fourth parameter: The accept type; for example, application/rdf+xml 
    ClientResponse creationResponse = client.createResource( requirementFactory, myrequirement, OslcMediaType.APPLICATION_RDF_XML, OslcMediaType.APPLICATION_RDF_XML);


    If the requirement is created, the creationResponse.getStatusCode() is HttpStatus.SC_CREATED, and you can get the requirement URL from the HttpHeaders.LOCATION header. For example: 
    	String requirementURL : creationResponse.getHeaders().getFirst(HttpHeaders.LOCATION);

To get a requirement, modify it, and send it back to the server, you use the requirement URL. Follow these steps:

  1. Get the requirement by using the getResource() method, which requires these parameters:
    • First parameter: The requirement URL
    • Second parameter: The accept type; for example, application/rdf+xml

    Example: 
      		ClientResponse getResponse = client.getResource(requirementURL , OslcMediaType.APPLICATION_RDF_XML);   		Requirement otherRequirement = getResponse.getEntity(Requirement.class);   // Load response in a Requirement object   		String etag = getResponse.getHeaders().getFirst(OSLCConstants.ETAG); // ETAG is needed to update
  2. Modify the requirement: 
      		otherRequirement.setTitle("Requirement 01 ( Title Changed ) ");   		otherRequirement.setDescription("Created By EclipseLyo  ( Description Changed ) ");  		otherRequirement.addValidatedBy(new Link(new URI("https://myserver/qm/resource/itemName/com.ibm.team.workitem.TestCase/55555"), "Link to RQM"));
  3. Send the modified requirement back to the server by using the updateResource() method, which requires these parameters:
    • First parameter: The requirement URL
    • Second parameter: The requirement object
    • Third parameter: The content type; for example, application/rdf+xml
    • Fourth parameter: The accept type; for example, application/rdf+xml
    • Fifth parameter: The requirement’s etag, which is obtained from the getResource response

    Example: 
    ClientResponse updateResponse = client.updateResource(requirementURL, otherRequirement, OslcMediaType.APPLICATION_RDF_XML, OslcMediaType.APPLICATION_RDF_XML, etag);
  4. Check that the requirement is updated by verifying that the updateResponse.getStatusCode() is HttpStatus.SC_OK.

To delete a requirement, use the deleteResource() method, which requires the requirement URL:

ClientResponse deleteResponse = client.deleteResource(requirementURL);

When the requirement is deleted, the deleteResponse.getStatusCode() is HttpStatus.SC_OK.

Querying for requirements

Another powerful aspect of OSLC is the ability to query for specific resources based on specific properties. For example, you can query for requirements that link to specific work items or test cases, or you can query for requirements that are of a specific type.

To use this capability, you use the query capability URL, which is described in the “Obtaining OSLC capabilities from a project area” section. You also use 3 classes from Eclipse Lyo to create, submit, and process query results. The classes are as follows:

  • OslcQueryParameters: A container for OSLC query parameters that can be associated with an OslcQuery object.
  • OslcQuery: Represents an OSLC query (HTTP GET) request to make of a remote system.
  • OslcQueryResult: The results of an OSLC query. If the query was paged, subsequent pages can be retrieved by using the Iterator interface.

Example query

The following example shows how to create a query for all requirements that contains an implementedBy link to “https://myserver/qm/resource/itemName/com.ibm.team.workitem.TestCase/55555”.

  1. Create an OslcQueryParameters object: 
      		OslcQueryParameters queryParams = new OslcQueryParameters();
  2. Add the Prefix, Where, and Select clauses: 
      		queryParams.setPrefix("oslc_rm=<http://open-services.net/ns/rm#>");   		queryParams.setWhere("oslc_rm:implementedBy=<https://myserver/qm/resource/itemName/com.ibm.team.workitem.TestCase/55555>");   		queryParams.setSelect("*");
  3. Create an OSLC query object, which requires these parameters:
    • First parameter : Authenticated client
    • Second parameter : Query Capability URL
    • Third parameter : pageSize the number of results to include on each page
    • Fourth parameter : OslcQueryParameters object

    Example: 
      		OslcQuery query = new OslcQuery(client, queryCapability, 10, queryParams);
  4. Run the query and get number of results: 
      		OslcQueryResult result = query.submit();   		int resultsSize = result.getMembersUrls().length;

The OslcQueryResult class offers several interesting methods that you can use to process the results; for example:

  		boolean hasNext()                Whether there is another page of results after this   		OslcQueryResult next()        Next page of results   		String[] getMembersUrls()        Return the subject URLs of the query response

Managing requirement’s user attributes

User attributes are exposed as extended properties; therefore, you must manage them in a special way. For example, to get user-readable names, you must check the requirement’s instance shape to make the proper mapping.

The following code sample extracts the requirements’ extended attributes, looks for the user-readable name in the resource shape, and displays the name with its value.

  		Map<QName, Object> requestExtProperties = requirement.getExtendedProperties();   		for ( QName qname : requestExtProperties.keySet() ){   			Property attr = featureInstanceShape.getProperty(new URI (qname.getNamespaceURI() + qname.getLocalPart()));   			String name = null;   			if ( attr != null) {   				name = attr.getTitle();   				if ( name != null ) {   					System.out.println(name  + " = " + requirement.getExtendedProperties().get(qname));   				}   			}   		}

To change an attribute, replace the extended property and update the resource at the server. For example, this code changes the primary text:

  		requirement.getExtendedProperties().remove(RmConstants.PROPERTY_PRIMARY_TEXT);   		String changedPrimaryText = "My Primary Text";   		org.w3c.dom.Element obj = RmUtil.convertStringToHTML(changedPrimaryText);   		requirement.getExtendedProperties().put(RmConstants.PROPERTY_PRIMARY_TEXT, obj);   			....   		// update resource   			....

Related information

Copyright © 2013 IBM Corporation

Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more here.

Fri, 03 Jan 2014