Automation and JQL

How to write a selection from Automation, read it in a rule, and search it with JQL. Everything uses the same two words: selects and selectedBy.

Setting a field from a rule

Two ways:

The application’s action

No Forge field appears in Automation’s Edit work item field list (FRGE-1108 (opens in a new tab)), so the app has its own action.

Set work item selection. Set, add to, remove from or clear a Work Item Selector field on a work item.

It writes the work item the rule is running on. Inside a branch, it writes each work item in turn.

Full size

• It edits as the app, so the history shows the app, not a person. Validation, the index and Jira links update as for any edit.
• The field must be on the edit screen, or the run fails.
• It is not limited to what the rule’s user can see. The field’s JQL scope limits what a rule can select.

What to know before you build a rule

• Keys outside the JQL scope are skipped and listed in message and skippedKeys. If every key is out of scope, the action fails.
• Too many keys fails the run: more than one for single select, more than 100 for multi.
• A scope with {{user.accountId}} blocks Replace and Add, because a rule has no viewer. {{issue.…}} placeholders work.
• To copy another Work Item Selector field, type the smart value by hand: {{issue.customfield_12345}}. Automation’s suggestion is broken for Forge fields (AUTO-2131 (opens in a new tab)).
• To select by query, use Lookup work items and pass {{lookupIssues.key}}.

Outputs

Available to later rule steps: message, changed, workItemKey, fieldId, fieldName, selectedKeys, selectedCount, addedKeys, removedKeys, skippedKeys.

Successful outputs are not written to the audit log; message holds the result.

Jira’s own Edit work item action

Use the Advanced section:

{
  "fields": {
    "customfield_10192": ["IT-1", "IT-2"]
  }
}

Use your own field id; the Knowledge base on the field’s configuration screen has it filled in. A single select field takes a list with one key.

A script or another app sends the same body with PUT /rest/api/3/issue/{key}:

export default async function () {
    await jira.put('/rest/api/3/issue/FIN-12', { fields: { customfield_10192: ['IT-1', 'IT-2'] } });
}

import api, { route } from '@forge/api';

const key = 'FIN-12';
await api.asUser().requestJira(route`/rest/api/3/issue/${key}`, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ fields: { customfield_10192: ['IT-1', 'IT-2'] } })
});

curl -X PUT "https://your-site.atlassian.net/rest/api/3/issue/FIN-12" \
  -u "$EMAIL:$API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "fields": { "customfield_10192": ["IT-1", "IT-2"] } }'

Each of these skips the JQL scope, and the history names whoever sent the request: Automation for Jira for a rule.

Reading a selection in a rule

Reading the field itself

Use the field’s name or id. The id keeps working if the field is renamed. Below, “Blocked by” is single select and “Depends on” is multi select.

A multi select field returns a list, so Jira’s list smart values (opens in a new tab) work: .first, .last, .size, .get(0), filtering and iteration.

Reading the relationship index

The index answers what points at this work item, across every Work Item Selector field. Use it in conditions and actions. It updates in the background, a few seconds behind the field.

Iterate a list the usual way:

{{#issue.properties.workItemSelection.selectedBy}}{{.}} {{/}}

Custom JQL functions

Four functions, each named for its direction.

Full size

Narrowing a function to one field

Without a field argument, a function searches every Work Item Selector field. Add a field to count only its selections:

Quote it either way. The name ignores case but must match otherwise. If two fields share a name, the query fails and lists each cf[...].

workItem in workItemsSelectedBy("IT-1")
workItem in workItemsSelectedBy("IT-1", "Blocked by")
workItem in workItemsSelecting("IT-1", "cf[12345]")
workItem in workItemsWithSelection("Blocked by")
workItem not in workItemsSelectedByAny()

The Knowledge base on the field’s configuration screen has these with your field filled in.

Querying without a function

Each index path has a JQL alias with a wis prefix:

wisSelects = "IT-1"
wisSelectedByCount > 0

How the index stays correct

The index updates in the background, one write at a time per work item. Installing or upgrading indexes existing values. It reacts to:

• Work item created or updated, when one of the app’s fields changed
• Work item deleted, clearing references in both directions
• Work item link deleted, removing the selection it came from. A new link someone adds by hand never appears in the field.

Common questions

How do I set a Work Item Selector field from Jira Automation?

With the app's Set work item selection action: pick the field, choose Replace, Add, Remove or Clear, and list the work item keys.

Why is the field missing from Automation's Edit work item action?

No Forge field is in that list (FRGE-1108 (opens in a new tab)), so the app ships its own action.

Does the Automation action respect the field's JQL scope?

Yes. Keys outside the scope are skipped, and the action names them.

Who does the history show as making the change?

The app, because the action edits as the app rather than as a person.

Related

• Workflow validation, which enforces rules on a selection at a transition
• JQL scope, which bounds what a rule or a person can select
• Permission mode
• Privacy and data handling

A problem or a question? Write to support@oktul.com or open a request in the Help Center (opens in a new tab).