Trigger - Checklist changed

AVAILABLE WITH JIRA >= 8.16

The Checklist changed trigger occurs after changes are saved in a checklist field.

The trigger provides Smart Values that can be used down the line in the automation rule.

Configuration

The trigger’s fields are as follows:

Field

Description

Checklists

The checklist fields that the automation rule monitors. When a change is saved in these fields, the automation rule will capture it.

Triggering event

The checklist-specific event that will be checked to run the automation rule. If the event isn’t matched, the event won’t run.

Run items separately

Activating this option can make the rule more resource intensive.

Do not use this option if the rule updates Checklist data.

Jira has a technical limitation that might cause your Checklist data to duplicate in the updated issue.

If enabled, the rule will run once for each matching item instead of once per checklist.

This is particularly useful for cases where an action should be run for each item. Some Smart Values vary depending on this option.

Events

Events are only captured the moment they occur, not every time that the checklist’s status is synonymous to the event. For example, the All items completed event will only run if at least one item wasn’t checked before the update and all items are checked after the update. The event won’t run if all items are checked and a new, already-checked item is added.

Items are compared using their ID. Since the free-form editor resets the ID of all items, some events could be triggered by false-positives generated from the reset.

Event	Description
Item checked	Whenever an item gets checked.
Item unchecked	Whenever an item gets unchecked.
Item assigned	Whenever an item that isn’t assigned gets assigned.
Item unassigned	Whenever an assigned item gets unassigned.
Item assignment changed	Whenever an item gets assigned, has its assignment changed from one user to another or gets unassigned.
Item added	Whenever an item gets added. Added items do not have last values.
Item removed	Whenever an item gets removed. Removed items only have last values.
Item changed	Whenever an item has any of its fields changed, including its order in the list.
All items completed	Whenever the list gets fully checked.
Mandatory items completed	Whenever the list’s mandatory items get fully checked.

Smart Values

The trigger will add Smart Values that can be used down the line in the automation rule. These Smart Values will always contain basic information regarding the checklist custom field the rule is run for, but the item values will either be combined or separated based on the Run items individually field.

Smart value	Description	Example
`checklist.id`	The checklist field’s ID.	`customfield_10001`
`checklist.name`	The checklist field’s display name.	`Definition of Done`
`checklist.items`	The list of items in the checklist. Items can be looped through using the mustache templating language.
`checklist.items.count`	The total number of items in the checklist.	`10`
`checklist.items.completed.count`	The number of items in the checklist that are checked.	`4`
`checklist.items.incomplete.count`	The number of items in the checklist that are unchecked.	`6`
`checklist.items.complete.percent`	The percentage of items in the checklist that are checked.	`40`
`checklist.items.incomplete.percent`	The percentage of items in the checklist that are unchecked.	`60`
`checklist.items.mandatory.count`	The number of mandatory items in the checklist.	`3`
`checklist.items.mandatory.complete.count`	The number of mandatory items in the checklist that are checked.	`1`
`checklist.items.mandatory.incomplete.count`	The number of mandatory items in the checklist that are unchecked.	`2`
`checklist.items.mandatory.complete.percent`	The percentage of mandatory items in the checklist that are checked.	`33`
`checklist.items.mandatory.incomplete.percent`	The percentage of mandatory items in the checklist that are unchecked.	`67`
`checklist.global-items.count`	The number of global items in the checklist.	`4`
`checklist.global-items.complete.count`	The number of global items in the checklist that are checked.	`1`
`checklist.global-items.incomplete.count`	The number of global items in the checklist that are unchecked.	`3`
`checklist.global-items.complete.percent`	The percentage of global items in the checklist that are checked.	`25`
`checklist.global-items.incomplete.percent`	The percentage of global items in the checklist that are unchecked.	`75`

When Run items individually is enabled

The rule is run once per item and only the item it is run for will be available.

Smart value	Description
`checklist.item`	The first item that matched the event.

When Run individual items is disabled

The rule is run once for all items and the items are aggregated in a list.

Smart value	Description
`checklist.matched.items.count`	The number of items that matched the event.
`checklist.matched.items`	The list of items that matched the event. Items can be looped through using the mustache templating language.

Accessing an item’s properties

When looping over the checklist.items or checklist.matched.items value, the loop's context is applied to each individual checklist item. Because of the context, the beginning of the Smart Value doesn’t need to be specified.

Notice the name value in the following example.

CODE

The following items:
{{#checklist.items}}
* {{name}}
{{/checklist.items}}

just got completed.

When a single checklist item is in the Smart Values, the whole value key must be specified. See the following example.

CODE

 The item named {{checklist.item.name}} just got completed.

See the Smart Value representation for the list of all available checklist item fields.