Automation and JQL

A selection is not only something a person picks in the picker. It is written by Automation, queried in JQL, read as a smart value, and kept in a relationship index that stays correct on its own. This page covers all four.

The property, the JQL alias and the JQL function share one vocabulary, selects and selectedBy, so the same idea reads the same way wherever you meet it.

Setting a field from a rule

There are two ways, and they differ in what the rule author has to type and in whose name the change is recorded.

The application’s action

Forge custom fields do not appear in Automation’s own Edit work item field list (FRGE-1108), which is why this exists.

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

It takes no work item input. The action always writes the work item the rule is currently running on, so a branch changes what it acts on: put it inside a branch over linked work items and it writes each of them in turn.

Full size

It writes through Jira’s ordinary issue edit, as the application, so a change no person made is not recorded against a person: the work item’s history shows the app. Everything else behaves normally, because it is still an ordinary edit. Field validation applies, workflow validators run, and the relationship index and native work item links update through the same path a human edit takes.

Acting as the application also means the action is not limited to what the rule’s user can see. Automation rules are configured by administrators, and the field’s JQL scope is the control over what a rule can select.

Three behaviours to know before you build a rule

Work items outside the field’s JQL scope are skipped, not written. The rest are written, and the skipped keys are named in the action’s message and skippedKeys outputs. If every key is out of scope the action fails, so “all your keys were rejected” can never look like “field cleared”.

To copy from another Work Item Selector field, type the smart value by hand, as {{issue.customfield_12345}}. Automation’s suggestion list offers a broken form for Forge fields (AUTO-2131).

To select by query rather than by key, use Automation’s own Lookup work items action and feed {{lookupIssues.key}} into the work items input.

Outputs

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

Automation does not write successful action outputs to the audit log, so message is written to carry the whole story on its own.

Jira’s own Edit work item action

The field cannot be picked from the field list, so the Advanced section is the only route, and the value is JSON:

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

Use your own field’s id rather than the one above. The field configuration screen’s Knowledge base section prints this snippet with the id already filled in.

This path writes through the REST API, so the field’s JQL scope does not filter what it writes, and the work item’s history attributes the change to Automation for Jira rather than to the application.

Reading a selection in a rule

There are two ways to read one, and the ordinary one is enough for most rules.

Reading the field itself

The field answers to a plain smart value like any other Jira field, by display name or by id. Both forms are equivalent, and the id is the sturdier of the two because renaming the field does not break a rule that uses it.

Below, “Blocked by” is a single select field and “Depends on” is a multi select one.

A multi select field returns a list, so every one of Jira’s list smart values works on it: .first, .last, .size, .get(0), filtering and the iteration syntax.

Reading the relationship index

The index answers the question the field cannot: what points at this work item. A field only knows what it selects, and the index keeps the reverse direction as well, which is why a rule asking “is anything still blocked by this” reads the index rather than a field. It works in conditions as well as actions.

It also reads across every Work Item Selector field at once, where a field smart value reads one field. Iterate a list the usual way:

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

Custom JQL functions

Four functions, one job each, with the direction stated in the name.

Narrowing a function to one field

Every function takes an optional trailing field argument, and it is the difference between “related somehow” and “related in this particular way”.

Leave it out and the function searches every Work Item Selector field on the site, so a work item selected in “Blocked by” and one selected in “Duplicates” both come back. Name a field and only that field’s selections count.

It accepts two forms, and they mean the same thing:

The name is the field’s, not the context’s, so one argument covers every context that field has. Quote it either way, and match the display name exactly, spaces included.

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

The field configuration screen’s Knowledge base section prints these with the field’s own name and id already filled in, so the argument does not have to be typed from memory.

Querying without a function

Every indexed path also has a JQL search alias, which is the path with a wis prefix, so plain JQL works too.

wisSelects = "IT-1"
wisSelectedByCount > 0

How the index stays correct

Everything above reads a relationship index, so the index being right is the thing that makes the rest trustworthy. It is maintained asynchronously through Forge async events, with a per-work-item concurrency key so all writes to one work item’s property are serialised rather than racing.

Four events maintain it, and installing or upgrading the application backfills work items that already hold values:

• Work item created and updated, but only when the changelog names one of this application’s fields
• Work item deleted, which clears the dangling references on everything it pointed at and everything that pointed at it
• Work item link deleted, so a link removed by hand clears the selection it came from. Link creation is deliberately not subscribed to, because a link someone adds themselves must not appear in the field.

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. Both reach the same service desk, so either way the request gets a reference and an SLA measuring the response.