Creating a Related Issue Panel

We will begin by creating a Related Issue Panel to display related stories. The related stories are those that have the same Epic Parent i.e. the same Epic Link. For example, if we have Epic 1, and it contains 10 stories, then within each Story issue view, we will be able to see a panel containing links to the other 9 stories that have the same Epic parent.

1. Navigate to the Apps administration screen.

2. Select Show Related Issues under the Apps section. Click Allow Access if this is your first time configuring the app. On the next page, review the permissions and click on Accept.

3. The Related Issues Panel configuration page will display all the Related Issues Panels.

4. Click the “+ New Panel” button.

5. Provide a Name for your Related Issues Panel e.g. Related Stories.

6. Select the Projects where this panel should appear. Then select the relevant issue types where the panel will appear. In this case we will be selecting Story.

7. Select the fields you wish to display in the panel.

8. In the JQL field insert

   CODE

   issuetype = Story and "Epic Link" = ${issue.fields.parent.key} and issuekey != ${issue.key}. 
   
   Note: ${issue} is the current issue where the panel is being displayed. 
   

9. Click Save and then Confirm.

10. Navigate to a Story that belongs to an Epic containing several other stories.

11. Click the Issue Panel button.

12. The Related Issues Panel should appear and display the other stories from the same Epic.

Using the ${issue} syntax

The ${issue} specifier allow us to reference the issue context for the current issue i.e. the issue that is being displayed by the user in the issue view screen. The ${issue} contains the JSON formatted issue data as returned by the Jira Cloud REST API.

An easy way to see this is to use the following URL in your browser

https://<yoursite>.atlassian.net/rest/api/3/issue/<your issue key>

where you must replace <yoursite> with the name of your Atlassian cloud site, and <your issue key> with a valid issue key in Jira. If successful, this will return the JSON structure for the issue. You can use this to determine the values that should be used to access the fields of your issue.

Here are some examples:

Priority: ${issue.fields.priority.name}

Status: ${issue.fields.status.name}

Custom Field (Text): ${issue.fields.customfield_xxxxx} where customfield_xxxxx should be replace by your customfield identifier e.g. customfield_12345.

Custom Field (Select): ${issue.fields.customfield_xxxxx.value}

Using the $issueLinks macro value

We can also reference the collection of linked issues in the current issue by using the value $issueLinks in out JQL query in the configuration of the panel.

For example, if you wanted to display all issues linked to issues which are in turn linked to the current issue you could use

linkedIssue in ($issueLinks)