Display Linked Issues DC - Field settings

Each context of a Display Linked Issues field has its own configuration. Open it from Administration → Issues → Custom fields → your field → Configure.


Settings

Setting Mode What it does
Link types Links Which issue link types (and directions) are shown
JQL JQL The query whose results are shown
Fields Both Columns of the table, in order: any system or custom fields
Include current issue JQL Whether the current issue itself may appear in the results
Matching issues JQL Show only or hide the issues whose field equals the current issue’s - see Exact match
Exact match JQL The text field compared by Matching issues
Max issues Both Maximum number of rows - see Max issues
Show as panel Both Also show the table as a panel on the issue view
Show count Both Show the number of issues

Max issues

Max issues limits the table in both modes:

  • in JQL mode - the number of issues taken from the query;
  • in links mode - at most N linked issues visible to the current user.

When there are more issues than the limit, the table ends with the marker “Showing first N of M issues”. If Max issues is not set, the limit is 1000.

The same limit applies to the CSV export and to the search index of the field.


Exact match and Matching issues

JQL ~ is a word search: a query like email ~ "willi@gmx.de" also finds anna.willi@gmx.de. When you need issues with exactly the same value as the current issue, use the exact-match filter. It is available in JQL mode, below Include current issue:

  • Matching issues - what to do with the issues that match:
    • Show only matching issues - keep only the issues whose value equals the current issue’s value;
    • Hide matching issues - remove those issues and keep the rest.
  • Exact match - the field to compare. Text fields are offered: single-line text, multi-line text, read-only text and URL. — off — disables the filter.

How values are compared:

  • the value of the field on each found issue is compared with the value on the current issue as a whole;
  • the comparison ignores case and leading and trailing spaces;
  • an empty value matches nothing:
    • Show only matching issues with an empty value on the current issue - the table is empty;
    • Hide matching issues with an empty value on the current issue - nothing is removed.

Max issues is applied after the filter: you get up to N issues that passed it.

Example: a support field shows other requests of the same customer with a JQL that searches "Customer email" ~ the customer’s address. For willi@gmx.de, the query also returns requests from anna.willi@gmx.de. With Exact match = Customer email and Show only matching issues, only the requests from willi@gmx.de stay.


Issue panel and Location

With Show as panel, the table is also shown as a panel on the issue view. Location sets where:

  • Right - the right column of the issue view;
  • Left - the main (left) column;
  • a custom key - any web panel location key matching [a-zA-Z0-9._-]+.

The change applies without restarting Jira.

A panel is shown only on issues where there is something to show and only with the configuration of the issue’s context of the field. In the right column, a wide table scrolls horizontally; words are not broken letter by letter.


Access

  • The configuration pages and the admin REST API require password confirmation (WebSudo), like other Jira administration pages.
  • Panel settings are changed only by a Jira administrator.

Admin REST API

Both endpoints require a Jira administrator.

List the contexts of a field with their configuration

GET /rest/linked-issues/1.0/admin/fieldConfigs?customFieldId=<id>

Save a configuration

POST /rest/linked-issues/1.0/admin/fieldConfig
Content-Type: application/json
Origin: https://jira.example.com

The body carries the settings described above: linkTypes, link, fields, jql, showAsPanel, showAsPanelSW, showCount, includeCurrentIssue, maxIssues. Use the GET endpoint to see the contexts of the field that have a configuration and their current values.

Responses:

  • 400 - the configuration is not valid;
  • 401 / 403 - the caller is not a Jira administrator;
  • a POST without an Origin or Referer header is rejected by Jira’s XSRF check - send the header of your Jira base URL.