Track projects in Rational Focal Point with the XPathValueFetcher business rule

Monitor progress through the Collaborative Lifecycle Management integration with Rational Team Concert and Rational Requirements Composer

The Collaborative Lifecycle Management (CLM) integration of IBM Rational Focal Point with Rational Team Concert and Rational Requirements Composer provides a comprehensive planning, execution, and project management capability for small to medium-sized software delivery organizations, particularly those that use agile development practices. You can use the XPathValueFetcher business rule in Rational Focal Point to fetch key values, such as status and progress, from the other Rational applications. You can configure the rule to run as a background batch process to periodically synchronize data from Rational Team Concert and Rational Requirement Composer.

Manjunatha S. Nadigar (manjunatha.nadigar@in.ibm.com), Integration Lead, IBM

Author1 photoManjunatha Nadigar works on the Rational Focal Point development team. He has been with IBM Rational software for five years.



11 September 2012

Also available in Chinese

Link management in Rational Focal Point

IBM® Rational® Focal Point™ integration with the Rational solution for collaborative lifecycle management (CLM) applications is based on Linked Data technology. In other words, the links created between Rational Focal Point and CLM applications, such as Rational® Requirements Composer and Rational Team Concert™, are a key part of this integration. The diagram in Figure 1 shows various Focal Point and CLM application resources and their relationships, using links. Notice that the links are many-to-many relationships.

What you need to know

Following this article requires knowledge of REST architecture, XML, and XPath.

Figure 1. Resources and relationships
Relationships of Focal Point and CLM resources

Rational Focal Point integration with CLM applications gives you following capabilities:

  • Create single a CLM resource, such as a work item or a requirement artifact, from a Business Need in Focal Point
  • Create a collection of CLM resources, such as work items or requirement artifacts, from the Focal Point UI, and process them in bulk
  • Link existing CLM resources to Business Need from the Focal Point UI.
  • Preview linked CLM resources from the Focal Point UI
  • Fetch key data from linked from a CLM resource to Focal Point for project monitoring by stakeholders, using the XPathValueFetcher business rule

Configure the XPathValueFetcher business rule

A key benefit of Rational Focal Point is that you can use it as a governance dashboard. Product managers, business stakeholders, and executives can use CLM applications such as Rational Team Concert and Rational Requirements Composer to track and communicate the progress and status of their initiatives during project execution or elaboration.

You can also use an XPathValueFetcher business rule to filter Focal Point elements, based on CLM data pulled into Focal Point. For example, you can list all of the business rules for which a corresponding Requirement Status is approved in Rational Requirements Composer.

Focal Point uses the IntegrationLinkAttribute for linking more than one link to CLM resources. By using these links, the XPathValueFetcher rule can fetch information from a CLM application into a Focal Point attribute for both text and numeric values, such as Status and Progress data linked to a work item in Rational Team Concert.

Prerequisite for executing the XPathValueFetcher business rule

How much can you save?

Want a rough estimate of the ROI your organization may achieve by using IBM Rational Focal Point?

Register for the Rational Portfolio Management ROI calculator!

The XPathValueFetcher business rule runs in the background. It needs user authentication entered to make requests to a CLM server without user intervention.

Rational Jazz™ technology provides a way to assign a functional user-to-consumer key to make a background request without user intervention from Focal Point.

Figure 2. Create a consumer key and attaching a function user to a consumer key
Authenticating JAZZ user to run in background

Larger view of Figure 2.

Figure 3. Add a CLM consumer key as a Friend for XPathValueFetcher authentication
Registering consumer key in Focal Point

Larger view of Figure 3.


Follow the XPathValueFetcher business rule format

=XPathValueFetcher('Integration link attribute',"URL parameters","XPath expression","Label","true")

1. Enter the name of the Integration Link attribute

Focal Point allows you to store links to specific project areas in CLM applications by using the Integration Link attribute. You can create or link to CLM resources in configured project areas by using this attribute.

As the first parameter for the XPathValueFetcher business rule, enter the name of the Integration Link attribute used to link to the CLM application, for example; work items (see Figure 4).

2. Configure the URL parameters

URL parameters are used to query the required resources and attributes from the CLM server. The URL parameters in Rational Team Concert and Rational Requirements Composer are configured differently:

  • When querying the resources in Rational Team Concert, the XPathValueFetcher business rule uses the OSLC REST service to get an XML representation of the work item.
  • For querying the resources in Rational Requirements Composer, the rule uses the Rational Requirements Composer Reportable REST API to get an XML representation of the requirement.

Configure the URL parameter for a Rational Team Concert work item

Rational Team Concert provides the oslc_cm.properites parameter on the HTTP GET request to get a restricted number of resoruce properties from a work item URL. If this parameter is ommitted from the request, all resource propreties are provided in an XML response.

Figure 4. An Integration Link attribute linked to a work item and rich hover display of the work item
rich hover view of an Rational Team Concert work item

Larger view of Figure 04.

Display the link to the Rational Team Concert work item, as shown in Figure 4, and copy the link to Rational Team Concert work item from the IntegrationLinkAttribute to make a GET HTTP request by using any REST client. Figure 5 shows the Mozila Firefox REST client being used for a GET request to a work item URL.

Figure 5. An HTTP GET request for a Rational Team Concert work item URL, using the Firefox RESTClient add-on
Sample Rational Team Concert work item XML

Larger view of Figure 5.

Constructing a URL parameter to fetch State and Progress information of a Rational Team Concert work item

Both State and Progresstracking are reference resources in XML, and Rational Team Concert provides an option to fetch them as inline resources. For example:

rtc_cm:progressTracking{*}, rtc_cm:state{*}
?oslc_cm.properties=rtc_cm%3Astate%7B*%7D,rtc_cm%3AprogressTracking%7B*%7D

Note:
oslc_cm.properties goes as part of a request URL. This requires parameters to be encoded. For example:

{*} is encoded as %7B*%7D, and rtc_cm:state is encoded as rtc_cm%3Astate.

This is an example of a URL to a Rational Team Concert work item (this URL will be used in constructing the XPath Expression in Step 3):

https://ibm-mnadigar-w5:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/13?oslc_cm.properties=rtc_cm%3Astate%7B*%7D,rtc_cm%3AprogressTracking%7B*%7D

Configure the URL parameter for Rational Requirements Composer

The XPathValueFetcher business rule uses the Rational Requirements Composer Reportable REST API for fetching data from Rational Requirements Composer. In Focal Point, Rational Requirements Composer Requirement links are stored as OSLC resource URLs and these URLs are automatically converted to a Reportable REST URL in XPathValueFetcher business rule before making a GET request.

This is a sample Rational Requirements Composer requirement URL format stored in Focal Point:
https://fpdev.integration:9443/rm/resources/__JnJ8rYzEeGXfpEm4RWRkQ

The equivalent Rational Requirements Composer Reportable REST API URL format:
https://fpdev.integration:9443/rm/publish/resources?resourceURI=__JnJ8rYzEeGXfpEm4RWRkQ&fields=/ds:dataSource/ds:artifact/

For Rational Requirements Composer, the URL parameter will be:
/ds:dataSource/ds:artifact/

You can input any valid XPath expression. For example:
=XPathValueFetcher('Requirements', "/ds:dataSource/ds:artifact""/ds:dataSource/ds:artifact/rrm:collaboration/rrm:attributes/attribute:objectType/attribute:customAttribute[@attribute:name='Status']/@attribute:literalName","Status","update_interval=1h")

This is an example of a Rational Requirements Composer Reportable REST requirement URL (this URL will be used in constructing the XPath expression in the next step):

https://fpdev.integration:9443/rm/publish/resources?resourceURI__JnJ8rYzEeGXfpEm4RWRkQ&fields=/ds:dataSource/ds:artifact/

Figure 6. An HTTP GET request on Rational Requirements Composer requirement Reportable REST URL
Sample Rational Requirements Composer Requirement XML

Larger view of Figure 6.

3. Construct the XPath expression

After you have constructed the URL parameter, use the sample URL constructed in the URL parameters step to make the HTTP GET request.

  • Use the REST client with headers used in the URL parameters Step 2 to get XML representation of the work item or requirement as a response.
  • Use this XML to construct the XPath expression to the required attribute in the XML to be retrieved in Focal Point.
  • Use the freely avaialbe XPath editor to construct the expression.

These are examples of XPath expressions used for Rational Requirements Composer and Rational Team Concert:

Examples of Rational Requirements Composer XPath expressions:

  • /ds:dataSource/ds:artifact/rrm:title
  • /ds:dataSource/ds:artifact/ds:collaboration/ds:attributes/attribute:objectType/attribute:customAttribute[@attribute:name='Status']/@attribute:literalName/child::text()
  • /ds:dataSource/ds:artifact/ds:collaboration/ds:attributes/attribute:objectType/attribute:customAttribute[@attribute:name='Difficulty']/@attribute:literalName

Examples of Rational Team Concert XPath expressions:

  • //rtc_cm:state/dc:title[text()]
  • //oslc_cm:priority[enumeration()]
  • //oslc_pl:workCompleted[text()]
  • //oslc_pl:effortRemaining[text()]

Examples of XpathValueFetcher business rules to fetch Status, Difficulty, and Stability from a Rational Requirements Composer requirement:

  • =XPathValueFetcher('Detailed Requirements', "/ds:dataSource/ds:artifact"
  • "/ds:dataSource/ds:artifact/rrm:collaboration/rrm:attributes/attribute:objectType/attribute:customAttribute[@attribute:name='Status']/@attribute:literalName
  • /ds:dataSource/ds:artifact/rrm:collaboration/rrm:attributes/attribute:objectType/attribute:customAttribute[@attribute:name='Difficulty']/@attribute:literalName
  • /ds:dataSource/ds:artifact/rrm:collaboration/rrm:attributes/attribute:objectType/attribute:customAttribute[@attribute:name='Stability']/@attribute:literalName"
  • "Status, Difficulty, Stability"
  • "update_interval=1h")
Figure 7. Sample XPath editor view of construction of an XPath expression to Rational Requirements Composer requirement title
Sample XPath editing

Larger view of Figure 7.

4. Add labels

A label is some meaningful information shown for each value (XPath dxpression) fetched from a CLM application. For example:
=XPathValueFetcher('work items',"/?oslc_cm.properties=rtc_cm%3Astate%7B*%7D","//rtc_cm:state/dc:title[text()]","work item State", true, "run_at=1")

Figure 8. Figure 8. Configuring Label in XPathValueFetcher business rule
Shows use of custom code labels

5. Specify the last runtime stamp

Rational Focal Point allows the XPathValueFetcher business rule to be scheduled to run as a background job for regular intervals, such as updater_interval=xxxh|m|s or run_at=xxx. With this parameter, you can show in the UI the last time that this business rule ran (see Figure 9 for an example):
=XPathValueFetcher('Work Items',"/?oslc_cm.properties=rtc_cm%3Astate%7B*%7D","//rtc_cm:state/dc:title[text()]","Work Item State", true, "update_interval=1h ")

Figure 9. Figure 9. Work Item Details show the last runtime stamp of the rule
Last run: (date and time)

6. Configure the rule to run as background job

Focal Point allows the XPathValueFetcher business rule to be configured to run as a background job. You can specify how frequently it should be run. Two examples follow.

update_interval=xxx h|m|s

With this parameter, you can specify the interval between the two runs. For the update_interval=1h expression, the time interval between the execution of two business rules is set to one hour. You can use this parameter for all of the business rules.

run_at

With this parameter, you can determine a specific time to update the business rule. You cannot use both update_interval= and run_at= at the same time. For the expression run_at=8,7,3, the business rule runs once a week at 8:00 AM, and it will start running in three days. The numbers in the parameter represent:

  • start_at
  • days_between_runs
  • days_before_first_run

You can customize this parameter according to your need. For example, you can use run_at=8 to run the business rule daily at 8:00 AM or run_at=8,7 to run it once a week at 8:00 AM. You can use this parameter for all of the business rules:
=XPathValueFetcher('Work Items', "/?oslc_cm.properties=rtc_cm%3Astate%7B*%7D","//rtc_cm:state/dc:title[text()]","Work Item State", true, "update_interval=1h")

7. Manually trigger the XPathValueFetcher business rule run

The OSLC view command to synchronize data with the Jazz™ Team Server can be configured to trigger the XPathValueFetcher business rule from the Rational Focal Point User interface. This view command execution applies to all elements and attributes in that view with the XPathValueFetcher business rule.

Configuring the Synchronize OSLC view command involves the following steps:

  1. Select the Focal Point view where you want the view commands to be shown (Approved Projects in the example in Figure 10).
  2. For Linked elements, select Business Needs.
  3. Select IntegrationLinkAttribute configured to links to Rational Team Concert and Rational Requirement Composer.
  4. For the command option, select Synchronize data with Jazz Team Server.
Figure 10. Configuring the OSLC view command to synchronize data with the Jazz Team Server
Configure > OSLC view command screen

Larger view of Figure 10.

You can execute the configured OSLC view command from the Focal Point view, as shown in Figure 11.

Figure 11. Executing the OSLC view command to synchronize data with the Jazz Team Server
Manually triggering the business rule

Larger view of Figure 11.

Resources

Learn

Get products and technologies

  • Download a free trial version of Rational software.
  • Evaluate other IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=832280
ArticleTitle=Track projects in Rational Focal Point with the XPathValueFetcher business rule
publish-date=09112012