Out of the box, a Jira issue can have links to other issues or external web pages. Once OSLC Connect for Jira is installed and configured, another kind of link can be created: Collaboration Links. These links relate the issue with ALM applications' artifacts (the OSLC Remote Application artifacts). The link relationship is determined by the Collaboration Link type, and available link types are determined by configurations done at server and project level administration.
Available Collaboration Link types can be created, from an issue to an existing remote artifact, by either selecting or dragging/dropping it. When selection option is chosen, a dialog is open to allow the user search and select the remote artifact to link with. Often, the user may have searched the artifact in another browser's tab (hosting the OSLC Remote Application) and it would be easier to just drag and drop the artifact from one application to the other. In these cases, the user just needs to be sure what are the dragging and dropping areas on each application, but since dragging areas change from one OSLC Remote Application to the other, or simply do not exist in others, all these details have been split in the Using the Dropping dialog topic.
Also often, the user may want to link an issue with a remote artifact that needs to be created first. In these cases, but not for all Collaboration Link types, it is possible to open a dialog to remotely create the artifact needed, just before linking the issue with it in a single step. This saves the user from having to switch from Jira to the OSLC Remote Application, just to create the artifact before creating the link.
More
button in the Operations
bar area.Link
option in the opened menu.Link
dialog, select the Collaboration Link
option in the left panel.Link Type
you want to create [2], [3].Container
combo will be displayed with the associated remote projects/containers to select [4].Authorize Application
page which is the last confirmation to allow Jira
accessing the OSLC Remote Application information on behalf of the user you used to login [7].
Authorize the access and then close the pop-up window when indicated if it is not closed automatically.Link
dialog, two new radio buttons may exist [8], [9]:Link to existing
- allows linking the issue to an existing artifact.Create new
- allows to create a new artifact before linking to it.Select artifact
or Fill form
button depending on your radio button selection.OK
button. Note: all dialogs' title will summarize the current linking operation with following pattern: <issue-key> is <linking_artifact> of <remote_containert>,
e.g. PROJECT-4 implements requirement of "My Project (Requirements)"
and user can always press the Cancel
button to go back and rectify link type and/or target project in previous dialog, if necessary.If everything went as planned, the selection/creation/dropping dialog and the Link
dialog will be closed, then the created link will be visible in the Issue Links
area.
If, on the other hand, there is a constraint or failure with the linking, the Link
dialog will remain open and will report all problems found [13]. At this point, user is able to retry
the linking of all failed links either one by one (by pressing the Retry
button on an specific error entry) or all at once (by pressing the Retry all failed artifacts
link at the bottom of results table
- only visible when there are more than one error). If problem persists after retry some linking, and it is not due to a remote server constraint, the safest is to click on the Close
button, notify problem(s) to the administrator
and wait for a resolution [14]. When problem is due to a remote server constraint, the remote message is quoted in gray text and the extra option Save locally
will be available for that individual link.
In this case, check whether what remote server says can be solved either by you or some administrator (problem could be remotely or locally originated) and retry the linking after that, otherwise proceed as before because saving a link locally is not recommended;
doing so implies to create only the link from Jira, to the OSLC Remote Application, but without creating the link backward and breaking traceability.
Once a single issue link is created (not necessarily a Collaboration Link), you will be able to start the Link
dialog, from the Issue Links
section, by pressing on the plus icon
located at the top-right corner of the section. If the link created is a Collaboration Link, you can create more links of the same type, by dragging and dropping remote artifacts on the Collaboration Link type section [15].
Issue Links
area, choose the specific link you want to remove.Delete
button.If everything went ok, the dialog will be closed, the link is removed from the system, and it will no longer appear in the Issue Links
area.
If, on the other hand, you see the Failed to remove the back link
dialog, please contact your administrator in order to check the communication with the OSLC Remote Application,
or any other issue before continuing. At this point, the safest is to click on the Cancel
button and wait for a resolution.
Collaboration Links cannot be created if the OSLC Remote Application is Configuration Management enabled, and the Jira project has not been configured to be compatible with Global Configurations (you will get an error during the step 8 in the above procedure or in the Dropping dialog). In order to be compatible, Jira project administrator needs to make sure two mappings have been defined:
Affects Version/s
and Fix Version/s
.Having these two mappings, OSLC Connect for Jira is able to resolve the Global Configuration (GC) needed to work with the selection/creation/dropping dialog.
This GC is displayed below the Container
field when it is resolved according to the following procedure:
Affects Version/s
or Fix Version/s
field) is taken and used to resolve, given the second mapping listed above, the GC to use.Given this, following important points can be concluded:
Having said that, what GC would be resolved if multiple versions are assigned to the versioned field of interest? As you may know, Jira allow users
to set multiple versions on the Affects Version/s
and Fix Version/s
fields. When this happens, Jira keeps a chronological creation order of the versions [3]
(the latest created version comes first) and the first version (from the version field of interest) that can be resolved to a GC, following this order, is the one chosen. Let's say your project has three versions:
1.0
, 1.1
and 2.0
which were created in that order; let's say the versioned field of interest is Affects Version/s
and it turns the Jira issue
is a Bug that is affecting the three versions... so you put all them in the Affects Version/s
field. Now, let's say your project administrator have configured a GC for the first two versions but forgot to assign
one for 2.0
. In this scenario, the GC provided to the remote dialog will be the one associated with version 1.1
, this because it is the first one (in reverse chronological creation order) from the
versioned field that can be resolved to a GC. If all this GC resolution seems too complicated, you can see it live by clicking on the icon at the right of the Configuration
field. The tooltip of this icon is
Why is this configuration used?
.
Last but not least, what occurs when a Jira issue is set to work with a Global Configuration but also requires linking with artifacts of projects that don't? Answer depends on whether the other remote project is just Configuration Management disabled (e.g. IBM Engineering Requirements Management DOORS Next) or not compatible at all (e.g. IBM Engineering Requirements Management DOORS Family - up to 9.7.1 version). In first case, linking won't be possible, it's an IBM rule to not work mixing projects which are Configuration Management enabled and Configuration Management disabled. On second case, linking will be possible as the remote application just ignores the context information sent by Jira.