Using Global Configurations With Jira
The objective with configurations with Jira is to provide a method to support the natural identification of the correct workflow object (Jira issue) from a versioned asset (e.g., DNG Requirement) and the right versioned asset from a workflow object. You should read the Introduction to Configurations and Global Configurations before you dive further into this article.
Jira’s Natural Versioning
Jira (and other change tools) have a natural way for users to reference a version. This natural method of doing versioning in Jira is a release. A release identifies an event for which a specific instance of an artifact is delivered.
It serves as both a container of defining work for a future release and identifying contents and work for a past release. These names most often are associated with a specific build or deliverable of the team in Jira.
The value of this is that users in Jira now have a common way to identify both works for the future and references to artifacts in the past.
You can see this, for example, on a defect in Jira.
This scenario details that this defect was present in the 1.0 Release (past), and it is planned to be fixed in the 1.1.0 Release (future).
This means that when referencing assets (which is what we do in links), we should use a different relative version for different links. For example, an “Implements Requirement” link would be pointing to an artifact that our Fix Version targets. And an “Affects Requirement” link would be pointing to an earlier set of requirements identified by the Affects Version release. This is the basic natural intention of versioning with Jira; although there are some complexities, we will address them later.
Implied in this behavior is that when a user updates a release identification, it updates all of the links. For example, the common need to move a story to a different release (pull ahead or push out later) should always reference the release's current set of requirements.
Mapping Jira Releases to a Configuration
There needs to be an alignment between the Releases in Jira and the Configurations in the OSLC Asset Domains to unify the configurations across the workflow and asset domain. Since both are conceptually similar, a simple mapping solution from Jira to OSLC Configurations makes the most logical sense. For example:
In this scenario, we have the logical mapping of Release in Jira to configurations in our OSLC Domain. The selection of which configuration relates to a Jira release is fully under your configuration team's control. It is also a situation where you can have Releases with no configuration (which will mean they can’t link to any assets) or multiple releases that use the same configuration (for example, future releases all pointing to the same tip of the configurations intended to be used.
These configuration mappings are used when linking and navigating links from Jira.
When Creating Links
When creating a link, Jira will utilize this configuration mapping. So considering a Jira issue with the Fix Version set to Release 1.1.0.
When launching a new link dialog, you will see something similar to the following:
This indicates for the Implements Requirement link; we are going to use the AMR 1.1.0 Configuration. And if we want to know why we can click on the 
to the right to see the details.
The idea is that your team can map the configurations that make the most sense to your team. When the links already exist, you can see the configuration used directly on the link, as is the following.
And if we changed the Fix Version to Release 1.0
If we review the link, we will see the GC and the Requirement details change configurations due to the Mapping.
We have a precise determination of version information for a link with this mapping. We will always navigate to the correct version of the artifact.
If a user deletes the version field for your link, as we see below:
The system is aware and will flag these details so that the engineer can resolve them. It still retains the link but identifies that the Jira Issue version is incomplete for deterministic navigation.
Link Type to Version Field Mapping
Now, this is an example with the 'implements requirement' link type. Each link type has a unique mapping to the version field that is used in configuration resolution. Most teams use the default settings, but you can modify these relationships in the project configuration.
The “Fix Version/s” relates to future dynamic artifacts that will be used while working on the issue, while “Affects Version/s” relates to past artifacts in previous releases. This is why you will observe many test-related relationships use the “Affects Version/s” field since they identify the source of the issue later identified.
Using multiple releases in Jira
While it is desirable to have a process where a single version is utilized in a field, there is no such restriction. This is most common for the “Affects Version/s” field where we may introduce multiple versions where we see an issue.
Under these situations, it is important to remain deterministic. Our navigation and previews will always be precise and return the value of a single version of the artifact. This is visible on the GC hint.
When multiple Releases are selected in a version field, the product will always select a priority order defined in the project's Release configuration. Users can reprioritize by reordering.
This will be hinted at by the saved value of the version filed where the priority item is shown last.
With this information, you can successfully leverage the multiple releases' usage while still having control and determinism on configuration context.
Mapping Jira to Configuration Summary
The Jira to Configuration mapping is targeted to be simple and deterministic. The intention is that a given release identifies with a specific version of assets (stream or baseline) and provides simplicity and precision to users. It should be as direct and intuitive as possible for a user to preview or navigate assets and understand the version relationship.
Mapping Configurations to Jira Release
The inverse relationship of mapping OSLC Configurations to Releases is also done to provide visibility to Jira Issues in the asset management tools. The basics need of the capability in the GC domain is to point a configuration to a release. However, the ELM versions do this process uniquely, as described below.
Single Configuration Mapping (ELM pre-7.0.2)
The behavior before 7.0.2 was that a release mapped to a single configuration. And inversely, that mapped configuration was the only place where the Issues participated in. Effectively, the GC would discover what Release was relevant to that configuration. The definition of the mapping is only captured in Jira.
This resulted in the behavior of a 1:1 configuration mapping where a Release in Jira was mapped to a single GC. The GC resources would then discover the participating Release to find artifacts.
There can be more explanation and guidance in a blog we delivered in 2020 → https://www.sodiuswillert.com/en/blog/recommendations-on-using-changes-with-configurations-in-doors-next.
This enables a simple and direct mapping in Jira, as seen below.
This solution is effective and provides a deterministic configuration for users. What was challenging to users were the items noted in the blog; inability to use in personal streams and inability to leverage in hierarchical streams.
Multiple Configuration Mapping (ELM 7.0.2+)
In version 7.0.2, a change is created that each GC can select what Release is linked to a GC. The result is the freedom to include a Release in multiple configurations. This addresses several of the issues of visibility noted in the blog but now creates a web of mapped relationships, as demonstrated below.
This new experience means some new behaviors to manage the relationships.
New Behaviors in ELM 7.0.2
Create Additional Relationships
From within the GC Application, you can Add any Release into any stream to make those related Jira issues available in any view. This gives the team flexibility in any process to make their workflows best for them.
And you can find new releases from Jira.
Release Relationships Kept in Streams during Cloning Events
One of the valued features is that in cloning events for streams (created streams, personal streams) derived from another stream, the Release mapping is maintained. This makes sure the personal streams remain similar to the stream they just cloned in their Issue content.
New Behaviors in OSLC Connect for Jira 2.6.0
Consistency Management in Jira
To remain consistent with GCs, we can detect and synchronize the GC to Release mapping from within Jira. When reviewing the GC mapping in Jira, you can detect whether the mapping you have created also has a mapping from that GC into your current release. Having bidirectional mapping is valuable to enable navigation two and from the same artifacts and is highly recommended.
With these supports, you can manage your GC mappings directly from Jira and push the configurations into IBM GC. The below dialog shows that a change has occurred in the GC app, so the Jira backlink to the Release is no longer present and should be synchronized.
Cautions and Recommended Practices
While we believe that visibility in multiple configurations in releases can be appealing, it should be used cautiously. Here are our recommended practices and cautions.
Recommended Practices
We recommend that you discuss common configuration management practices. This includes a primary Release concept to GC mapping where you are planning to be editing relationships (the mapping initiated from Jira) and secondary mappings (mappings initiated from GC) where you are only interested in visibility.
Manage mapping from within Jira as the Primary as this solidifies what Jira Users want to see in ELM
Ensure that the Jira Mappings are Synchronized to ELM; otherwise, ELM and Jira users will see different artifacts.
Identify the common practices where changes are encouraged by the team as it leads to more consistent linking practices and contexts. (Are you ELM or Jira dominant for the link source?)
Identify whether your GCs should include releases in the entire Hierarchies.
Identify common Release naming practices that align with common GC naming practices.
Ensure that Release is visible on all artifact Rich Previews to ease detection of mismatch
Discourage deleting of Issue Links from ELM (see cautions)
Jira Project Admins should have GC Link Addition Permissions (otherwise, they can’t synchronize the mappings with GC
Cautions
The cautions are important facets we have identified that should be in your process development practices.
Removing Jira links in your stream deletes from all streams, so be cautious and aware.
Links are stored on the Jira artifact and discovered by ELM.
Making mappings from GC to Jira can cause inconsistent mappings.
Bidirectional supports from Jira are encouraged.
Guidance on stream maintenance and review should be for all users.
Especially on the review of what Release are visible in my stream
Be cautious on crossing releases in your streams.
Adding multiple releases from the same project or releases from different Jira projects may not be visible in main ELM views.
Never map to personal streams from Jira.
Personal streams should only be local changes and should never be the primary release stream.
Mapping Conclusions
We encourage both discovery and definition when working with configurations and releases. An initial discovery phase will demonstrate the power and critical capabilities enabled by these tools. The process is necessary to ensure that teams will apply the tools consistently with predictable results and behaviors. If there are questions or needs to review your practice, we are available to discuss.