Jira Automation

Linker fields work with Jira's built-in automation. Rules can read a field through smart values, set it through advanced field editing, and react the moment it changes. Every recipe on this page was verified on a live site.

The value automation sees

A Linker field stores a plain list of work item keys, for example ["CLI-3"]. There is no wrapper object and nothing to unpack: the standard list functions of automation smart values apply directly. You need the field id (customfield_<number>) for most recipes; the Fields page of the Linker admin shows it right under each field name.

Reading the field with smart values

With a field id of customfield_10264:

The field carries keys only. To use the summary, status or any other detail of a selected work item, resolve the key with the Lookup work items action first:

key = {{issue.customfield_10264.get(0)}}

After that step, {{lookupIssues.first.summary}} holds the work item's summary, and the other lookupIssues smart values work the same way. If your rule edits the field earlier in the same run, add the Re-fetch work item data action before reading, so the smart values see the new value.

Setting the field

The simple field picker of the Edit work item action does not list app fields; that is a Jira limitation which applies to every Forge app field, not just Linker. Use the JSON route instead: open More options in the action and enter the value under Additional fields:

{
  "fields": {
    "customfield_10264": ["CLI-3"]
  }
}

The value is always a list; a single-selection context takes a one-element list. Smart values are allowed inside the JSON, so a rule can copy a selection from a looked-up work item or compose it from other data.

The write behaves exactly like an edit made by hand or through the REST API: Linker's sync picks it up and creates the configured native links within about a minute, and the configured delete behavior applies to values the rule removes. If somebody opens the work item before that, the field writes the missing links right then, so a rule's result is never left half-done on a page somebody is looking at. Nothing special is needed in the rule. The How linking works page describes this safety net in detail.

Reacting to changes

The Field value changed trigger lists Linker fields like any other field. Select the field, and the rule fires whenever its value changes, no matter whether the change came from the picker, a panel, a bulk edit or another rule.

Two things to keep in mind:

• Linker's own sync counts as a change too. When reverse sync adopts a manually created link into the field, or a resync rewrites values, the trigger fires as well. Usually that is exactly what you want; if not, narrow the rule with a condition.
• JQL conditions inside rules compare Linker fields by exact value: "Client" = "CLI-3" and in lists work, the ~ operator never matches app fields. See Limitations & timing.

Linker's JQL functions in a rule

Linker contributes three JQL functions to Jira, and rules can use them wherever a rule accepts JQL: in a JQL condition, in the Lookup work items action, and in a JQL branch. That lets a rule act on a relationship without knowing which field carries it.

issue in linkerSharesWith("{{issue.key}}", "Client")

A branch over that query walks every work item that carries the same client as the one that triggered the rule. The same works the other way round: issue in linkerLinksTo("{{issue.key}}") branches over everything that points at this work item, through any Linker field. The full reference, including what each function returns and where it deliberately matches nothing, is in the JQL guide.

Workflow validator: no open linked work items

Not everything belongs in a rule. Some things a workflow should simply refuse, and Linker contributes a validator for the one people ask for most: Linker: no open linked work items blocks a transition while something this work item is linked to is not finished. It is set up in Jira's workflow editor rather than in an automation rule, and it is offered for company-managed and team-managed spaces alike. It answers the long-standing request JRACLOUD-43369, 519 votes at the time of writing.

Setting it up

1. Open Jira Settings (gear) → Work items → Workflows and edit the workflow that carries the transition.
2. Select the transition you want to guard, for example the one into Done, and open its validators.
3. Add a validator and choose Linker: no open linked work items from the list.
4. Pick the link type and the side. The side is offered as the phrase the transitioning work item itself shows in its Linked work items section, for example is blocked by, so you choose what you would read on the work item. Either side covers both directions.
5. Publish the workflow. From then on the validator applies to that transition.

What it does

The transition is refused while any work item linked in the configured way has a status whose category is something other than Done. The person trying it reads: “A linked work item is not done yet. Finish or unlink it, then try again.” It goes by the status category, so a work item counts as finished as soon as its status sits in the Done column of the workflow, whatever that status is called and whether or not it carries a resolution.

A validator that was added but never configured lets every transition pass, so a half-finished setup never blocks anybody.

Worked example: name the client in a customer-visible comment

The scenario: support requests carry a Linker field Client that points at the client's work item. Agents see the full field with columns in the agent view, and customers see the client's name on their request, because Linker renders the field in the portal itself, see Service desk portal. What a rule adds on top is a notification: a customer-visible comment that says the request has been assigned, at the moment it happens, in the activity feed where customers get an e-mail for it.

The rule:

1. Trigger: Field value changed, field Client.
2. Condition: Work item fields condition, Space equals Support.
3. Condition: {{smart values}} condition, first value {{issue.customfield_10264.size}}, greater than 0. The trigger also fires when the field is cleared; without this guard the lookup would run the invalid JQL key = and the comment would name nobody. Use the smart values condition here: like the simple field picker, the Work item fields condition does not list app fields yet, and a JQL condition can read a stale search index right after the change.
4. Action: Lookup work items with the JQL key = {{issue.customfield_10264.get(0)}}.
5. Action: Comment on work item with the text Your request is assigned to {{lookupIssues.first.summary}}. and the comment visibility set to Share with customer.

The moment an agent picks a client, the customer gets a comment such as "Your request is assigned to Lakeside Biotech.": only the name, no key, no status, no internals. Internal comments stay hidden from the portal as usual.

The same pattern works for any consumer that needs a display value instead of a key: write {{lookupIssues.first.summary}} into a text field, a Slack message or a customer email.