Custom Relationships for Jira Cloud
This app allows you to build your own customized relationships, You can specify hierarchies that define:
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
You can also define relationships based on a JQL Query (using a Rule) that is either always shown or just shown when selected (from a dropdown list).
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 hierarchies page can be navigated by going to the administration tab Apps and then selecting CustomRel - Hierarchies 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 CustomRel - Hierarchies 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 two options: one to choose which fields are in the hierarchy list and another to choose what features to display in the Custom Relationships panel in an issue.
Fields to Display in Issue List
For this documentation, we will choose the "Deciding which fields to display in an issue list" 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 the action has been configured the save button can be clicked. After saving you will be taken back to the main Rules page.
You can enter a name to describe the rule and potentially disable this rule. When next is clicked you are take to the When page.
When the action is chosen the user can configure the action.
This rule can now be selected in the configuration of a Top Level Parent node and the fields you selected will be displayed.
Other Options to Display in an Issue
When creating a rule there is a "When Custom Relationships is shown in an issue"
This will display the following two options.
Both options show the same page. The difference between the two actions is in how they display on the Issue page. The first option will run the JQL query and display the list of issues on the issue page. The second option will show all of the rules of this type in a drop-down select list. When the user selects one of these rules the JQL will be run and the resulting list of issues will be display. More than one rule can be selected.
In the image above there is a field for entering the JQL query, a button for testing the JQL (compulsory) and test values for entering the issue and project keys (only shown if the issue and/or project key are mentioned in the JQL query). As mentioned, you can directly reference the issue and project keys related to the issue you are currently in. All JQL queries must be valid JQL statement.
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
The Custom Relationships panel appears in the Issue pages just below the details section. If this is not showing then click on the hierarchy icon below the Issue summary. The panel has three distinct parts:
Custom hierarchies, created in the hierarchy CustomRel - Hierarchies page. This is the first issue list starting with (C)
Zero or more lists of issues specified using JQL queries. This section only shows if there are queries to show. This is the second issue list starting with (J).
A drop-down list containing pre-defined JQL queries that are shown when selected. The drop-down is only shown if there are options in the drop-down. This is under the heading Related Issues.
In the example above there is:
A hierarchy, starting (C), being displayed has:
A top-level node of an issue type of Epic
The title "Development"
The top-level node has "Children are called" set to Tasks
A "Display Issue from a JQL Query" list, starting (J), from a rule called "Other In Progress Issues".
A "Related Issues" section that contains three rules: Show Done Issues in this project, Show In Progress Issues in this project and "Show To do Issues in this Project.
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.
Lists from JQL queries
The display of any JQL Queries is below any custom hierarchies. Each list has a (J) on the right-hand side of the list title. To the right of each issue is a button with three dots. Clicking on this will show more details about the issue, like that shown in the previous section.
A Drop-down menu of JQL Queries
The display of a drop-down list of JQL Queries is at the bottom of the Custom Relationships panel. If there are selectable JQL queries then a drop-down menu under the heading "Related Issues".
When an option in the drop-down menu is selected, a list of issues, based on the JQL query for the rule, shows below. Each list has a (S) to the left of the title.
One list of issues can be shown for every option in the drop-down menu. The list can be removed by clicking on the close button above the list or by clicking on the "x" in the drop-down menu.
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')
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
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.