Work item linking in a global configuration context: Overview

Nick Crossley, Persistent Systems
Kathryn Fryer, Persistent Systems
Last updated: 20 May 2021
Build basis: Engineering Lifecycle Management 7.0.2 and later

This article is one of a series that addresses linking work items and versioned artifacts in a global configuration context as implemented in IBM Engineering Lifecycle Management (ELM) 7.0.2 and later. If you are using an earlier ELM release, refer to the Jazz.net article Configuring Rational Team Concert to establish a global configuration context for work item links.

If you are already using these capabilities in an earlier ELM release and upgrading to 7.0.2 or later, refer to Work item linking in a global configuration context: Migrating from releases before 7.0.2 (coming soon) for details on how to transition to the new implementation.

Note: The information in this article does not apply to IBM Engineering Workflow Management (EWM) source code artifacts, nor to linking change sets in any ELM application to EWM work items.

Introduction and contents

With configuration management enabled across ELM applications, artifacts such as requirements and tests are versioned. When you link between versioned artifacts, the system uses the configuration context you specify to determine the correct version of the target; for links across components or domains, you specify a global configuration that groups configurations for the linked artifacts.

However, change requests and other types of work items are not versioned and are not specific to any configuration, and therefore they do not contribute directly to any global configuration. To create and resolve links from work items to versioned artifacts – and to the correct version of the target artifact – the system requires additional settings, as described in this article.

• Enabling work item linking in a global configuration context:
  • Enabling configuration management context for EWM work items
  • Defining releases in EWM
  • Specifying which work item attribute specifies the release
  • Linking EWM releases to global configurations
  • Indicating the release for a work item
• How global configuration, release, and attribute mappings work together
• Best practices and additional considerations
• More information

Enabling work item linking in a global configuration context

To enable linking and navigation between work items and versioned artifacts in a configuration context, you must:

• Enable the EWM project area to use a global configuration context for work items
• Define releases in EWM for the product or solution releases your teams produce
• For each link type, specify which work item attribute provides the Release value, using the OSLC Link type-attribute mapping in EWM.
• Link the global configurations to the appropriate EWM releases
• Associate work items to releases using the work item’s attributes

Note: When you enable global configuration management, key concepts to understand include link storage and direction: links are stored on only the “outgoing” side of the relationship. All links involving work items are stored in EWM, regardless of the other artifact involved or where or how you create the link. For more details, see the blog post ELM directional linking with CM enabled.

---

Enabling configuration management context for EWM work items

As of ELM 7.0.2, you must explicitly enable EWM to link between work items and versioned artifacts in global configurations. If you do not enable this setting, you cannot set a configuration context in EWM; the system will resolve links between work items and versioned artifacts as if there is no global configuration specified.

Note: If you are upgrading from an earlier ELM version where you enabled Link Type/Attribute Mapping in EWM, this option is automatically set for you.

In EWM project area management, go to the OSLC Link/Attribute Mapping tab and click Enable global configuration resolution for remote resources with versions. This option is not reversible; once you enable it, you cannot disable it.

After you enable this option, EWM displays a configuration context menu for work items. The system uses the context to resolve links from work items to versioned artifacts.

You can also set the configuration context for the EWM dashboard to apply to any configuration-enabled report widgets it contains.

Note: Enabling this EWM option does NOT mean that work items are versioned or have configurations. It simply enables the configuration context menu for work items and link resolution in a configuration context. This option is unrelated to the source code configuration management capabilities in EWM.

Defining releases in EWM

In EWM, a release is a Deliverable produced as output from an iteration or set of iterations, often with an associated release plan. Different teams with different timelines can have different and multiple releases. Releases are a key part to enabling work item linking in a global configuration context.

Define releases in EWM project area management on the Releases page. Associate each release to an iteration in your project timeline. If the iteration has sub-iterations, the release applies to those sub-iterations as well unless you override it by associating a sub-iteration to a different release. Ideally an iteration is associated to only one release.

In some cases, a release is derived from a previous release; for example, release 1.1 of a product is derived from release 1.0. As of ELM 7.0.2, you can explicitly define this type of predecessor relationship between releases, as described in more detail in the Jazz.net article Work item linking in a global configuration context: Evolving global configuration and release relationships over time (coming soon).

Specifying which work item attribute indicates the release

Work items relate to releases based on attributes that either:

• Explicitly specify a release with a type of Deliverable, like the Found in attribute, or
• Specify an iteration on the timeline from which the system can determine an associated release, like the Planned for
attribute.

You can also define custom attributes of type Deliverable that specify the release.

In EWM project area management, the OSLC Link/Attribute Mapping page defines which work item attribute indicates the release value for each of the different OSLC link types.

In 7.0.2, when you work in EWM, links from work items to versioned artifacts in DOORS Next, ETM, and RMM resolve purely based on the configuration the user has set in the configuration context menu. When you work in DOORS Next, ETM, or RMM, work item links display and resolve based on the work item’s associated release as determined by the attribute specified in the mappings, and the releases linked to the current global configuration the user has set in that application. See How the global configuration, release, and attribute mappings work together for further details.

A work item can have more than one attribute that points to a release, and in some cases, those attributes can point to different release values. For example, a defect might be Found in one release, but Planned for delivery in a different release. The system determines which attribute to use based on the type of link.

By default, link types typically related to defects (such as Blocks Test Execution) use the Found In attribute which specifies a release; for link types typically related to planning (such as Implements Requirement), the system derives the release value from the Planned For attribute, which specifies an iteration. You can change these settings, and also define and use custom attributes if appropriate.

Linking EWM releases and global configurations

From a global configuration perspective, the EWM releases deliver the implementation or capture the work items for the solution represented by that global configuration. A hierarchical global configuration might relate to multiple releases from the same or different EWM project areas, comprising a broad solution. Conversely, multiple global configurations might link to the same Release, for example, where the development team is implementing multiple variants as a combined effort, or where you have multiple streams representing different development teams, or different approval stages for the same release.

As of 7.0.2, the GCM application stores links between global configurations and EWM releases, using the Release link type. This is a key difference from earlier releases, where EWM stored the release links to global configurations. (Note: For information on releases earlier than 7.0.2, refer to the Jazz.net article Configuring Rational Team Concert to establish a global configuration context for work item links.)

For your global streams and baselines, add links to one or more releases that deliver the implementation for that solution. Because the system uses these associations to resolve links between versioned artifacts and work items, ensure the relationship is reflected at appropriate levels in the hierarchy; for example, if a team works at both the top level of a global configuration hierarchy and in a component-level or team-specific global configuration, include the release link at both levels to ensure work item links resolve consistently in both contexts.

When you derive new global stream or baseline configurations from an existing configuration, including personal streams, the system initializes the same release links in the derived configurations; you can modify those release links if appropriate without impacting the original configuration. Changes made to the release links for the original configuration are not cascaded to existing derived configurations; you must manually update any existing configurations. For a more complete discussion on maintaining configuration-release links over time, see the Jazz.net article Work item linking in a global configuration context: Evolving global configuration and release relationships over time (coming soon).

Indicating the release for a work item

Users set the work item attributes to indicate to which release or releases the work item pertains. Changing the value of the attribute changes the work item’s release association.

---

How the global configuration, release, and attribute mappings work together

When you set the configuration context in any ELM application, the system attempts to resolve both incoming and outgoing links using that context. For work item links, resolution differs slightly depending whether you are starting from the work item in EWM or from the versioned artifact in another ELM application. (Remember that all links involving work items are stored in EWM as outgoing links and are considering incoming links in the other ELM applications.)

In EWM, when you set a global configuration context, the system uses that context to resolve outgoing links. If a version of the target artifact exists in that configuration context, the link displays correctly and you can preview and navigate to the linked artifact; if there is no version of the artifact in that context, the system might or might not display the link text, and cannot preview or navigate to the artifact. When navigating links from EWM, the system does not use the work item’s release or the link type/attribute mapping settings. This is a key difference from releases prior to 7.0.2, where EWM did not provide a configuration context banner, and the system relied on the release and link/attribute mappings.

When resolving a work item link in DOORS Next, ETM, or Rhapsody Model Manager (RMM), the system:

1. Checks the current global configuration context to see what releases it links to, including any direct or indirect predecessor releases (see the Jazz.net article Work item linking in a global configuration context: Evolving global configuration and release relationships over time (coming soon) for details on predecessor releases).
2. For the OSLC link type used, checks the link type/attribute mappings in EWM to determine which work item attribute specifies the release value.
3. Uses the work item attribute to get the work item’s release association.
4. Determines whether the release is one of those linked to the global configuration.
5. If the release is linked to the global configuration, the system displays the work item link. If not, the incoming link is not displayed. The exception: if the work item is not associated to any release, the system always displays the incoming link.

In the following example for an “Affects Requirement/Affected by” link in DOORS Next, the system checks the ADAS Basic global configuration for its Release links (1). The mappings for this link type point to the Planned For attribute (2), which for this work item is Sprint 1.3 (3). That sprint is part of the iterations defined for Release P1, which is one of the Releases linked to ADAS Basic (4). The system therefore displays the incoming link (5).

For more details on creating and navigating links between work items and versioned artifacts and how the system uses the settings described above to resolve those links, please see the Jazz.net article Work item linking in a global configuration context: Creating and navigating links (coming soon).

Best practices and additional considerations

In addition to the guidance provided here, ensure you read the other articles in this series and additional references listed under For more information to understand the system capabilities and how best to leverage them in your ELM environment.

• • Set expectations for your users on how work item linking behaves in the context of global configurations. Ensure users know what attributes determine the release for a work item and the association to the type of link they might be creating.
  • Remember that link resolution and navigation from EWM depends only on the global configuration context; it does not consider the work item release. Educate your users on the correct configurations to use for your environment.
  • For global configurations with a hierarchy of contributions, add release links at appropriate levels of the hierarchy. Release links for one global configuration do not apply automatically to other global configurations in the hierarchy. For example, given the example below, a release link for Aviary Base does not apply to its contributions; work item links would resolve in the Aviary Base configuration context, but not in the Hummingbird Base, Avionics Base, or other contexts, unless you also linked the release to those global configurations as well. Consider what configuration contexts users will work in, and ensure appropriate releases are linked to each global configuration.

• • Because you can link the same EWM release to multiple global configurations, and a global configuration to multiple releases, a given work item relationship could resolve in multiple configuration contexts, leading to ambiguity about which contexts are “valid”. Associating iterations in the EWM timeline to multiple releases can increase the potential contexts. Where possible, map any given iteration on the EWM timeline to a single release, ensure appropriate links between global configurations and releases, and that users understand the configuration contexts and releases that pertain to their work.
  • When a global configuration links to multiple EWM releases, there is no “preferred” release and no particular ordering of linked releases. There is also no particular relationship between the ordering of releases shown in GCM and that in EWM. This is most relevant when a DOORS Next, ETM, or RMM user creates a link to a new work item, where the system automatically sets the work item’s release attribute. In that scenario, the system determines all releases linked to the current global configuration and of those, uses the release shown lowest in the list on the EWM Admin page to populate the work item attribute value in the creation dialog. The user can always change the attribute value before clicking OK to create the work item and link.
  • Report Builder normally includes work items in all configuration scopes. To reflect work item filtering in reports, set the Exclude work item relationships with incompatible releases option in the Trace Relationships section in Report Builder. Set this option in each report where you want to filter the links. If you don’t set this option in a report, Report Builder does not consider configuration context when displaying work item links; this is consistent with report behavior in earlier ELM releases.

• If you don’t want to filter work item links based on global configuration context, you can choose an alternative mode where a link from a work item to an artifact in one global configuration displays and resolves in any global configuration that includes any version of that artifact. To remove the filtering, edit the server Advanced Properties for DNG, ETM, and RMM to set Exclude work item relationships with incompatible releases to false (the default setting is true to enable filtering). Ensure you set this option consistently in all ELM applications and in your reports; if you set the application options to false, you would not set the reporting option. You must still enable EWM to link to versioned artifacts and set the configuration context in EWM to navigate links.

For more information

For additional information on linking between work items and versioned artifacts, see the following resources, including other articles in this series:

• Enabling linking of work items to versioned artifacts in IBM Documentation (formerly the Knowledge Center)
• Work item linking in a global configuration context: Creating and navigating links (coming soon)
• Work item linking in a global configuration context: Migrating from releases before 7.0.2 (coming soon)
• Work item linking in a global configuration context: Reporting (coming soon)
• Work item linking in a global configuration context: Evolving global configuration and release relationships over time (coming soon)
• For ELM versions prior to 7.0.2: Configuring Rational Team Concert to establish a global configuration context for work item links

---

About the authors

Nick Crossley is a Senior Technical Staff Member at Persistent, responsible for the architecture of global configuration management, product line engineering, and version and variant management in the IBM ELM solution. Nick leads the OSLC standardization work on Configuration Management, and has over 40 years of experience with software tools and development. Nick can be contacted at nick_crossley@us.ibm.com.

Kathryn Fryer is a Senior Solution Architect with Persistent Systems, focused on the IBM Engineering Lifecycle Management solution, particularly around global configuration management. She previously held a similar position at IBM, where she spent 30 years in software development, management, and user experience roles.  Kathryn works closely with clients and client-facing teams in pre-sales, enablement, and consulting.  She can be contacted at kathryn_fryer@persistent.com.

© Copyright IBM Corporation 2021