Issue Reference Field Type

Issue Reference Field Type

Atlassian Marketplace Raledo Services Raise a Support Request

Issue Reference Field Type

Changes to Custom Field Configuration -5 Sept 2022 🚀 We have changed how the custom field is configured. Instead of using the custom field context, we have provided a dedicated configuration screen for all fields of this type. You can easily migrate your old configuration to the new configuration screen. See Instructions →

The Issue Reference Field Type is an easy to use alternative to the standard Jira Issue Linking mechanism. It is a simple select list of Jira Issues. The contents of the select list are configured using a JQL statement, allowing users to select from a restricted list of issues.

For example, if you have a project which contains issues representing customers, and another project containing support requests raised by those customers, you can use an Issue Reference Field to establish a relationship between the two issues. You can even use this to automatically trigger the creation of a standard Jira issue link of a defined type.

The Issue Reference Field Type is ideal for building hierarchies, such as Parent Links, Portfolio structures, and Product Release hierarchies. With this tool, you can create multiple fields to store each type of relationship you need. Check out our Use Cases section for more information and examples.

More Examples 🚀 Check out our Use Cases for simple solutions to complex problems Go to Use Cases →

Getting Started


  1. Log into your Jira instance as a Jira Administrator.
  2. Click the Apps dropdown and choose Find new apps.
  3. The Find new apps screen loads.

  4. Search for Issue Reference Field Type and click on the app tile.
  5. The App Details screen loads.

  6. Click Get app to start installing your app.
  7. You're all set!
  8. Click Close in the Installed and ready to go dialog.


Migration Custom Field Context Configuration to New Configuration Experience

In previous versions of the app we used the custom field context to configure the JQL that is associated with the instance of the custom field. However, we have now changed this so that the app has its own configuration screen.


This will list all the custom fields of type Issue Reference Field Type, and allow you to configure each independently, without using the custom field context.

It will also provide a mechanism to import the configuration from the custom field context should you have any existing fields created with an older version. If you click this button next to the field name, the JQL for your custom field will be imported. Once imported, the option to import will disappear for the relevant field.

When you click on Config, you will be presented with the configuration screen. Here you can add a new Context and Configure existing contexts.

Create an Issue Reference Custom Field

We start by creating the custom field in the normal way and choose the Issue Reference field type.

  1. Login as a Jira Administrator and Select Admin ⚙ > Issues.
  2. Under FIELDS, select Custom fields.
  3. Click Create custom field. Make sure to select All to view the available field options.
  4. Scroll down the list and select the Issue Reference Field Type and click Next.
  5. Type the Name and Description of the field.
  6. The name you select appears as the custom field's title wherever the field appears.

  7. When you have entered the field Name and Description details, select Create.
  8. Optionally, add the new custom field to one or multiple screens by ticking the corresponding box and click Update.

Configure the field with JQL

Once the field is created we can configure the field by setting the JQL query that should be used to populate the select list.

  1. Login as a Jira Administrator and Select Admin ⚙ > Apps.
  2. Under APPS in the left hand navigation sidebar, select Reference Field Configuration.
  3. If this is the first time you have used this field type then you will be accessed to grant access to the app before you can configure the field. Follow the on screen instructions and grant acces for the application. For more information see Grant Access to App.


  1. Click the Config button next to the name of the field you are configuring.
  2. Now you will create a Context for your configuration. A context is similar to a custom field context. The context allows us to present the user with different options for a field i.e. different JQL can be executed for each context. For each context we specify the Project(s) and Issue Type(s) that should be matched for each context. In the example below if the user is viewing an issue in the ABC project, the field called Dev Ref Field will execute the JQL “project = CCM”, thereby showing a list of all issues in the CCM project.
  1. In the JQL field, type the JQL query you will use to populate the options in your Issue Reference Field. Click the Save button.

Using with Automation Rules

Changes to the field value can be used to trigger automation rules, just like any other field. For example if you want to automatically create or delete a Jira Issue Link when the value in your Issue Reference field changes, you can do the following.


  • Try to ensure the JQL will only return relevant issues. For example, if it does not make sense to create a relationship with an issue that is closed, then exclude closed/resolved issues from the JQL results (e.g. ‘AND resolution is empty’)

Limitations and Known Issues

Issue Reference Field Type is built in Forge because we want to support Atlassian's new cloud app development platform that helps developers to build trusted and scalable apps with Atlassian-hosted compute and storage. Our team monitors the latest developments and releases from the Altassian Forge team and we will incorporate the relevant improvements and new capabilities as quickly as possible.

At the moment, fields built using the Forge framework, including the Issue Reference Fields have the following limitations:

  1. Cannot be used on Workflow Transition screens. If they are added to a workflow screen, they will be rendered as short text fields.
  2. Cannot be used on the “Create Linked Issue” screen used in JSM projects.
  3. Only work with the new issue view. Fields of this type cannot be rendered on boards or in the Global Issue Navigator (i.e. JQL search results).
A workaround exists which involves using automation rules to update a backing field. For example, we could have a Customer Issue Reference field, and a Customer Name text field. Using Automation Rules we can update the Customer Name text field each time the Customer Issue Reference field changes. Then we can display the Customer Name field in the boards and issue navigator.

How to Use the Issue Reference Field

As a user, the issue reference field created by your administrator will look like a normal select list field.

In the above screenshot the administrator has created a Hardware Asset issue reference field. It is configured with the JQL ‘project = “Asset Management” and assettype=Hardware and status = Active’, thus allowing the user to establish a relationship with any active hardware asset from the Asset Management project.

Clicking on the field will open a dialog box and allow the user to select from the list of available issues, which in this case are all Hardware Assets. See Demo Video

Note, if you click on the issue key link within the issue reference field, the issue will be opened in another tab.

Grant Access to App

As a user you need to grant access to the app. The first time you view an issue that uses an Issue Reference Field, you will be presented with the following


Use Cases

Customer Relationship Management

  • Store Customer Information in a separate Jira project and issue type.
  • Create a Customer field using the Issue Reference field type, and configure the JQL for the field with ”issuetype = Customer and status = Active”.
  • When you create an issue related to one of your customers, use the Customer field to relate the new issue to the relevant Customer.
  • To find all issues related to a single customer use JQL like “Customer.key = CUST-123

Asset Management

  • Create an Asset Management project and an issue type Asset.
  • Create an Asset field using the Issue Reference field type, and configure the JQL for the field with ”issuetype = Asset and status = Active”.
  • When an incident related to a particular Asset (e.g. an employees laptop), use the Asset field to select the related employees laptop from the list.

Issue Hierarchies

  • Add a Program issue type. Add another issue type to represent Initiatives.
  • Programs can contain one or more Initiatives. And Initiatives contain Epics, which contain Stories etc.
  • Create two Issue Reference fields - Initiative Link will be used by Epics (”issuetype = Initiative”), and Program Link (”issuetype = Program”) will be used in Initiatives.
  • Epics can be linked to Initiatives using the Initiative Link field.
  • Initiatives can be linked to Programs using the Program Link field.