Use the Rational Focal Point REST client to create and synchronize resources from external applications

IBM Rational Focal Point helps product and portfolio management team to capture ideas and user requirements from customers, analysts, market research, and internal stakeholders, and prioritize the ones that provide the most value to the business. These are sorted into business needs that are prioritized on according to factors such as cost and revenue, resource availability, alignment of strategic goals and objectives, and business risks. They can then be handled in other applications, such as IBM Rational Team Concert and Rational Requirements Composer, by using the included REST API client that is included in Version 6.5.2 and later. In this detailed tutorial, Manjunatha Nadigar explains how to seamlessly integrate Rational Focal Point with external applications.

Introduction

IBM® Rational® Focal Point™ helps product and portfolio management teams capture ideas and requirements from customers, analysts, market research, and internal stakeholders, and then prioritize the ones that provide the most value to the business. Version 6.5.2 includes a REST client that enables online data collection from disparate external data sources. This is configured and automated without the need for customized code. Ideas, user requirements, and criteria that are required for prioritization decisions can originate from disparate data sources. Ideas and requirements captured in Rational Focal Point are prioritized and pushed to other applications as high-level plan items or requirements for implementation or elaboration. During this process, key data from the external REST applications, such as status and progress information, is synchronized in Rational Focal Point for monitoring by stakeholders.

In a typical product lifecycle, the product manager captures high-level stakeholder requests in Rational Focal Point as business needs. These business needs are prioritized according to business factors such as cost and revenue, resource availability, alignment of strategic goals and objectives, and business risks. They are then ready to be handled in other applications, such as IBM® Rational Team Concert™ and Rational® Requirements Composer.

Rational Focal Point Version 6.5.2 can be integrated with any external application to create new resources by using the POST command from the prioritized business needs. You can track the progress of the business need in the other application from within Focal Point by using the SYNCHRONIZE command to get the key data from the external application.

The Focal Point REST client is an administration user interface where you can configure REST GET, POST, PUT, and DELETE commands to any external REST application. You then run these commands from the Focal Point user interface. Figure 1 illustrates the actions.

Figure 1. Rational Focal Point REST client overview
Focal Point REST client diagram

The following sections explain how to use REST APIs to integrate Rational Focal Point with an external application.


Create resources in any REST-based application

In the Focal Point REST client, you can use a POST command to create resources in REST-based applications. Configuring integration with Focal Point by using the client involves the following steps:

  1. Add an external application to be integrated with Focal Point as a Friend.
  2. Configure the POST command to create new resources in REST-based application from Focal Point Element.
  3. Use the configured POST command to create new resources in the REST-based application from a Focal Point element.

Add an external application to Focal Point as a Friend

To integrate an external application with Focal Point, add it as a Friend. Click General > Application > Friend, and specify the details. Basic and OAuth-based authentication is supported.

Figure 2. Configuring an external application as a Friend in Focal Point
Adding an external application as a Friend in Focal Point

Configure the POST command to create new resources

You can create resources in an external application by using Focal Point elements. The POST commands are configured on View in Focal Point and any user who has access to View can execute those commands. These are the steps to configure the POST command to fetch external resources:

  1. Configure the REST application request URL
  2. Configure the REST Client Template XML
  3. Configuring the root XPath to the REST application
  4. Configure attribute mapping between Focal Point and the REST application
  5. Configuring the REST client POST response
  6. Complete the Configuration Section
  7. Request parameter mapping
  8. Request header mapping

Note:
These tasks require knowledge of REST architecture, XML, and XPath.

Configure the REST application request URL

  1. From the REST application, identify the REST API that can be used to create resources. For example, you can use the Rational Team Concert Creation Factories URL to create work items in Rational Team Concert.
  2. Choose a unique attribute in Focal Point to use with the POST command to hold the URL or any attribute from newly a created resource in the external application. If the chosen unique attribute has a value, the element is ignored in a POST operation.
Figure 3. Setting the REST client view command name and the Request method, and selecting the Friend and REST application request URL
REST client command configuration view

Configure the REST client template XML template

To create any resource in the REST API, an XML representation of the resource is required as input. Depending on the REST design, XML input for the POST operation of the REST API can be constructed by issuing a GET request on a sample resource URL. If the POST XML data is not the same as the GET XML data, the sample XML can be constructed according to the REST API document.

Case 1. POST XML is the same as GET XML template

Enter the sample resource URL in the REST application URL to template XML field, and click Get Template XML. The XML resource representation of the resource is fetched and used as input to POST operation.

Figure 4. Configuring the REST client XML template by issuing a GET request on a sample REST resource
GET template XML code

Case 2. POST XML and GET XML are different

Enter the sample XML representation for the POST operation in the REST application template XML field.

Figure 5. Configuring REST client template XML by manual inputting POST XML
Manually composing a REST client template XML

Configuring root XPath to the REST application

The POST operation creates a new resource in the external application with attribute values copied from the mapped Focal Point element attributes to external application attributes.

After you configure the template XML for a POST operation, you can choose the root XPath to the REST application artifact. The root XPath is the XPath to the XML element that holds all of the attributes of a resource.

For the Rational Requirements Composer sample XML file shown in Figure 6, this is the root XPath:
/rdf:RDF/rdf:Description

Figure 6. Sample GET XML from a Rational Team Concert work item
Rational Team Concert work item and choosing root XPath

Configure attribute mapping between Focal Point and the REST application

To map a Focal Point attribute to a REST application attribute, select the Focal Point attribute in the left and the XPath expression to REST application attribute in the right. Figure 7 shows one method of choosing an XPath expression, based on the value shown on selecting the XPath expression.

Figure 7. Focal Point attribute mapped to REST application attributes
Mapping an attribute between Focal Point and REST application

Configuring the REST client POST response configuration

You can configure the POST response handling, such as updating the newly created resource URL to a Focal Point attribute or updating the Focal Point attributes with REST POST XML response.

Depending on the REST API design, some applications write the response details in the header or serialize the XML representation in the response body. The REST client has options for handling the response header and body.

Response XML attribute mapping

If the REST API design requires that a REST XML attribute be mapped to a Focal Point attribute, in the REST Application Template XML field, enter the template response XML and then choose the root XPath to the element with attributes.

Figure 8. REST Client Response XML Attribute Mapping
Mapping Focal Point attribute with REST Response XML

Response header attribute mapping

If the REST API design requires that a REST response header be mapped to a Focal Point attribute, the Location response header with the URL to newly created work item URL is mapped to the work item URL attribute in Focal Point (see Figure 9).

Figure 9. REST Client Response Header Attribute Mapping
Mapping Focal Point attribute with REST Response Header

Complete Configuration section entries

Configure the date format used by the REST application and the separator (such as a comma or semicolon) used for separating multiple values in REST XML.

Figure 10. Configuration section for the date format and the separator for multiple values
Configure the date format and the multiple value separator

Request parameter mapping

To pass a request parameter with the value populated dynamically, based on a Focal Point element attribute, configure the request parameter mapping. In the example shown in Figure 11, the value for the Stock request parameter is populated from the Stock Symbol attribute.

Figure 11. Request parameter mapping with a Focal Point attribute
Configure REST Request parameter with Focal Point attribute value

Request header mapping

To add arbitrary HTTP headers required by the REST application, configure the request header mapping. The headers are added as a part of the GET request.

Figure 12. Request header for a GET call to the Rational Team Concert REST API
Configure the REST request header

Use the configured POST command to create resources in a REST-based application from a Focal Point element

Open the view where the SYNCHRONIZE command is configured, select the command, and click the Go icon.

Figure 13. Executing configured POST command
Running a POST command from a Focal Point view

Synchronize key data from a REST application with Focal Point for monitoring

Ideas and requirements captured in Focal Point are prioritized and pushed to other applications as high-level plan items or requirements for implementation or elaboration. During the implementation of ideas and requirements in other applications, key data such as status and progress information are synced with Focal Point for monitoring by stakeholders.

Configuring a new integration with Focal Point using the REST client involves following steps, which the subsections that follow explain:

  1. Add an external application to Focal Point as a Friend
  2. Configure the SYNCHROINZE command to synchronize resources key data in REST application with Focal Point data
  3. Configure the REST client template XML configuration
  4. Configure attribute mapping between Focal Point and the REST application
  5. Complete Configuration section entries
  6. Configure request parameter mapping
  7. Configure request header mapping

Add an external application to Focal Point as a Friend

To integrate an external application with Focal Point, click General > Application > Friend and specify the details. Basic or OAuth-based authentication can be used with REST applications.

Figure 14. Configuring an external application as a Friend in Focal Point
Adding an external application as a Friend in Focal Point

Configure the SYNCHROINZE command to synchronize resource key data in the REST application with Focal Point data

Key data from a REST application can be synchronized with the data in Rational Focal Point. The GET commands are configured on Focal Point views, and a user who has access to these views can execute those commands by following these steps:

  1. Choose the Request Method to synchronize, and select the Friend server to synchronize.
  2. For the URL attribute to REST artifact, choose the attribute in Focal Point that holds the URL to REST artifact to synchronize.
Figure 15. Setting a REST client view command name and request method, and selecting a Friend and REST application request URL
REST Client Command Configuration fields

Configure the REST client template XML template

To map a Focal Point attribute to REST application attributes, enter the sample URL of the REST artifact to fetch the XML representation.

Figure 16. Configuring the REST client template XML by making a GET request on a sample REST resource
REST application template XML code

Configure attribute mapping between Focal Point and the REST application

To map a Focal Point attribute to a REST application attribute, select the Focal Point attribute in the left pane and the XPath expression to the REST application attribute in the right pane. One method to choose the XPath expression is based on the value shown on selecting the XPath expression. The selected XPath expression can be customized.

Figure 17. Mapping of Focal Point attributes to REST application attributes
Work Item state, Planned effort, actual effort

Complete Configuration section entries Configure the date format used by the REST application and the separator (such as comma or semicolon) used for separating multiple values in the REST XML file.

Figure 18. Configuring the date format and the separator for multiple values
Configure the date format and multiple value separator

Configure request parameter mapping

To pass a request parameter with value populated dynamically based on Focal Point Element attribute, map the request parameter to the Rational Focal Point attribute.

In the example shown in Figure 19, the value of the request parameter Stock is populated from the Focal Point attribute Stock Symbol.

Figure 19. Request parameter mapping with a Focal Point attribute
Configure the REST request parameter with a Focal Point attribute value

Configure request header mapping

To add arbitrary HTTP headers required by REST application, map the request header. The headers are added as a part of the GET request.

Figure 20. Request header for a PUT call to the Rational Team Concert REST API
Configure the REST request header

Use a configured SYNCHRONIZE command to update linked resources in a REST application from a Focal Point element

Open the view where the SYNCHRONIZE command is configured, select the command, and click the execute icon.

Figure 21. Executing a configured SYNCHRONIZE command
running POST command from Focal Point

Configure a REST client DELETE command

To delete a linked resource in an external application from the Focal Point user interface, select the attribute in Focal Point that holds the URL to the REST artifact to delete, and set the required request header.

Figure 22. Select the attribute with the link to an external application
configuring DELETE command

Fetch resources from any REST-based application by using the REST client GET command

The Focal Point REST client provides a way to fetch a collection of resources from an external application into Focal Point as new elements. The GET commands are configured in the Focal Point display. A user who has access to that display can execute GET commands.

Configure the GET command to fetch resources from REST-based application to Focal Point as a new element

Figure 23. Setting the REST client view command name and request method and selecting the Friend and REST application request URL
REST Client Command Configuration view

Configure the REST application request URL

From the REST application, identify the REST API that fetches the list of resources. For example, in the case of integrating with Rational Requirement Composer, provide the reportable REST API.

Table 1. Sample URL for querying a work item in Rational Team Concert
ParameterURL
Get all https://server:port/ccm/rpt/repository/workitem?fields=workitem/workItem/(*)
Query will return the ID and the summary fields of all work Item elements with IDs of either 1 or 2. https://server:port/ccm/rpt/repository/workitem?fields=workitem/workItem[id=1 or id=2]/(id|summary)
Query will return the ID, the summary, and the comments (creator name and comment contents) fields of all work Item elements owned by Manju in the Test project area. https://server:port/ccm/rpt/repository/workitem/?fields=workitem/workItem[projectArea/name='FP 6.5.2 (Change Management)'
and owner/name='manju']/(id|summary|comments/(creator/name|content))
Query will return the ID and the summary fields of all work Item elements that were modified since 2010-12-07T10:10:53.000 (TIME ZONE -5). https://server:port/ccm/rpt/repository/workitem/?fields=workitem/workItem[modified > 2010-12-07T10:10:53.000-0500]/(id|summary)

Configure root XPath to the REST application

You can map a Focal Point attribute to a REST application attribute. During a GET operation, mapped Focal Point attributes are updated with REST application attribute values.

After you enter the REST application request URL and click the Connect button, the next step is to choose the root XPath to the REST application artifact. This is the XPath-to-XML collection element that holds the list of artifacts. Figure 3 shows the sample XML for Rational Team Concert shown. The root XPath is: /workitem/workItem. This XPath will fetch the details of the entire work item.

Figure 24. Sample of the GET XML from Rational Team Concert
Rational Team Concert work item and choosing root XPath
Figure 25. Selecting root XPath to the REST application
Choosing Root XPath

Configure identification mapping between Focal Point and the REST application

During a GET operation to make sure that resources from external application are not duplicated in Focal Point, you need to do identification mapping. This mapping is done on a unique attribute in Focal Point and the REST application.

Figure 26. Identification mapping attribute between Focal Point and the REST application
Identification Mapping view

Configure attribute mapping between Focal Point and a REST application

You can map a Focal Point attribute to a REST application attribute by selecting the Focal Point attribute on left and XPath expression to REST application attribute on right. One way to choose the XPath Expression is based on the value shown on selecting the XPath expression. The mapped XPath Expression can be edited.

Figure 27. Focal Point attribute mapped to REST application attributes
drop-down menu to select attributes

Complete Configuration section entries

In the Configuration section, configure the date format used by the REST application and the separator, such as a comma or semicolon, that is used for separating multiple values in the REST XML.

Figure 28. Configure date format and separator for attribute with multiple values
Configuration view

Configure request header mapping

This allows you to add arbitrary HTTP headers required by the REST application. Headers are added as part of the GET request.

Figure 29. Request header for the GET call to Rational Requirements Composer, a REST application
Request Header Mapping view

Use the configured GET command in Focal Point to fetch resources from a REST-based application

Open the view where the GET command is configured, select the command, and click the execute button.

Figure 30. Executing a GET call to Rational Team Concert REST API
running GET command from Focal Point

How the GET command works

  • Makes HTTP GET call to a configured REST application request URL to fetch the resources in the external application
  • Applies the root XPath to the REST application artifact to get a list of artifacts from XML
  • For each artifact, checks whether a Focal Point element with a mapped unique attribute in identification mapping already exists with the mapped REST application unique attribute value
  • If a Focal Point element already exists with a REST artifact unique attribute value, it updates the Focal Point element's mapped attribute from the REST artifact attribute values
  • Otherwise, it creates new element in Focal Point with attribute values from the mapped REST application attribute

Prioritize business needs in Focal Point

Using the Focal Point REST client GET command, Plan items from Rational Team Concert are fetched as business needs in Focal Point. Then they are ready to be prioritized.

Rational Focal Point provides a simple, effective capability for evaluating projects against specified criteria. You can define the criteria. A few examples:

  • How well does the project contribute to a strategic objective.
  • Which project is the most innovative?
  • Which project contributes the most to cost reduction?
  • Which project is expected to deliver the most business value?
  • Which project is higher or lower risk?

After evaluating and prioritizing projects according to your defined criteria, you can visualize the results to consider trade-offs (see Figure 31), such as value vs. cost or value vs. cost vs. risk, or other multiple criteria, to see which project comes out on top when evaluated against all your strategic objectives. These prioritized rankings are updated to the attributes.

Figure 31. Visualization of prioritized business needs and exporting ranking information to an attribute
bar graphs

Update Focal Point prioritized information to a linked resource using PUT command

After you have prioritized business needs in Focal Point and decided which business need to work on, export the priority rank information from the Focal Point attribute to the REST application attribute by using the REST client PUT command.

Configure the PUT command to update the linked resource from a Focal Point element

Figure 32. Setting the REST client view command name and request method and selecting Friend and the URL attribute to the REST artifact
REST Client Command Configuration fields

Configure the REST client template XML configuration

To update a resource through the REST API, you need the XML representation of the resource as input. Depending on the REST design, the XML input for the PUT operation of the REST API can be constructed by a GET request on a sample resource URL. In some cases, the PUT XML might not be the same as the GET XML. In those scenarios, you can construct the sample XML based on the REST API document.

Case 1. The PUT XML is the same as the GET XML

Enter the sample resource URL in the REST application URL to the template XML, and click Get Template XML. This will fetch the XML resource representation of the resource. You can use that as input in the PUT operation.

Figure 33. Configuring REST client template XML by making a GET request on the sample REST resource
REST Client Template XML Configuration view

Case 2. The PUT XML and GET XML are different

Enter the sample XML representation for the PUT operation in the REST application template XML, and select Use Template XML for the REST Put Call option. This option uses the template XML, and only mapped attribute information will be updated to the REST application through the PUT command.

Figure 34. Configure the REST client template XML by manually entering the POST XML
Manually Composing REST Client Template XML

Configure attribute mapping between Focal Point and the REST application

You can map a Focal Point attribute to a REST application attribute by selecting the Focal Point attribute on the left and the XPath expression to the REST application attribute on the right. One way to choose the XPath expression is based on the value shown on selecting the XPath expression. The selected XPath expression can be customized.

Figure 35. Rational Focal Point attribute mapped to REST application attributes
Attribute mapping view

Complete Configuration section entries

In the Configuration section, configure the date format used by the REST application and that separator, such as a comma or semicolon that is used for separating multiple values in the REST XML.

Figure 36. Configure section for date format and separator for multiple values
Configuration view, two fields

Configure request parameter mapping

Request parameter mapping allows you to pass request parameter with values populated dynamically, based on a Focal Point element attribute. In the example in Figure 37, the Stock request parameter value will be populated from the Stock Symbol attribute in Focal Point.

Figure 37. Request parameter mapping with Focal Point attribute
Request parameter table with key and value columns

Configure request header mapping

This allows you to add the arbitrary HTTP headers required by the REST application. Headers are added as part of the GET request.

Figure 38. Request header for making a PUT call to the Rational Team Concert REST API
Heading Name, Header value columns

Use the configured PUT command to update linked resources in a REST application from a Focal Point element

Open the view where the PUT command is configured, select the command, and click the execute button.

Figure 39. Issuing the configured PUT command
running the PUT command from Focal Point

Resources

Learn

Get products and technologies

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=858909
ArticleTitle=Use the Rational Focal Point REST client to create and synchronize resources from external applications
publish-date=02262013