Jazz Library Configuring Rational Team Concert to establish a global configuration context for work item links
Author name

clm,elm,workflow-management,continuous-engineering-solution,jazz-foundation,rational-team-concert

Tue, 18 Dec 2018
5 min read
0

Configuring Rational Team Concert to establish a global configuration context for work item links

Kathryn Fryer, IBM
Last updated: 18 December 2018
Build basis: Rational solution for Collaborative Lifecycle Management 6.0.6 and Internet of Things Continuous Engineering Solution 6.0.6

This article is part of a series that addresses practices and considerations for configuration management in the Rational solution for Collaborative Lifecycle Management (CLM) and Internet of Things Continuous Engineering Solution (CE). If you are not familiar with the configuration management capabilities, see version 6.0.6 of Configuration management: Concepts and capabilities and Overview of global configurations in IBM Knowledge Center.

 

This article describes how to configure Rational Team Concert so users can link work items to specific versions of lifecycle artifacts. The article focuses primarily on links from Rational Team Concert to Rational DOORS Next Generation requirements and Rational Quality Manager test artifacts.

Note:

  • Rational Team Concert provides source code configurations that can be part of a global configuration. The support for source code configuration management is not relevant to this article.

  • The information in this article does not apply to links between change sets (including Rational DOORS Next Generation change sets) and work items. Change sets are not versioned, and work items link directly to the change set resource.

Contents

Introduction and concepts

With configuration management enabled, artifacts such as requirements and tests are versioned. To work with the versioned artifacts, you choose a configuration in the application (for example, Rational DOORS Next Generation or Rational Quality Manager) that specifies which artifacts and which versions of those artifacts to use. Global configurations group configurations from the individual applications and indicate which versions of artifacts belong together. When you create or traverse a link across lifecycle domains, for example from a requirement to a test, you must be in a global configuration context that includes configurations for both artifacts; the link resolves based on the content of the global configuration. This practice is also true for links between versioned artifacts across configurations from the same domain.

Because a configuration can contribute to more than one global configuration or be part of a broader global configuration hierarchy, and you can deliver changes across streams, links between versioned artifacts can be visible across multiple global configuration contexts. The system always uses the current global configuration context to create or resolve links to versioned artifacts.

Linking from versioned artifacts to work items in Rational Team Concert works differently. Rational Team Concert work items are not versioned. These artifacts are an implementation of the OSLC Change Request artifact, and the OSLC Configuration Management specification indicates that change requests are not versioned artifacts. Work items do not belong to any configuration and, therefore, can’t be contributed to any global configuration. However, users still need to link work items to versioned artifacts in the other lifecycle domains, and expect the system to resolve those links in the correct configuration context. The system needs a way to associate a Rational Team Concert work item with a global configuration, so users can link work items with the intended artifact versions.

This article describes how to configure Rational Team Concert to make the global configuration association, and describes the linking behavior for work items in a global configuration context. Understanding the behavior is essential to define your usage model and to ensure that you configure associations correctly to support your scenarios. You must define how iterations and releases will map to your global configurations, which work item attributes you will use to identify the release for the different OSLC link types and work item types, and how and when those values should be set or modified. Without the appropriate configuration to associate the global configuration context, links from work items might not resolve to the correct version of an artifact, might not resolve at all, or might not even be visible from the versioned artifact.

As you define your usage and configuration, carefully consider scenarios where the behavior might be unexpected, such as in these situations:

  • Changing target releases or iterations for work items
  • Changing global configuration context for versioned artifacts, for example, working in parallel streams or delivering changes across streams
  • Changing contributions in a global configuration, such as replacing streams with baselines
  • In a single stream strategy, using the same global configuration across multiple releases, with global baselines to represent final release content
  • Having teams work in the context of different global configuration contributions within a multi-level global configuration hierarchy

For details on these scenarios and other considerations, see Understanding how changes can affect link visibility and resolution and Implications and considerations.

Link storage with configuration management

With configuration management enabled, all links are directional, with no back links. A link is stored with only one artifact in the relationship (the “source” or “owner”, which is typically the downstream artifact). The application for the source artifact stores the link information and publishes it to the Link Index Provider (LDX) application by using a tracked resource set (TRS) feed. The application for the target artifact queries LDX for incoming links based on the current configuration context, and displays them to the user. For example, Rational Quality Manager stores the “Validated-by” link for a test case to a Rational DOORS Next Generation requirement. When the user opens the requirement in Rational DOORS Next Generation, the system queries LDX based on the configuration context to display the incoming “Validated-by” links.

Link storage is independent of where you initiated the link. You can create the “Validated-by” link from the requirement or from the test case, but it is always stored in Rational Quality Manager. As noted before, the system uses the current global configuration context to create or resolve links to versioned artifacts. For example, when you create the “Validated-by” link, the system uses your current configuration context to identify the correct artifact version on the other end of the link. The link is stored with the context of the Rational Quality Manager configuration. Because both Rational Quality Manager and Rational DOORS Next Generation can set the configuration context and deliver across streams, that link can be visible in more than one configuration context; each call to LDX includes the current global configuration context.

All links that involve Rational Team Concert work items are always stored by Rational Team Concert, including links between work items and requirements, tests, and designs. The other CLM applications query LDX to resolve those links. However, unlike Rational Quality Manager and Rational DOORS Next Generation, you do not explicitly set a current configuration context when you work with Rational Team Concert work items. Instead, Rational Team Concert uses other mechanisms to determine the appropriate configuration context for the versioned artifacts, as described in the following section.

Configuring Rational Team Concert to establish global configuration context

To link Rational Team Concert work items and versioned artifacts in the other CE/CLM applications, you must first set up the project area associations and friend relationships as you would for any CE/CLM environment. For details, see Administering projects in IBM Knowledge Center. This article assumes you’ve correctly configured the basics, and that users have at least read access to all the artifacts.

To link between Rational Team Concert work items and versioned requirements or tests, you must make additional changes so the system can determine the correct global configuration context for creating and resolving links. The mechanisms and changes are described in the next section.

To ensure links display and resolve correctly, you must configure the Rational Team Concert mechanisms for your process.

Rational Team Concert mechanisms to configure

There are two main aspects to setting up the connection between work items and global configurations.

  • The release and its association to a global configuration and an iteration in the Rational Team Concert timeline
  • The link type or attribute mappings that specify which work item attribute to use to determine the correct release and its associated global configuration
The administrator typically configures these mechanisms in the project area administration, as described in following sections.

Associating releases with iterations and global configurations

A Rational Team Concert release is an actual resource, with the type of “Deliverable”. Releases are not a new concept or object type, but they are now integral to how the system determines global configuration context for a particular work item link.

In the project area administration, go to the Releases page to define and manage releases.


You must define a release and associate it with your global configuration and an iteration in your project timeline. The following image shows the dialog box where you add a new release and how it is related to the AMR Mobile US 2.0 iteration in the timeline, and the AMR Mobile US global configuration.

In this example, the iteration in the timeline has a hierarchy with subiterations (indicated by the + icon). In an iteration hierarchy, subiterations inherit the same release and global configuration associations as the parent, unless you explicitly override the release on the subiteration (which then applies to the rest of the subiterations on that level of the hierarchy). The following example shows a release defined for the top-level iteration named AMR Mobile US 2.0. The subiteration AMR Mobile US 2.0 M1 inherits that release and its global configuration association. However, AMR Mobile US 2.0 M2 is associated with a different release, which applies to that subiteration and AMR Mobile US 2.0 GA. (More likely, the release would change with AMR Mobile US 3.0.)

 

Note: A release can only ever have one global configuration association at any given time. You can change the associations. For example, after you deliver AMR Mobile US 2.0, you might want to associate the release with the global baseline for AMR Mobile US 2.0 instead. However, the release can have only one association at any given time.

You can define more than one Rational Team Concert release for the same iteration, but you cannot associate that same iteration with more than one global configuration. When the systems resolves the configuration context for that iteration, the system only uses the first (top-most) release that appears in the list.

Work items are tied to releases by one or more attribute values. The attribute might explicitly specify a release (such as the Found In attribute), or it might specify an iteration that is associated with a release (such as the Planned For attribute). You can also define custom attributes that specify the release. Frequently, a work item has only a single attribute that specifies the release; however, a work item can have more than one attribute (for example, both Found In and Planned For), and they can be set to values for two different releases.

Associating links with releases and global configurations by using attribute mappings

The release has an association with the global configuration, and the work items have an association with the release. However, different work item types might use different or multiple attributes for the release, and different OSLC link types might involve different work item types. The system needs a map to determine which work item attribute to use when it creates or traverses a particular OSLC link type.

For each OSLC link type, set the OSLC Link/Attribute Mapping to specify which work item attribute defines the release relationship. In other words, you associate a work item link type with a release-valued property of the work item, which the release selects when creating or navigating links of that type. For each link type, the system can then determine the release and the associated configuration context when it creates or traverses a link of that type. You must consider which work item types will be involved in the link relationship, and the attributes for those work item types.

In the project area administration, go to the Configuration Management – OSLC Link/Attribute Mapping page to define the mappings.

 

Default mappings are provided based on the default work item definitions; the administrator must click the text (shown in the images above and below) to enable them. After they are enabled, you can modify the defaults or specify your own mappings. For each OSLC link type, the mapping indicates which work item attribute will point to the release value, either directly (such as the Found In field, or if you prefer, a custom attribute with release values) or indirectly by an iteration value (such as the Planned For field) that is associated with a release.

 

The mapping is based on the type of OSLC link that you are creating or resolving, and the attribute in the linked work item. Different work item types might have different attributes. For example, an “Implements Requirement” link is most likely to a planning work item, such as a feature or story, which typically has a “Planned For” implementation in a particular release. A “Blocks Test Execution” link is probably to a defect, which would be “Found In” a particular release. You can customize the default mappings based on how you define your work items and attributes, and your linking scheme. You can’t customize the link types, which are defined by OSLC.

This section explores how the system resolves the global configuration context for the work item links in these scenarios:

  • Creating a link from a work item to a versioned artifact
  • Creating a link from a versioned artifact to a work item
  • Displaying and resolving an existing link in a work item to a versioned artifact
  • Displaying and resolving an existing link in a versioned artifact to a work item

Whether you initiate link creation from the work item or the versioned artifact, Rational Team Concert always stores the link information. The application for the versioned artifact does not store any link information, but queries LDX for the incoming links.

Because Rational Team Concert stores all the work item link relationships, the behavior for these scenarios is the same whether the versioned artifact is a requirement or test artifact.

Creating a link from a work item to a versioned artifact

In the work item, you select which type of link to create. Rational Team Concert checks the link type and attribute mappings to identify which attribute to use to identify the release, and, therefore, the global configuration context. For example, if you create a “Tested by Test Case” link and you are using the default OSLC Link/Attribute mapping, Rational Team Concert uses the “Planned For” field to determine the iteration, associated release, and associated global configuration.

Rational Team Concert sends the global configuration context to the other application, which then populates the “artifact selection” dialog box based on that global configuration context. If you were creating a new artifact to link to, the “artifact creation” operation would be in that global configuration context. When you have selected or created the artifact to link to, Rational Team Concert stores the link information for the work item, and points to the artifact’s URI without any version information; it includes the global configuration context for the link in the TRS feed to LDX. The work item displays the link.

If you then view the linked artifact in the correct global configuration context (in Rational DOORS Next Generation or Rational Quality Manager), the CLM application queries LDX based on that global configuration context, finds the incoming link from the work item in LDX, and displays that link.

In both cases, the link itself is stored in Rational Team Concert; the versioned artifact does not actually store any information about the incoming link from the work item.

Creating a link from a versioned artifact to a work item

In Rational DOORS Next Generation or Rational Quality Manager, you set your global configuration context. When you create an OSLC link to Rational Team Concert, the application makes a request to Rational Team Concert for its “link creation” dialog box, including the global configuration context. Based on the link type you chose, Rational Team Concert checks the link type and attribute mappings, and identifies the attribute to use to identify the release and global configuration mapping.

If you are linking to an existing work item, Rational Team Concert filters the results in the “link creation” dialog box to only those results in the release for the current global configuration context, which means that work items that are “Found In” that release or “Planned For” an iteration associated with that release (or with a custom attribute that points to the release). You can remove that filter and link to any work item (for example, if you know the story hasn’t been planned yet, or is about to be moved to a different iteration). However, doing so can affect the link resolution and how the link is displayed as described below, so use caution.

 

If you are creating the work item for the link, Rational Team Concert automatically populates the appropriate attribute with the release or iteration value for the current global configuration context, based on the link type and release-to-global-configuration associations. In the following image, the Planned For field is automatically set to the top-most iteration for the release associated with this global configuration.

 

You can override these attribute settings. However, doing so can affect the link resolution and how the link is displayed as described below, so use caution.

After you select or create the work item to link to, Rational Team Concert stores the link information for the work item, and points to the artifact’s URI without any version information; it includes the global configuration context for the link in the TRS feed to LDX. The work item displays the link.

For the versioned artifact (for example, requirement or test case), the application queries LDX with the current global configuration context, and displays the incoming link, assuming you did not override the default link creation settings. If you disabled the filter so you could link to a work item that is not related to the current global configuration, or changed the prepopulated release attribute when you created the work item, the work item might have a different value for the global configuration context, based on the release associated with the values you used. In that case, when Rational DOORS Next Generation or Rational Quality Manager queries for incoming links with the current global configuration context, it will not discover the link you just created (because it has a different context), and the link will not be displayed.

Displaying and resolving an existing link in a work item to a versioned artifact

Because Rational Team Concert stores the work item link information, the link is always visible in the Rational Team Concert work item.

When you want to resolve the link—by either displaying a preview (rich hover) or clicking to open the linked artifact—Rational Team Concert determines the attribute mapping for that particular link type and uses the value of that attribute to determine the release for the work item, and the associated global configuration for that release. Rational Team Concert then passes the link information with the global configuration context to the target application to display the versioned artifact in the correct global configuration context.

Displaying and resolving an existing link in a versioned artifact to a work item

The versioned artifact does not store any information about the link to the work item.

When you view the versioned artifact, the application queries LDX with the current global configuration context to discover any incoming links and displays them with the artifact. Those links could be from other artifacts besides work items. If the application does not find incoming links for this global configuration context, no links are displayed.

Resolving a displayed work item link is straightforward; although Rational DOORS Next Generation or Rational Quality Manager sends the global configuration context, Rational Team Concert uses only the artifact URI to display the preview of the artifact.

A Rational Team Concert release can be associated with only one global configuration at a time. By extension, any work item link to a versioned artifact is associated with only one global configuration at a time. For the versioned artifact, the incoming work item link will only be displayed in that single global configuration context. Other work item links might be displayed in another global configuration context, depending on the defined associations and mappings. If you work with versioned artifacts in different global configuration contexts, links to work items are displayed only if the work item is associated with that particular global configuration context. Incoming links will likely be displayed in some global configuration contexts but not others. Understanding the behavior is essential to planning your linking strategy and how you will configure Rational Team Concert and links to work items.

Rational Team Concert uses attribute values such as Found In and Planned For to determine the release and associated global configuration context. If you change those attribute values (for example, set Planned For to a different iteration), it could change the associated global configuration context and affect existing links. In that case, the links from the work item would resolve to the new global configuration context. If the artifact doesn’t exist in that new global configuration context, the link won’t resolve at all. For the versioned artifact, the query to LDX won’t return that incoming link because it’s no longer part of the original global configuration, and you will not see the incoming link at all. If you viewed the artifact in the new global configuration context, you would see the incoming link. This behavior can be useful, for example, when you re-plan work to a later release.

Similarly, if you change the release to associate with a different global configuration context, any links from work items to versioned artifacts will resolve only in that new context. Versioned artifacts in the previous global configuration context will no longer show incoming links from the work items, but those in the new global configuration context will.

If a work item includes both the Found In and Planned For fields, and those are set to values for different releases, different link types might resolve to different contexts. For example, the “Affects Requirement” link type might determine Release1 from the Found In field, with an association to GC1, while the “Implements Requirement” link type derives Release2 from the Planned For field, with a GC2 context. If you open the requirements in the GC1 context, you will see the incoming Affects Requirement (Affected by) link, but not the Implements Requirement (Implemented by) link. If you change the context to GC2, you’ll see the Implements Requirement link but not Affected By.

If you do not configure the Rational Team Concert releases and link type or attribute mappings, links to versioned artifacts might resolve to the default configuration (the first stream of the original component of your project area), or not at all. Versioned artifacts in global configuration that use the default configuration might show the incoming links, but they will not be visible in global configuration using other configurations. This is true even if you create the link from a particular global configuration context: without the Rational Team Concert associations, Rational Team Concert can’t provide the correct configuration context to LDX.

Note: If you set your configuration context to a local configuration instead of a global configuration, you will not see any incoming links from other components or applications.

Implications and considerations

Your usage model for global configuration management must take into account the behavior and configuration for linking between work items and versioned artifacts. You must define how iterations and releases will map to your global configurations, which work item attributes you will use to identify the release for the different OSLC link types and work item types, and how and when those values should be set or modified.

The following actions might cause the incoming link from the work item to seemingly “disappear” from the versioned artifact (the link still exists for the work item and in LDX, but is not discovered based on the global configuration context):

  • Changing the current global configuration context for the artifact to a different context from the one where you established the work item link, including delivering the versioned artifact to a different stream, and then switching to that new stream context.
  • Taking a baseline of the versioned artifacts. If the baseline is then included in the original global configuration where the link was established, the incoming links will appear in the baseline, but not the stream. If the baseline is included in a different global configuration, the links won’t appear in the baseline.
  • Changing the association between the Rational Team Concert release and the global configuration (or less likely, the release and iteration).
  • Changing the work item’s attribute value that indicates the release, such as changing the Planned For value. Note: If you change the work item attribute for the release, save the work item before you add or change any links. Until you save, the work item will use the previously stored value to determine the global configuration context.
  • Creating links from a work item before setting the attribute value that indicates the release. With no release specified, the system tries to establish a link to the default stream of the chosen component. If the artifact does not exist in that stream, you won’t find it. Set the attribute for the release and save the work item before you create links to versioned artifacts.

Although the versioned artifacts might not show the incoming links, the work items always display the links to the versioned artifacts. You can define work item queries that include those links, filtering by other fields such as Found In or Filed Against, for example, to view all open defects against a component in a certain time period. You can include such queries on dashboards if appropriate. Note: If you try to resolve a link from the query results, the artifact version you see is still determined by the release and global configuration association for that work item, which might or might not be correct.

For work items that can specify two release values (for example, in the Found In and Planned For fields), consider which link types use which attributes. The work item link might appear in different global configuration contexts for versioned artifacts depending on the link type. For example, a defect work item might have both Found In and Planned For fields, and use the Found In value to resolve “Blocks Execution” links and the Planned For value to resolve “Tested By Test Case” links. When you create a defect that “Blocks Execution” of your Rational Quality Manager test result, the system sets the Found In value based on the current global configuration context, and the link to the result resolves in that context. Then, you set the Planned For field to a later release, with a different global configuration association. When you create a Tested By Test Case link from the defect to a test case, the system uses the Planned For value and resolves the link to the second global configuration context: the incoming does not appear in the test case in the original global configuration. Similarly, the Blocks Execution link appears only in the original global configuration, not in the second global configuration. This practice can be useful because the link appears in both affected configurations. However, if you don’t understand the behavior, it can be confusing to have links from a single work item resolve to artifacts in different global configuration contexts.

 

You can also replicate this scenario by using multiple work items, potentially of different types, that point to different releases. For example, instead of using a Planned For field on the defect work item, you could create a task to fix the defect, and associate the task with the later release and different global configuration context. You can then link the work items together to establish traceability. If a defect applies to multiple variants, and you want to see the incoming link in each of those global configuration contexts, you can also create other linked or child work items that each specify a different release and global configuration. This approach would add the overhead of additional work items.

Ensure that you work through your development scenarios to plan how you will configure and use work item linking, including scenarios such as the following ones:

In this scenario, if you set your release to the global configuration stream, all work item links will resolve to the stream. When you baseline the stream, you do not see the incoming links in the baseline, because the mapping is to the global configuration stream. At the end of an iteration or release, you can change the release mapping for that iteration to point to the final global configuration baseline, so you would see all the incoming links in the baseline but not the stream. You can then associate your next iteration or release with the global configuration stream, so new links for subsequent work appear in and resolve to the stream context. At the end of the release, you can set all iterations to point to the final global configuration baseline, so all links for that release are visible in that baseline context. In this scenario, in the versioned artifact, you only see the incoming links for that particular global configuration or release. You can still view all the link information across all releases from the Rational Team Concert work items; however, those links might resolve to different global configuration baseline and stream contexts.

  • Teams working at different levels in a global configuration hierarchy

In a complex global configuration hierarchy, different teams can work in lower-level global configuration contexts within a broader, higher-level global configuration. For example, if a global configuration “Car” includes contributions from global configurations “Power Train” and “Infotainment”, some teams might work at the Car level, while others work directly in the Infotainment context to provide a reusable component across different Cars. The Rational Team Concert release association does not take the global configuration hierarchy into account. If the release is mapped to the Infotainment global configuration, the Infotainment team can create links to work items that resolve in that context only; however, if the team changes the context to the Car global configuration, it would not see the incoming links. If the release is mapped to the Car context, the Infotainment team can create links that resolve in that context, but will not resolve if the team sets the context to an Infotainment-only global configuration.

  • Delivering changes across streams, where work items might apply to both

At any given time, a work item link can resolve in the context of a single release and global configuration. If you deliver or merge the versioned artifact to another stream that contributes to a different global configuration, you will not see the incoming work item link in the second stream. For example, if you have a test artifact linked to a defect in one stream, and you deliver the test artifact to a second stream that’s used in a different global configuration (perhaps because it pertains to a second variant), the link to the defect is shown only in the original test artifact: if you follow the link from Rational Team Concert, it resolves to the original global configuration context. You can change the work item settings so the link resolves to the new global configuration, but then it will not appear as an incoming link in the original global configuration context. You can create a second duplicate work item that points to the new global configuration.

Summary

To ensure links resolve correctly between versioned artifacts and non-versioned Rational Team Concert work items, complete these steps:

  • Define Rational Team Concert releases that are associated with a global configuration and an iteration in the Rational Team Concert timeline
  • Specify attribute mappings for each OSLC link type to indicate which work item attribute indicates the release

Rational Team Concert always stores the link for the work item. When you open the versioned artifact, the system displays the incoming link based on querying LDX with the configuration context. At any point in time, a link between a work item and versioned artifact can resolve to only one global configuration context, based on the link type, work item attribute value, release, and global configuration associations set at that time. Changing any of those four factors can change the global configuration context where the link resolves and appears.

Organizations must consider this behavior as they plan their global configuration strategy and their linking strategy, and must communicate the usage model and expected behaviors to teams so they know what to expect and can create, view, and resolve links in a well-defined and predictable manner.

More information

About the author

Kathryn Fryer is a Solution Architect with over 25 years at IBM, most recently focused on the IBM CE/CLM solutions including global configuration management. She works closely with customers, sales, and development to develop usage models, aid adoption, and improve product offerings. She can be contacted at fryerk@ca.ibm.com.


© Copyright IBM Corporation 2018

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.

Tue, 18 Dec 2018