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

Definitions

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

Buy Now

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. Using Custom Relationships in Issues

  4. FAQ

Global Configuration

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

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

 

Project Configuration

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.  

This section is about configuring relationship hierarchies for a particular project.  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.

 

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.

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.

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.

The "Remove Link" button will remove the link to issue whose information is being display without prompting.

 

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

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.

 

Redmoon Software

Site Designed: