Custom Relationships for Jira Cloud
This app allows you to build your own customized relationships, defining:
How issues can be related
What types of issues can be in a relationship
How many relationships types are possible
How many levels deep you want a relationship
The name of the relationship
The name for each level of a relationship
The following are definitions used in this documentation. To make understanding easier the following diagram is referred to within those definitions
Node: A node is a point in a hierarchy. The diagram above has 6 nodes, including two top-level nodes.
Hierarchy: A hierarchy is a group of one or more nodes. In the above diagram, there are two hierarchies, one called Development and one called EST each containing three nodes
Custom Relationships offers two different ways to configure relationship hierarchies: globally (for all projects) and for particular projects. This section describes the global configuring of relation hierarchies.
The global configuration page can be navigated to by going to the administration tab Apps and then selecting Configuration under the Custom Relationships section. That will display the following page.
At the top right-hand side of the page is a purple circle, with a question mark in it. Clicking on this will show a popup guide on how to create a relationship hierarchy. On the last page of the popup is a button to create an example hierarchy (disabled and unsaved).
Creating your first Hierarchy
To start a new hierarchy click on the "New top level parent" button on the right-hand side of the page. This will open the following dialog.
At the top of the dialog is an optional field for entering the title of the hierarchy. This will appear in the issue panel whenever the hierarchy is shown.
Each node (including the top-level parent) has an enabled slide button. This allows you to stop any new hierarchies being created. This is handy to stop a new hierarchy being used before you are ready to stop an existing hierarchy from being used anymore.
The Issue Type(s) field defines which issue types the top-level parent can be. The Custom Relationships panel will only show on issues with one of these issue types (it will show for the children in the hierarchy once those issues are linked). The top-level parent is the only node that you can set more than one issue type for. For child nodes, you have to specify each issue type separately.
The second to last field in the dialog is an optional name to call the children of this issue. This will displayed as a heading for the list of children belonging to this node.
The last field allows you to specify which fields are shown in the issue view for this hierarchy. The display rule is defined in the Rule page (see the section below).
If I entered a title of "Development", issue type of Epic and the name of the children as "Tasks" then the configuration page would now display the following
The configuration page now has the new top-level parent but the details are unsaved. Click the save button to make the changes permanent. To the right of the newly added node are three icon buttons: add child, edit this node and delete this node (and all of its children). Clicking on the add child icon will open the dialog shown below.
This dialog has the same fields as the top-level parent except for the Hierarchy Title. The Issue Type can be any type that is available, including the same type as the parent. The "Name to call children" field if there will be no children for this issue type. Adding and issue type of Bug will display show the following configuration.
For the hierarchy shown above the first level in a hierarchy will always be an issue of the type Epic and that will only have children that are the Bug issue type. At the moment the, any children that are bugs can not have any children.
Next, we will add another child to the Epic. This time it will be an issue type of Story whose children are called "Bug Tasks".
For the hierarchy shown above the first level in a hierarchy will always be an Epic but that Epic can have children of the issue types Bug and/or Story.
Next, we will add a Bug issue type to the Story node.
For the hierarchy shown above the first level in a hierarchy will always be an Epic but that Epic can have children of the issue types Bug and/or Story. For those children, if any of them are a Story issue type then they can have children of the issue type Bug. The Bug issues can not have any children. In the Epic the bug and story issues will be called "Task" and the bug issues shown in the story issue will be called "Bug Tasks".
Custom Relationships offers two different ways to configure relationship hierarchies: globally (for all projects) and for particular projects. This section describes the global configuring of relationship hierarchies.
To add a relationship hierarchy for a project go to the projects admin page and select the Custom Relationships tab (near the bottom).
If you define any hierarchies for a project then only issues within this project can use these. The issues can also use the globally defined hierarchies as well.
Please see the Global Configuration section above for help in using this configuration page. The global and project pages are almost identical. The only difference is that the project page only lets you use issue types that are available for this project whereas the global page allows you to use all issue types.
Global Rule Configuration
Custom Relationships Rules offers two different ways to define rules: globally (for all projects) and for particular projects. This section describes the global defining of rules
The global Rule Configuration page can be navigated to by going to the administration tab Apps and then selecting Rules under the Custom Relationships section.
Rules are used to define a behaviour for a hierarchy. These rules are defined independently from the hierarchy and a rule can be used on more than one hierarchy.
The empty Rules page is shown below.
Click on the "Create Rule" button to create a new rule. You will then be shown the following page.
The page wants you to select when the rule should be run. For this example there is only one option, Displaying Fields in Issue List. Click on the monitor icon to select this option. After selecting the "When" part of the rule you now are taken to the "Action" part of the rule. Since there is only one action for this "When" then it is selected automatically and displayed.
This action shows a list of the current fields that are displayed for issue hierarchies. Hovering over them gives you a trash icon for deleting them and opening the select field, under the list, will allow you a add new ones. For re-ordering the fields can be dragged or you can use the arrows shown when hovering.
NOTE: The list of available fields is being added to on an ongoing basis. If you want a particular field, that isn't currently present, then please ask (support (at) redmoon-software.com).
Once you have selected the fields you want then you click the Next button to take you to the final page.
Once you have entered the name you can click Save to complete the creation of the rule.
This rule can now be selected in the configuration of a Top Level Parent node and the fields you selected will be displayed.
Project Rule Configuration
Custom Relationships Rules offers two different ways to define rules: globally (for all projects) and for particular projects. This section describes the rules defined for a project
The Project Rule configuration page can be navigated to by going to a project administration section (Project Settings) and then selecting Custom Relationship Rules.
Please see the Global Rule configuration section above for help in using this page. The global and project pages are almost identical except the project rules can only be used for the hierarchies defined in this project
Using Custom Relationships in Issues
Important: The panel will ONLY appear if:
The issues type is the same as a top-level node in a hierarchy defined in this projects configuration page or in the global configuration page
This issue is a Custom Relationships child of another issue
The Custom Relationships panel
The Custom Relationships panel appears in Issues pages just below the details section.
In the example above, the hierarchy being displayed has:
A top-level node of an issue type of Epic
A Title of "Development"
The top-level node has "Children are called" set to Tasks
Linking Issues to this Issue
The Add Issue button can be clicked to add/link issues to this issue. When the button is clicked the following panel is displayed.
The configuration for this hierarchy specifies that this Epic node can only have children that are the issue type Story or Bug. You can either create a new issue or find an existing one.
Create New Issue
To create a new issue click on either the Bug or Story buttons to open the Jira issue creation dialog with the issue type pre-set. In this dialog you can specify the issue you want to create and then click the create button to add it to the development hierarchy.
You can attach an existing issue to a hierarchy by using JQL or entering the issue keys. To use JQL click on the "Use JQL" button. This will open the JQL query tool.
Once the search parameters have been specified then the Link All Issues button can be clicked to add those issues displayed to the appropriate hierarchy.
The other option for finding issues is to click the Enter Keys button. This will display the following panel.
The user enters the issue keys to link and then clicks Link All Issues.
When issues have been added to a hierarchy then they will be displayed below the hierarchies.
Each line displays the issues type, priority, key, summary, status and assignee. To the right of each issue is a button with three dots. Clicking on this will show more information about that issue and allow you to remove the link.
The "Remove Link" button will remove the link to issue whose information is being display without prompting.
Searching using JQL
The following is a hierarchy that will be used to demonstrate the result of JQL searches.
/ \ \
LR-3 LR-4 LR-6
Get all children of a parent
To get all children belonging to the parent with the issue key LR-2 use the following. It will return LR-3 and LR-4.
issue.property['com.redmoon.linkedrelationships.children'].childNodes.parentIssueKeys in ('LR-2')
Get all children of the top-most parent
This gets all children of the issue that is at the very top of a hierarchy. So the following would return LR-2, LR-3, LR-4, LR-5 and LR-6
issue.property['com.redmoon.linkedrelationships.children'].childNodes.topIssueKeys in ('LR-1')
Get all parents for an issue
This gets all parents of the issue. So the following would return LR-1
issue.property['com.redmoon.linkedrelationships.parent'].parentNodes.childIssueKeys in ('LR-2')
Can I have a hierarchy where all levels are the same issue type?
Yes, you can use whichever issue types you want at each level. So you can have the top-level node of type Task and that only has children of type Task and that task can also have children of type task and so on ...
Why can't I delete a hierarchy that is being used?
Hierarchies that are being used can't be deleted because the relationship data would be lost. If you don't want to use a hierarchy any more then just disable the top-level parent. When this is disabled you will still see any current relationships in your issues but no new relationship will be able to be created and no existing relationships will be able to be modified
Why is the Custom Relationships panel no showing in the Issue
The Custom Relationships panel is only shown if:
The issues type is the same as a hierarchies top-level node
This issue is linked to a parent issue using Custom Relationships.
Find all top level nodes
This gets all top level issues. So the following would return LR-1
issue.property['com.redmoon.linkedrelationships.toplevel'].children.nodeIds is not empty