Linking issues with catalog objects is a great chance to enrich issue with some information. The Catalog app provides the combination of custom fields and a web-panel with all those fields with expanded functionality of managing objects. The field and the web-panel are synchronized in both ways, all changes are performed by the app technical user.

Since Catalog needs to perform some actions within issues (update a relevant field by changing the value within the web-section), it must have the following project permissions:

  • Browse projects
  • Edit issues

Ensure the Catalog technical user (as a single user or as an atlassian-addons-project-access project role) has these rights in the projects. By default, the role corresponding to apps has all project permissions. Those permissions are granted to apps by default.

Read more: Add-on permissions update (Atlassian blog)

Setting up selectors

Navigate to Catalog configuration → Issue Fields section and add a new field specifying its name and the directory the field should provide a selection from.

The Catalog web-panel in issues will contain this field with the ability to access and manage objects there. Also, the synchronized custom field will be automatically added to the list of custom fields. This field should not necessarily be added to screens, it will be updated by the app by any changes in the relevant field of the web-panel.

However, you might need to add the field on screens, such as create or transition screen since the web-panel is only available on the view screen.

Restricting fields to projects

You can easily hide the custom field by not displaying it on the issue screens. As for the web-section, you can manage its content by specifying in which projects a particular field should be displayed. Leave empty to display the field within the web-section in all projects.

Displaying Linked Issues

There is a Linked Issues attribute that can be added to the object template to display the issues linked to the object and navigate to them quickly and simply.

Linked issues are not displayed automatically in the entries since it's not always necessary. For example, you use a Catalog directory as a simple list of references. You always can find issues linked to a particular Catalog entry via Issue Navigator.

However, sometimes it might be convenient to see the linked issues (or some of them) right within an entry.

Just add a Linked Issues attribute while setting up your directory. Set the additional filters if required. The following are several examples of displaying linked issues in Catalog.

Examples of use

Case 1. We have a Services directory and allow our Service Desk customers to select a service from the list of available ones. We'd like to know instantly how many unresolved issues there are for a particular service.

  • Add a Catalog custom field and put it on screens of the relevant project. Name it Service.
  • Add a Linked Issues attribute to the Services directory and set the additional JQL-filter: resolution is EMPTY. Name it Open Service Requests.

Case 2. We manage the workflow of a book exchange and need to specify the book to give and a book to take in each issue. We'd like to know which books were taken mostly.

  • Add a Catalog custom field, set up a selection from the Books directory and call it Book to give.
  • Add a Catalog custom field, set up a selection from the Books directory and call it Book to take.
  • Add a Linked Issues attribute to the Books directory and specify Linked via field(s) = Book to take.