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).

Definitions

The following are definitions used in this documentation.  To make understanding easier the following diagram is referred to within those definitions

Buy Now
diagram related to 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

Sections
  1. Global Configuration

  2. Project Configuration

  3. Global Rule Configuration

  4. Project Rule Configuration

  5. Using Custom Relationships in Issues

    1. Custom Hierarchies

    2. Lists from JQL Queries

    3. A Drop-down menu of JQL Queries

  6. Searching with JQL

  7. FAQ

Global Hierarchies

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.

adding a new child node in the hierarchy

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".

 
Add new top level parent
Create new Custom Relationship hierarchies
New hierarchy with one node
Parent node with a single child
Parent node with two different child types
Parent with three children, including a child of a child

Project Hierarchies

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.

The empty rules page

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.

 
The name and enabled setting for a rule

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.

Select which when condition that the rule will be used for
Once an action has been selected the action can be configured
Choose the action for the rule you want to create

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"

The new rule that was created
Create a rule for when custom relationships is shown in an issue

This will display the following two options.

The two actions available to display JQL queries in an issue

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.

Enter details for a JQL rule

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.

Hierarchies

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.

Find Issue

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.

JQL Search for issues to attach

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.

Custom 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.

 
More info and actions for an Issue
Linked Relationships panel with linked issues
Add an issue to a hierarchy
Enter issue keys to link to this issue
The Custom Relationships issue panel showing a custom hierarchy, a display JQL query and a list of selectable JQL queries

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.

The list of issue for the JQL rule that was selected
Display a list of issues created by a JQL statement

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".

Display a drop down menu to select JQL queries that should be shown

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-1

/    \

LR-2   LR-5

/   \     \

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

FAQ

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 ...

hierarchy made out of the same issue type

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.