This article describes the various techniques that you can use to create links and exchange data between artifacts in repositories for IBM® Rational® Focal Point™ and the Rational solution for Collaborative Lifecycle Management (CLM), including those for IBM Rational Team Concert™ and IBM® Rational® Requirements Composer applications that are integrated into CLM.
A section for each technique provides an overview of how that method is used and then gives generic instructions on how to set it up or configure it. In some cases, examples are from the Rational Governance of Application Development Outsourcing solution.
This article is based on the assumption that you have already done the base integration of setting up the servers as friends, specifying functional users, specifying the available project areas to use, and defining preview views for Focal Point modules that can link to CLM artifacts. Those topics are not addressed here.
If you are not already familiar with REST APIs and navigating resource representations in XML, it is highly recommended that you gain those skills. To use the data exchange capabilities, you will need to understand RESTful interfaces and how they work. An understanding of the specific CLM REST interfaces and structure is also very helpful. Look for resources on jazz.net, open-services.net, and even REST tutorials on the Internet. A few suggestions:
- Complete the Open Services for Lifecycle Collaboration Workshop. It goes a little deeper than you might need, but it's a good introduction (jazz.net).
- Check the RRC data sources page to see what's available and get more detail on Rational Requirements Composer resources (jazz.net).
- Read the article by Manjunatha Nadigar, Use the Rational Focal Point REST client to create and synchronize resources from external applications (IBM developerWorks®, February 2013).
Focal Point accesses Rational Requirements Composer resources by using the latter's reportable REST API but uses the Open Source Lifecycle Collaboration (OSLC) REST service to access Rational Team Concert resources, not that software's reportable REST API. There was no explicit integration between Focal Point and Rational Quality Manager when this article was published in April 2013.
Overview of the integration techniques
There are four main integration techniques:
- Simple artifact creation and linking by using the Integration Link attribute
- XPathValueFetcher business rule
- OSLC view commands.
- REST view commands.
Table 1 summarizes these four techniques, and the sections that follow provide more detail.
Table 1. Integration techniques
|Integration link||Create or delete links to CLM artifacts using "delegated UI." View data by using rich hover.||Simplest technique, foundation for other integration techniques.|
|XPathValueFetcher||Fetch text or integer values from attributes in the CLM artifact to update a single attribute in Focal Point. Data can be used with Focal Point filtering.||Operates as background batch process.|
|OSLC view command||Limited set of nonextensible capabilities that run against a Focal Point container element to create, remove, restore, and validate links for all contained elements.||Hard-coded in Focal Point, specific to Rational Requirements Composer and Rational Team Concert. Invoked from pull-down menu or icon.|
|REST view command||Execute REST commands against any tools that expose data through REST APIs. Exchange attribute values in either direction between Focal Point and CLM artifacts.||Very flexible, most complex to define. Invoked from pull-down menu.|
Integration Link attributes
The Integration Link attribute is required for the other types of integration techniques. It defines the allowed Rational Team Concert and Rational Requirements Composer project areas and back link types. When you edit the attribute value for an element, you can then either create an element or link to an existing element in the target CLM application, with the delegated UI provided by Rational Requirements Composer or Rational Team Concert.
When you create an artifact, you can populate the title and, optionally, the description from the Focal Point element. Rational Team Concert also provides drop-down menus for you to manually set other attribute values, such as Planned-for or Filed-against. This integration mechanism does not permit any further data exchange.
After you have associated the Focal Point element with a new or existing CLM artifact, the Integration Link attribute then holds the URL value for the CLM artifact. Hovering your mouse cursor over the link shows the "rich hover information window for the artifact. You can also delete the links from either side (Focal Point or CLM).
You can use the XPathValueFetcher business rule to extract a specific value from Rational Requirements Composer or Rational Team Concert to populate or update a Focal Point attribute value. Because rules run automatically, the Focal Point attribute is updated automatically without requiring any user action — assuming that you have defined a CLM functional user with the necessary authentication as part of the preliminary integration setup. You must have this functional user defined on the CLM side for the business rule to run. You can define the scheduled frequency to run the business rule. (You can also use an OSLC view command to force the XPathValueFetcher rules to run, but more on that in the next section.)
The Integration Link attribute provides the context of the particular artifact to access. The business rule specifies the attributes to retrieve for that artifact. You need to specify the XPath value to the attributes that you want to access in Rational Team Concert or Rational Requirements Composer. Typically, you retrieve only a single value with this business rule, because it is updating a single attribute value in Focal Point. But you could retrieve multiple values to populate a matrix or text field.
XPathValueFetcher uses the OSLC 1.0 syntax, not OSLC 2.0.
OSLC view commands
OSLC view commands are defined in the Focal Point code and are included. They work only with other tools that support the OSLC CM (change management) and RM (requirements management) specs. (OSLC support is an additional layer on top of supporting REST APIs.). They have a limited set of predefined capabilities, which you cannot extend. Because OSLC is all about linked data and a delegated UI to enable linking resources, these commands are primarily about managing links.
OSLC view commands extend the basic Integration Link support so you can run the operation on multiple elements at the same time, targeting container elements with links to the elements to be created or linked (for example, a Project that contains links to the Business Needs). Of course, those linked elements must have Integration Link attributes defined.
Because OSLC view commands are associated with a view, you must be in that view and in a tree presentation mode. The icon to run the command shows in the element's title bar, next to the drop-down menu for OSLC commands. The screen capture in Figure 1 shows the icon to create artifacts and associate links in an element's title bar.
Figure 1. OSLC command icons
If you hover your mouse cursor over the icon (as shown), text appears to tell you which command the icon will run. Click the icon to invoke the command.
These are the available OSLC view commands:
- Create artifacts and associate the links
- Creates CLM artifacts for each of the linked Focal Point elements and sets the Integration Link attribute values.
- Remove the associated links
- Removes links from both Focal Point and CLM artifacts.
- Restore the links that were last removed from the Jazz Server
- Resets previous links that were deleted from both the Focal Point and the CLM side.
- Validate the Integration links
- Checks for any broken or inconsistent links between Focal Point and CLM. From the list of results, you can also choose to restore or remove broken links.
- Create project to the Jazz Team Server
- Creates a new Rational Team Concert project area, release plan, and plan items with links from Focal Point project and business need elements. This is the original Focal Point-CLM integration implementation. It always creates a new Rational Team Concert project area, which is not consistent with some usage models, where projects for subsequent releases are created in the same project area.
After you have run this command to create the project in Rational Team Concert, the OSLC command icon for that project and its business needs will automatically change to the Synchronize Data icon. The data retrieved in this way includes Plan and Actual Start and End Dates, Planned Effort and Duration, Actual Duration, Actual Work, and Percent Complete.
- Synchronize data with the Jazz Team Server
- Runs all configured XPathValueFetcher business rules defined in the linked elements.
You cannot further extend or modify the OSLC view commands.
OSLC view commands must be run manually, so a user must click the icon to execute the command. It cannot be scheduled to run automatically.
REST view commands
The REST view command is the most flexible and the most complex of the integration techniques. Basically, anything that you can do with a REST command (get, put, synchronize, delete attributes and elements), you can do with a REST view command. You are making Focal Point a REST client to other tools that expose their data with REST interfaces (in this case, Rational Requirements Composer and Rational Team Concert, but you could also integrate with other REST providers).
Starting with a URL path to a resource or set of resources (typically the Integration Link value, but not always), you navigate the XML representation for that resource to determine the attributes and values to exchange, along with their representations. You provide an XML template for Focal Point to locate and recognize the information, and then specify what Focal Point attributes correspond with the attributes in the CLM.
You can use this technique to push attribute values from Focal Point to CLM artifacts, to retrieve values from CLM to update Focal Point attributes, or to synchronize values between artifacts in both tools. A REST view command is associated with a particular view (as the name suggests). Note that the attributes to be updated must be editable in that view to allow the command to complete updates. Attributes referenced by the view command must be visible when defining the command, and they should remain visible. (We were able to hide referenced attributes after defining commands; however, additional validation in future might require those attributes to remain visible.) To improve performance, you can define query parameters for the command to limit the amount of data included in the REST command.
Like OSLC view commands, REST view commands must be run manually, meaning that a user must select the command from the pull-down menu to execute it. Also, it cannot be scheduled to run automatically.
One caveat: Data representations might differ between tools. For example, Rational Team Concert stores time values in milliseconds but Focal Point does not. Rational Team Concert represents Priority values differently internally from what you see in the UI and differently from Focal Point. There is currently no mapping capability, so we used a number of hidden attributes to handle the data transformation. We will show you how we addressed these specific examples; you might find others that you need to handle.
Implementing the four alternative techniques
This section describes how to configure each of the integration techniques and provides examples. In all cases, we assume that the Focal Point and CLM servers have already been configured as friends, with a functional user defined.
Defining and using Integration Link attributes
As described previously, the Integration Link attribute supports creating an artifact in Rational Requirements Composer or Rational Team Concert and establishing bidirectional links or establishing those links with an existing artifact. Rational Requirements Composer artifacts include requirements and collections; Rational Team Concert artifacts include any type of work item defined in the project area process specification. You can also establish links to existing Rational Team Concert plans, but the behavior is different. The plan must already exist, and no back link is set from Rational Team Concert to Focal Point.
After creating the artifact link, you can use it later for the other integration techniques.
The workspace administrator configures the Integration Link attributes, but it is usually the end user who creates or links to artifacts in the CLM repository.
Define or configure an Integration Link
- Log into Focal Point with (workspace) administrator privileges.
- Select to Configure > Attributes, and select the module to which you will add the attribute.
- Click Add Attribute and select Integration link from the list of attribute types.
Figure 2. Attribute types
- Enter the usual information, including name, description, position.
- The Allowed Service Providers field shows the list of configured friends. Expand or select the servers where you want to create or link artifacts for this attribute.
Figure 3. Define allowed service providers
- A pop-up window prompts you to specify what service providers (or project areas) to use on this server and which member roles should be able to use it.
Figure 4. Service provider configuration
- Unless you are restricting use by role (which you will do to some extent with the view definition), select the Members folder and the appropriate project areas, and then click Apply and Close. Eventually, when editing the attribute to set the value, the user will be prompted to specify which service provider to use from what you configure here.
- Specify the type of back link to create on the artifact (the relationship from that artifact's perspective). The Rational Requirements Composer back link type is usually "Elaborates Main Requirement…" (the requirements elaborate the Focal Point business need), and the Rational Team Concert back links are usually "Implements associated requirement" or "Tracks associated requirement." You need to specify the back link types only for the type of artifact that you're creating (so if you're linking to Rational Team Concert, you don't need to specify the Rational Requirements Composer back link types).
Figure 5. Back link types
- Click OK to save the attribute.
Set the Integration Link from a view
To set the value of an Integration Link, for example, to create a link between a Focal Point element and an artifact in Rational Team Concert, open a view where that attribute can be edited.
- Edit the attribute value by double-clicking the empty field or clicking the Edit icon next to it.
- Select the desired project area from the pull-down menu (populated by the list of service providers that you configured).
Figure 6. Setting the Integration Link attribute value
- To link to an existing artifact, click Select. To create a new artifact and link to it, click Create New. In both cases, the dialog windows shown are from the service provider, either Rational Requirements Composer or Rational Team Concert. Details on completing the creation and selection steps for each provider are included below.
- After you create or select the artifact, its name shows in the still-open attribute field.
Figure 7. Result of setting link to Rational Requirements Composer artifact
- Click the Save icon (shown above in Figure 7) to save the value to the field.
Create a new artifact in Rational Requirements Composer
If you opt to create a new artifact in Rational Requirements Composer, you see the dialog window shown in Figure 8.
Figure 8. Create new artifact in Rational Requirements Composer
- Set the Back link field to the type of link that you want to create from the Rational Requirements Composer artifact back to Focal Point. If you defined only one back link type, it's preset. Otherwise, it will show you the top option from your list.
- Set the Type of artifact that you want to create: Requirement or Requirement Collection.
- The Name and Description fields are populated with the name and description of the Focal Point element. You can change the values here if you want.
- The Artifact Type is the list of available Requirement or Requirement Collection types defined in the Rational Requirements Composer project, depending on what you selected for Type. Specify what type of requirement or collection you want to create.
- Similarly, the Artifact Format options depend on the Type that you select. For requirements, you can choose from different formats defined by the Rational Requirements Composer project area. Usually, there is only one collection format (or very few).
- Optionally, use the buttons to specify the folder where you want to create the artifact (or accept the default), and assign any tags.
- If the Rational Requirements Composer project has defined templates for the artifact type and format, you have the option to select that from the Template pull-down menu.
- Click Finish to create the artifact and return to Focal Point to save the link.
Select an existing artifact in Rational Requirements Composer
If you are linking to an existing artifact, you see the dialog windows in Figure 9.
Figure 9. Link to existing Rational Requirements Composer artifact
- As in the creation steps, specify the type of back link to create from the Rational Requirements Composer artifact to Focal Point. If you configured only one type in the Integration Link attribute, it will already be set.
- Set the Type to Requirement or Requirement Collection.
- If you know the number or part of the name of the artifact, you can enter it in the Search field. Alternatively, you can browse artifacts on the right side, which shows the folder hierarchy by default. When you select a folder, the available artifacts display in the selection area on the left. You can also click Filter Display by Attribute or Filter Display by Tag to browse or navigate based on those values.
- When you find the correct artifact, select it, and click OK to return to Focal Point and save the link.
Create a new artifact in Rational Team Concert
If you opt to create a new artifact in Rational Team Concert, you see the dialog window shown in Figure 10.
Figure 10. Create new artifact in Rational Team Concert
- Like Rational Requirements Composer, the Back Link options are defined by what you configured in the Integration Link attribute. Here you can see that only one option was configured, and it is preset.
- The Type pull-down menu shows the work item types that are defined in the Rational Team Concert process specification. You can choose to create any of the defined work item types.
- The Summary and Description fields are populated based on the name and description of the Focal Point element. You can modify those fields if you want.
- The other fields shown (such as Owned By, Severity, and so forth) vary based on the work item type that you choose and the attributes that Rational Team Concert defines for that type. You can choose to give values for the fields shown or leave them as the default values, depending on the process to be followed in Rational Team Concert after creation. Alternatively, you can push values from Focal Point to Rational Team Concert artifacts using REST view commands, which you'll see later in this tutorial.
- Click OK to create the artifact and return to Focal Point to save the link.
Select an existing artifact in Rational Team Concert
If you choose to link to an existing artifact, you see the window in Figure 11.
Figure 11. Link to an existing Rational Team Concert artifact
- The back link type still shows whatever you configured.
- The type of artifact that you can link to is a little different but still defined by the Rational Team Concert process specification. You might notice that you can select a Plan here (more about that special case in a moment). The type that you choose will change the other options on the dialog window.
- The second Type field shows another list of work item types. This is usually the same list that you saw in the Create dialog window. Select the specific work item type here.
- Enter the work item number or part of the name in the Work Item Number or Words Contained field to search, or select the Search by Query radio button to select and run a query to find the work item. The matching work items appear in the box below.
- Select the desired work item, and click OK to return to Focal Point and save the link.
You can choose to link to an existing plan rather than a work item. It can be very useful to link a Focal Point project element to the release plan in Rational Team Concert that will deliver it. Later, you can use this link to retrieve progress data from Rational Team Concert by using REST view commands (more on that soon, too). However, you cannot create a plan in Rational Focal Point by using the Integration Link, and there is no back link created in the Rational Team Concert plan to refer to the Focal Point element.
Defining and using XPathValueFetcher business rules
As with other business rules, the workspace administrator defines the XPathValueFetcher business rule as the value for a particular attribute, with or without a schedule. The end user doesn't interact with the business rule at all, but simply sees the result of its execution. At the most, end users might need to force the business rule to run to get an updated value. You can define an OSLC view command to allow them to do that.
To define the XPathValueFetcher business rule, you need to understand:
- The REST services provided by Rational Requirements Composer and Rational Team Concert, at least to some extent
- How to use REST queries to access data from those sources
- How to navigate the XML output to identify the correct XPath for the attributes that you want to retrieve
The format for this rule is:
=XPathValueFetcher('Integration link attribute',"URL parameters","XPath expression", "Label","true")
You can append either the
run_at=x, y, z or
update_interval=n parameter to specify the schedule on which to run. The
run_at parameter defines the time to start running the rule (x on a 24-hour clock), the delay before running it again (y days), and when to initiate the first run (in z days time). The
update_interval parameter specifies the interval time in hours between business rule executions. These parameters apply to all Rational Focal Point business rules.
For Rational Requirements Composer resources, you must include
/ds:dataSource/ds:artifact/ at the start of the "URL parameters" and "XPath expression" values. For Rational Team Concert resources, ensure that you are using the OSLC Version 1.0 syntax.
Listing 1 shows an example that uses a Focal Point attribute, Derived Requirements, to locate an artifact in Rational Requirements Composer, extract the value for Estimated Cost, label it Cost, and update every 12 hours.
Listing 1. XPathValueFetcher example extracting values from Rational Requirements Composer
=XPathValueFetcher('Derived Requirements',"/ds:dataSource/ds:artifact/rrm:collaboration/ rrm:attributes/attribute:objectType/attribute:customAttribute[@attribute:name= 'Estimated%20Cost']/@attribute:value","/ds:dataSource/ds:artifact/rrm:collaboration/ rrm:attributes/attribute:objectType/attribute:customAttribute[@attribute:name= 'Estimated Cost']/@attribute:value","Cost","update_interval=12")
Listing 2 is an example using the Focal Point Work Items attribute to locate a Rational Team Concert element and retrieve its State value, labeling it Work Item State. Because there is no schedule on this business rule, it will run by default like other rules.
Listing 2. XPathValueFetcher example extracting value from Rational Team Concert
=XPathValueFetcher('Work Items',"/?oslc_cm.properties=rtc_cm%3Astate%7B*%7D"," //rtc_cm:state/dc:title[text()]","Work Item State", true)
Define your own XPathValueFetcher business rule
To define your own rule, you'll need to use a REST client (available for most web browsers), such as Poster from Mozilla Firefox.
- Open your REST client. (Check your browser's online help if the client is not readily apparent.)
- Set the header values to
acceptwith a value of
- Find the value from an Integration Link attribute to the appropriate artifact type (after you've associated a Focal Point element to an Rational Requirements Composer Collection, or an Rational Team Concert work item), and copy that value into the URL field of the REST client.
- For Rational Requirements Composer, append
/ds:dataSource/ds:artifactto that value, and issue a
GETrequest to see the data associated with that object.
A sample reportable REST URL for a Requirement Collection might look like the one that follows, which is for a Rational Requirements Composer artifact:
The GET request returns an XML representation of the data for that artifact. Browse the XML to identify the attributes that you want to retrieve, and construct the XPath value. You can also use an XPath editor to help you construct the expression.
Example of defining an XPathValueFetcher business rule
The following example walks you through defining an XPathValueFetcher business rule to retrieve a custom attribute value from a Rational Team Concert work item to copy back to a Focal Point attribute value. You can follow the same steps, substituting the values of your attributes.
- Open your REST client.
You will need the URL to the correct artifact type in Rational Team Concert to identify its attributes. The easiest way to do this is to copy the value from an existing Integration Link attribute in Focal Point.
- Log in to Focal Point and locate a link to the Rational Team Concert artifact that you want to retrieve information about. In this case, the Link to Plan Item attribute holds the link. If it isn't set yet, go ahead and temporarily establish a link to a sample artifact (later, you can delete the link).
Figure 12. Link to Plan Item attribute values
- Right-click the link value, and select Copy Link Location.
Figure 13. Copy the URL value from Link to Plan Item
- Paste the URL into the URL field of Poster as shown in Figure 14.
Figure 14. Poster settings
- Provide credentials to authenticate to Rational Team Concert. In this case, we are using
bob(see Figure 14, above).
- Click the Header tab, and enter these values:
- Click Add/Change to add the header to the list.
- Click the Content to Send tab, and enter
application/xmlfor Content Type.
Figure 15. Content Type attribute field
- Click the GET button to retrieve the attribute information for that artifact. It might take a few seconds, but you should see a progress tracker.
- When the request completes, you should see a window like Figure 16.
Figure 16. REST request results in Poster
This information shows the XML structure of this artifact, with attributes and values. We are most interested in the attributes.
- The easiest way to locate the attribute of interest is to search, which you can't do in this data window. So instead, select all of the text in the main window (Ctrl-A), copy it (Ctrl-C), and paste it (Ctrl-V) into a Notepad or plain text file.
- In this example, the custom attribute name is Num Business Needs Blocked. However, a search did not locate that text. Sometimes, the Rational Team Concert internal representation of an attribute or value differs from what is shown in the UI. To locate the internal name:
- Log in to the Rational Team Concert project with project admin privileges.
- From the toolbar, select Manage this Project Area (see Figure 17).
Figure 17. Rational Team Concert admin menu
- From the list on the left, select Work Items, and then choose the type of that you're using.
Figure 18. Rational Team Concert work item configuration settings
- Scroll down to find the attribute name, with its type and internal ID. In the example in Figure 19, the Num Business Needs Blocked attribute will show up in the XML as numbbnblocked.
Figure 19. Specific work item values
- Search your notepad text for the identifier (in this case, numbnblocked). You should find something like the results in Figure 20.
Figure 20. Search results
- Copy the rtc_cm:numbnblocked text into your XPathValueFetcher business rule as the XPath expression. You will also use it in the URL parameters field to restrict the query sent to only this attribute (to avoid pulling back a lot of other data about that work item element that you won't use). The resulting XPathValueFetcher rule might look like Listing 3.
Listing 3. XPathValueFetcher rule example
=XPathValueFetcher('Link to Plan Item',"/?oslc.properties=rtc_cm:numbnblocked", "//rtc_cm:numbnblocked[text()]","Blocked","run_interval=12h")
The business rule is using the Link to Plan Item attribute to locate the plan item in Rational Team Concert, and then requesting the integer value for the work item's numbnblocked attribute and converting it to a text value (
[text()]). (If you were updating an integer attribute in Focal Point, you wouldn't need to convert the value to text.)
You should be able to repeat these steps to locate the specific values that you want.
You can also use the REST View Command configuration interface to see the list of possible attributes for an element. Follow the instructions for configuring a REST view command, and you should be able to see the available attributes for mapping. That gives you an idea of what is available, but you might still need to follow the preceding steps to find the specific XPath for the attribute.
Defining OSLC view commands
The OSLC view commands are all preconfigured. You simply associate them with the views from which you want to invoke them.
To associate predefined OSLC view commands to your views:
- Select Configure > OSLC View command.
- Click Add view command.
- From the list of views, select the view where you want to use the command.
- In the configuration window that follows (see Figure 21), specify the values:
- OSLC view command Name
- Give the command a name so you'll remember what it does. This name is used only in the configuration views; it is not shown to the end user.
- Linked elements
- This pull-down menu shows all of the linked elements for the element type in this view. Remember that the OSLC view commands operate in bulk against the set of artifacts that are linked to the element where you launch the command. The linked element that you choose needs to have an Integration Link attribute, which will be updated by the operation.
- Attribute where the Jazz Team Servers were configured
- Specify the Integration Link (from the linked element) that will be referenced or updated by the command.
- From the list of predefined commands, select the particular OSLC view command that you want to run.
Figure 21. OSLC view configuration menu
- Click Create to create the view command.
- In the view that you specified, the icon for this OSLC view command appears in the element's title bar. Trigger its execution by clicking the icon.
Figure 22. Create new artifact in Rational Requirements Composer
Remember that OSLC view commands are pre-configured, and you cannot further extend their capabilities.
Implementing REST client view commands
REST client view commands provide the most flexibility in exchanging data bidirectionally between Focal Point and CLM applications. You can exchange multiple attribute values in a single command. You can also insert additional steps, before or after the command or even as part of the command itself, to convert data representations and values.
As with XPathValueFetcher rules, you will need the URL to the resource or set of resources with which you want to exchange data. You'll use one specific example to set the template. When you actually run the command, the appropriate values will be substituted based on your selected elements. It's often easiest to simply create a link to the desired artifact (using an Integration Link attribute) and copy the link value. You can also go to the Rational Team Concert root URL and navigate the REST API from there to identify the available resources.
To improve the performance of REST view commands, you can use query parameters (as defined by OSLC) to limit the amount of data sent or retrieved by the request. By default, the entire XML is sent or retrieved, even if only a few of the values are used. You can define parameters either in the REST view command itself or in a Focal Point attribute that you then reference from the command. For an example of the latter, see the Sync Details from CCM Plan Item command. We did not specify parameters on the other commands, but you could add them if desired.
To configure and run view commands, you must ensure that the attributes used are visible in the view you choose and that those that are updated are editable. In some cases, the attributes that are updated might really be for internal use, to support other REST commands or calculations. Ideally, those should be hidden for most users to avoid confusing them or, worse, having them change a value that they shouldn't. For production use, consider configuring special restricted views to enable specific view commands, making them available to only a few users. Alternatively, group these in their own section at the bottom of the element, and collapse it when you set up the initial view settings so users are less likely to notice or explore it.
To define a REST view command:
- Select Configure > REST client view command.
- Click the Add view command button.
- From the list shown, select the view to use. Remember that the attributes you will change need to be editable in that view, and any attributes that you reference must at least be visible.
- REST client view command name
- The name you'll use to invoke the command. This name will appear in the pull-down menu for the end user to select, so ensure that it is meaningful.
- REST request method
- The type of REST command that you want to invoke:
- GET to extract data from the linked CLM artifact
- PUT to update or push values from Focal Point to the linked CLM artifact
- POST to create an element in CLM with data from Focal Point
- DELETE to delete data in the linked CLM artifact
- SYNCHRONIZE to update values in the Focal Point artifact from values in CLM
- Friends list
- The server "friend" to which you'll send the REST request
Figure 23. REST client view command configuration
- If you are using the GET method:
- Specify the REST Application Request URL by copying the URL for the resource type you want to access (for example, from a Plan Item link or based on your navigation of the Rational Team Concert XML).
- You will then need to complete the XPath values by using your REST client to identify the values to use. See the section on XPathValueFetcher for more details on how to do that.
- If you are using one of the other methods,
- Next to Choose URL Attribute to REST Artifact, click Select.
- From the list of Focal Point attributes, select the one that holds the URL to the resource or artifact type that you want to access (that is, the appropriate Integration Link attribute).
Figure 24. Specifying the Integration Link attribute to use
- Copy a link to one of those resources or artifacts (the value of the Integration Link) in the REST Application URL to Template XML field. (The easiest way to do this is to set the Integration Link attribute in one element, and then right-click the link and select Copy Link Location. Then copy the value into this field. Alternatively, you can navigate the XML hierarchy with a REST client such as Poster, as described in the XPathValueFetcher section, to find a suitable value.)
Figure 25. Copy the URL value from the Link to Plan Item attribute
- Click Get Template XML to get the XML related to that resource.
Figure 26. Get template XML option
- The Template XML should be generated for you by the previous step (Get Template XML button). You will see explicit values based on the sample URL that you used. Don't worry, because the values will be substituted at run time, based on the actual artifact specified in the Focal Point attribute for the element.
- If you are defining a PUT command and want to include the entire template XML in the command, check the Use Template XML for REST PUT call option. Otherwise, only the necessary subset will be included. This applies only to PUT commands.
- For Root XPath to REST Application Artifact, click the Select button to see the available values based on the URL and template XML specified. Usually, the correct choice is /rdf:RDF.
Figure 27. Set root XPath to artifact
- Under Attribute mapping, click the Add button to see the available Focal Point and CLM attributes.
Figure 28. Mapping attributes
- From the list, select the Focal Point attribute and its corresponding CLM attribute that will be affected by this command, and click Map.
- Continue to map the pairs of attributes as needed for this command.
- When you have finished the mapping, click Close to close the mapping window.
- Under the Request Parameter Table heading, specify any other parameters to use in the query (for example, to narrow the query to a subset of attributes to speed performance).
- The Request Header mapping specifies the header names and values to use in the REST request (as you did in your REST client), typically these values:
- OSLC-Core-Version = 2.0
- Use this header if you want to ensure that resources are represented as defined by the OSLC 2.0 spec. This is the level currently supported in CLM. If that changed, this header would ensure that resources continue to be represented the same way.
- Click Save to save your command.
It now shows in your list of configured commands.
When you go to the view with which you associated this command, you will see the command listed in the pull-down menu at the top of the view. If you are looking at a tree view, the command also appears in the title bar of the displayed element.
Figure 29. Invoking REST client view commands
To invoke the command for only the element shown, use the pull-down in its title; to invoke the command for all elements in the view, use the pull-down menu at the top.
From the pull-down menu, select the command that you want to run, and then click the Go () icon next to the menu to invoke the command.
- Remember that the commands are defined for a single view at a time. If you want access to a command from multiple views, you must define it for each view.
- Although you can copy and modify existing commands, you cannot change them to point to another view.
Creative uses of REST view commands
There are some very creative ways that you can apply REST view commands. Here are a few examples from the Governance of Application Development Outsourcing solution:
- We wanted to fetch the completion information (% complete/remaining) from the Rational Team Concert release plan. We couldn't request it directly from the release plan XPath. However, we were able to request the path to the release plan progress tracking information (rdf:Description/oslc_pl:progressTracking/@rdf:resource) and store that URL in another attribute. We then used that URL and XPath in a second REST view command to request the work completed and work remaining for the release plan. We calculated the % complete in Focal Point after retrieving the data (Rational Team Concert did not store the % value for us to retrieve directly).
- We were also able to request the Test Plan link from the release plan (by using the testedByTestPlan attribute: rdf:Description/calm:testedByTestPlan/@rdf:resource).
- In retrieving time-based data from Rational Team Concert, we converted from milliseconds to days as part of the command by adding a calculation to the attribute mapping (see Figure 30).
Figure 30. Including a calculation in attribute mapping
- We also did some fancy pre-work in Focal Point to convert our text and numeric representation of Priority into the complex literal enumeration values that Rational Team Concert uses internally (
priority.literal.I,plus a 0 or 1, plus a final variable integer):
- We used hidden Focal Point attributes to calculate the variable integer and determine whether to use 0 or 1, based on the Focal Point Priority value.
- We used another Focal Point attribute to concatenate those calculated values with the rest of the string to formulate a complete URL value for Rational Team Concert:
="https://gado.rtp.raleigh.ibm.com:9443/ccm/oslc/enumerations/ _nPrf4NmfEeGykNT4MeB2Fw/priority/priority.literal.l" + 'CCM Priority preIndex Value' + 'CCM Priority Value'
- When we defined the attribute mapping for the REST view command, we used that final Focal Point attribute with the full URL value to set the corresponding Rational Team Concert Priority value.
- Finally, one very special thing that we did was to retrieve expected end-date information from a Rational Team Concert snapshot (because the plans do not store that information other than in a plan snapshot). To do this, we had to use internal APIs that are also used by the OSLC view commands:
- We used the Release Plan link to locate the value of the Release Plan Project Area (rdf:Description/rtc_cm:projectArea/@rdf:resource) and store it in an attribute. (We used the same command that we used to get the Release Plan progress tracking information.)
- In a second command, we sent a request to the Project Area to find out its name (rdf:Description/dcterms:title ) and stored that in an attribute.
- Referencing the Project Area Name and Release Plan Progress location, we used another attribute in Focal Point (Release Plan Sync Snapshot Data URL) to hold the expression for the internal API (notice the references to those two other attributes):
=substring('Release Plan Progress', 0 ,"oslc") + "service/com.ibm.team.tpt. common.internal.IImpexService?PROJECT_ID=" + 'CCM Release Plan Project Area Name' + "&Plan_ID=" + substring ('Release Plan Progress',"plans/","/progressTracking")
- When defining the REST view command, we specified the '"Release Plan Sync Data Snapshot"' attribute for the ""Choose URL Attribute to REST Artifact"" field. We constructed the URL by copying values from a project that had run the previous view commands and had the project area name and progress tracking values.
- We mapped the Rational Team Concert Start Date and Finish Date attributes to the appropriate Date attributes in Focal Point.
As this article has shown, there are several different techniques you can use to integrate Focal Point with the CLM solution or with other REST-based applications. Remember that, because client implementations differ, you might have to explore the CLM schema and its XML hierarchy to locate the information that you need to retrieve and format the request correctly, especially for XPathValueFetcher, which requires more manual configuration. Understanding the REST XML representation of the artifacts and attributes and how to use a REST client to navigate that XML will be extremely helpful in completing your configurations.
Rajesh Kanna and Karthi Dakshinamurthy, from the Focal Point development team, made significant contributions to this article and to defining the integrations in the GADO solution that provided some of the illustrations used here. Thanks also to Richard Demidio, Rational Certified IT Specialist, who provided great details in the XPathValueFetcher section.
- For more about Focal Point:
- Explore the Rational software area on developerWorks for technical resources and best practices for other Rational Software Delivery Platform products.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, anytime, and many of the Getting Started ones are free.
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.
- Join the Rational Focal Point forum to ask questions and participate in discussions.
- Get connected with your peers and keep up on the latest information in the Rational community.
- Rate and write a review of Rational Focal Point. It's quick and easy.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook, Twitter (@ibmrational), and YouTube, and add your comments and requests.
- Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.