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 CLM 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, select the Link Type you want to create [1], [2], [3].
  5. A new Project combo will be displayed with the available remote projects to select [2], [3].
  6. As soon as you select the project, a pop-up window will appear [4]. If you hadn't previously started a CLM Application session in the same browser, the new window will show you the CLM 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 CLM 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 CLM 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, two new radio buttons may exist [7], [8]:Choose the radio button that better fits your needs [3] so the combo 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 combo if required [9].
  10. Click either on the Select artifact or the Fill form button depending on your radio button selection.
  11. A new dialog will be displayed with the CLM Application content to allow you either select or create an artifact to link to [10], [11]. Complete the remote form for the selection or creation and confirm this action by pressing the OK button.

If everything went as planned, the dialog will be closed and you will see the new link created on the Issue Links area. If, on the other hand, you see the Failed to add the back link(s) dialog, please contact your administrator in order to check the communication with the CLM Application, or any other issue before continuing. At this point, the safest is to click on the Cancel button and wait for a resolution.

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 [12].
  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 CLM 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] You will see an error message here if the license is not configured properly or if there are no associations defined for the current project. [2] Available elements will depend on the associations defined for the project to which this issue belongs to. [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 CLM 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 CLM Application behind the chosen Project. [8] If instead of seeing radios button you see an error message regarding Global Configurations, please refer to subsection ahead: Global Configurations Compatibility. [9] The artifact type combo next to the chosen radio button will always be preselected with a default option as long as it contain 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] If you are trying to remove a Collaboration Link without having started a session with the CLM Application, you will be prompted to perform the user authentication/authorization process.

Global Configurations Compatibility

Collaboration Links cannot be created if the CLM Application has 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 CLM Global Configurations.

Having these two mappings, OSLC Connect for Jira is able to resolve the Global Configuration (GC) it needs to provide to the remote selection/creation dialog. 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, there's one remaining thing to discuss, 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 [2] (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.

Finally, you must know you do not need to worry about CLM Applications with Configuration Management NOT enabled when your project has been configured to be compatible with GC's. In this case, although Jira sends a GC to the remote dialog, it will just ignore such information and will behave as usual.

[1] If you forget to set this value, you will get the step 8 error message mentioned above. [2] Which can be customized by the Jira project administrator.