Managing Collaboration Links

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:

  1. Locate and click the More button in the Operations bar area.
  2. Locate and click the Link option in the opened menu.
  3. In the Link dialog, select the Collaboration Link option in the left panel.
  4. In the right panel [1], select the Link Type you want to create [2]; 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.
  5. A new Project combo will be displayed with the associated remote projects to select [3].
  6. As soon as you select the project, a pop-up window will appear [4]. If you hadn't previously started a OSLC Remote Application session in the same browser, the new window will show you the OSLC Remote Application login page and you must continue with this step, otherwise please go to the next one [5]. The login page is here to complete the user authentication process, please provide valid user credentials, it is not necessary that such user has an admin role [5].
  7. What happens after the user authentication process (or if you had already started a session in other browser's tab) depends on whether Jira consumer was configured as trusted or not on the OSLC Remote Application. If it was configured as trusted, the only thing you need to do is to ignore a blank page that will be displayed for a few milliseconds, and then you can go to the next step; otherwise, you will see the 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 [6]. Authorize the access and then close the pop-up window when indicated if it is not closed automatically.
  8. Back on the Link dialog, three new radio buttons may exist [7], [8]:Choose the radio button that better fits your needs [3] so the control next to it got enabled and filled with available remote artifact types to create the link to.
  9. Change the remote artifact type from the enabled control if suitable [9].
  10. Click either on the Select artifact, Fill form or the Open dropping dialog button depending on your radio button selection.
  11. For the first two radio cases, a new dialog will be displayed with the OSLC Remote Application content to allow you either select or create an artifact to link to [10], [11]. Complete the remote form and confirm this action by pressing the OK button. If you chose the Drop existing radio, 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 Link button [12]. 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 Cancel button 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 [13]. 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 [14]. 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:

  1. In the Issue Links area, choose the specific link you want to remove.
  2. Click on the cross icon displayed at the end of the link row [15].
  3. On the confirmation dialog, click the 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.

[1] An error is displayed here if the license is not valid or if the project has no remote associations. [2] Selection will be automatic if a default link type is set at server configuration, a link of the given type was already created or there is only one link type available. [3] If only one element is available, it will be chosen automatically. [4] It may be the case that your browser prevented the opening of the pop-up window. Some browsers notify this with a message in a top bar, others are more discrete and just show a little red icon at the end of the addresses bar; in any case, all of them allow you to authorize pop-up windows, typically by clicking on the area where they showed you the blocking notification and choosing the option to allow pop-up windows. Please follow the corresponding procedure of your browser to allow them and then continue. [5] The available dialogs and artifacts to select/create on the next step will depend directly on the privileges of the logged OSLC Remote Application user. [6] This confirmation will be asked, only the first time a collaboration is needed for untrusted consumers, in each Jira session. [7] The availability of these radio buttons depend on the chosen Link Type and the OSLC Remote Application behind the chosen Project. In the particular case of the "Drop existing" dialog, it is available only for these applications: IBM Engineering Requirements Management DOORS Family, IBM Engineering Requirements Management DOORS Next, IBM Engineering Workflow Management, IBM Rhapsody Model Manager and Atlassian Jira. [8] If instead of seeing radio buttons you see an error message regarding Global Configurations, please refer to subsection ahead: Global Configurations Compatibility. [9] The artifact type control next to the chosen radio button will always be preselected with a default option as long as it contains at least one. [10] If you only got a blank page, contact your administrator. [11] If remote content is too large and you cannot see all options because they were shortened you can maximize this dialog by pressing the rectangle icon at the top-right corner. [12] For a detailed description on how to use the dropping dialog and its validations, please refer to the Using the Dropping dialog topic. [13] There may be more than one problem if user selects/drops more than one artifact to link to, and if some of them are success, they will be also displayed here after all errors. [14] Optionally, user can remove individual errors by hovering them and pressing the cross icon at their right. Dialog will be closed when no more errors are left. [15] If you are trying to remove a Collaboration Link without having started a session with the OSLC Remote Application, you will be prompted to perform the user authentication/authorization process.

Global Configurations Compatibility

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:

  1. A mapping from Collaboration Link types to Jira's Versioned fields: Affects Version/s and Fix Version/s.
  2. A mapping from Jira's Project Versions to IBM Engineering Lifecycle Management Global Configurations.

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:

  1. Depending on the Collaboration Link type you want to create, and the first mapping listed above, the Jira Versioned field of interest is determined.
  2. The value of the Versioned field of interest (either the 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.

IBM Engineering Requirements Management DOORS Family 9.7.2
Starting with DOORS Family 9.7.2 version, modules can work in the context of a Global Configuration. As for ELM applications, linking is possible only if both Jira and DOORS use the same global configuration context or none of them is using such context. Using a global configuration enables you to create unidirectional links from Jira issues to DOORS modules' baselines. Note however that creating links from Jira to a GC enabled DOORS module won't create the backlink from the module to Jira, this is a DOORS known limitation.

[1] If you forget to set this value, you will get the step 8 error message mentioned above. [2] Please refer to the Using the Dropping dialog topic for details. [3] Which can be customized by the Jira project administrator.