Managing Collaboration Links

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.

Creating a Collaboration Link.

  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], you can start dropping artifacts or select the Link Type you want to create [2], [3].
    Select a link type and continue with the following steps, only if you want to select (or create, if possible) a remote artifact to link with. If instead, you drop an artifact, you can skip the remaining steps as the Collaboration Link dialog is changed for the Dropping dialog. Address any linking-preventing error there, with the aid of the Using the Dropping dialog topic, before continuing.
  5. A new Container combo will be displayed with the associated remote projects/containers to select [4].
  6. As soon as you select the container, a pop-up window will appear [5]. 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 [6]. 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 [6].
  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 [7]. Authorize the access and then close the pop-up window when indicated if it is not closed automatically.
  8. Back on the Link dialog, two new radio buttons may exist [8], [9]:Choose the radio button that better fits your needs [4] 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 [10].
  10. Click either on the Select artifact or Fill form button depending on your radio button selection.
  11. A new dialog will be displayed, with the OSLC Remote Application content, to allow you either select or create an artifact to link to [11], [12]. Complete the remote form and confirm this action by pressing the 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].

Removing 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 [16].
  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.

Updating a Collaboration Link.

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.

[1] An error is displayed here if the license is not valid or if the project has no remote associations. [2] Link type selection is 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] Do not forget that available link types depend on the configuration done at administration level. So if the required link type is missing, please ask help from a project or system administrator. [4] If only one element is available, it will be chosen automatically. [5] 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. [6] 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. [7] This confirmation will be asked, only the first time a collaboration is needed for untrusted consumers, in each Jira session. [8] The availability of these radio buttons depend on the chosen Link Type and the OSLC Remote Application behind the chosen Project. [9] If instead of seeing radio buttons you see an error message regarding Global Configurations, please refer to the subsection ahead: Global Configurations Compatibility. [10] 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. [11] If you only got a blank page, contact your administrator. [12] 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. [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 pressing the Discard button. Dialog will be closed when no more errors are left. [15] This will open the Dropping dialog, from where linking can be continued, if no linking-preventing errors exists. [16] 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 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:

  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 Container field when it is resolved according to the following procedure:

  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.