As you may know, a Jira issue can have links to other issues or external web pages. Once OSLC Connect for Jira is installed and configured, you will be able to create another kind of links: Collaboration Links. These links relate the issue with ALM applications artifacts, notably OSLC Remote Application artifacts. The relationship type is set by the Collaboration Link type and the available ones depend on the remote artifacts types wanting to link.
All Collaboration Link types allow linking issues to remote existing artifacts, but only some of them allow the creation of remote artifacts while linking. Processes are basically the same, so both are described next:
Morebutton in the
Linkoption in the opened menu.
Linkdialog, select the
Collaboration Linkoption in the left panel.
Link Typeyou want to create ; available types depend on the remote project associations configured and the enabled link types set at the server configuration. Ask to an administrator about these configurations in case your wanted link type is missing.
Projectcombo will be displayed with the associated remote projects to select .
Authorize Applicationpage which is the last confirmation to allow Jira accessing the OSLC Remote Application information on behalf of the user you used to login . Authorize the access and then close the pop-up window when indicated if it is not closed automatically.
Linkdialog, three new radio buttons may exist , :
Link to existing- allows linking the issue to an existing artifact.
Create new- allows to create a new artifact before linking to it.
Drop existing- allows to drag and drop existing artifacts to be linked with the issue.
Fill formor the
Open dropping dialogbutton depending on your radio button selection.
OKbutton. If you chose the
Drop existingradio, a new Jira dialog will be displayed with a dropping area, drag and drop there the remote artifact you want to link to and if it is successfully validated, click on the
Linkbutton . Note: all dialogs title will summarize the current linking operation with following pattern: <issue-key> is <linking_artifact> of <remote_project>, e.g.
PROJECT-4 implements requirement of "My Project (Requirements)"and user can always press the
Cancelbutton to go back and rectify link type and/or target project in previous dialog, if necessary.
If everything went as planned, both the selection/creation/dropping dialog and the
Link dialog will be closed and you will see the new link created on 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 . At this point, user is able to retry
the linking of all failed links either one by one (by pressing the
Retry link 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 . When problem is due to a remote server constraint, error message will include the legend
Remote server says 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 back link from the OSLC Remote Application to
Jira and this breaks 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. There is no way to update a Collaboration Link, if you chose the wrong artifact, you will have to remove the Collaboration Link and then create it again correctly. To remove a Collaboration Link:
Issue Linksarea, choose the specific link you want to remove.
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 an IBM Engineering Lifecycle Management application (having 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). In order to be compatible, Jira project administrator needs to make sure two mappings have been defined:
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
Project field (in step 8 above) in a dedicated field named
Configuration. The GC resolution process is:
Fix Version/sfield) 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 
(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:
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
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.