Branch automation rules to perform actions on related work items

Work items rarely exist in isolation. They often contain sub-tasks, are stories within a larger epic, or are linked to other work items. These contextual relationships mean when a work item triggers a rule, the resulting actions might apply to other work items as well.

Special conditions and actions are available to create powerful rules that can work across complex work item relationships. For example, you can check that all sub-tasks of a parent work item are resolved.

• A branch for related work items can apply actions to related work items.

  • For example if there are sub-tasks, it would apply the action to all sub-tasks.

• A condition for related work items condition can check the state each related work item

  • For example, it can all linked work items are closed.

In order for a rule to work with a work item in another project, it must be a multi-project or global rule to execute in the projects the work item is in.

Branching on related work items

When configuring automation rules, it's possible to perform actions against related work items. This is referred to as branching. This is in reference to the rule no long executing in a linear fashion, but instead expanding out to multiple paths.

When a rule is branched on a work item or list of work items, the sub-branch of the rule is executed against each work item. All actions and references to {{issue}} will point to the related work item, not the trigger work item.

Branching is useful for a number of use cases, such as:

• Synching all sub-tasks by copying a value from the parent to a specific field.

• Moving an Epic to In progress when a Story is moved to In progress.

• Commenting on is blocked by linked work items when a work item is resolved.

Ordering of branch executions

• Branches on multiple work items (such as 4 sub-tasks) will run in parallel with no guarantee one will finish before the next one starts. Therefore, you cannot rely on changes between branches.

• Branches on multiple work items are run as a new process, with the main branch continuing execution before the sub-branch starts.

Accessing created work items

Rules can create work items using the Create work item and Clone work item actions. Performing further actions (such as adding a comment or creating sub-tasks) on these newly created work items within the same rule requires a related work item branch.

This is because the main branch of a rule always applies to the trigger work item, not the created work item. For example, adding a Comment on work item action after a Create work item action adds a comment to the trigger work item, not the created work item.

To address this, create a new branch for All created work items to allow you to action newly created work items.

Alternatively, you can use the Related work items condition (Most recently created) if you the only need to action a single work item.

Branching restrictions

• Nesting: Branches cannot be nested in one another, and do not support the use of the If/else block condition.

• Isolation: Branches are isolated. Any changes that occur in a branch will not be visible to the main branch, or any others. For example, if a branch has a Create variable action, the created smart value can be used in that same branch, but can't be used in the main branch, nor in any other branches.

Related work items condition

The Related work items condition checks the state of related work items before progressing a rule.

This condition allows for a vast range of use cases, including checking:

• Whether or not a work item has linked work items of a specific type.

• If the work item has a parent or Epic.

• If any of the work items in a sprint or version are unassigned.

• If all the stories in the Epic are resolved.

• That resolved sub-tasks of a specific type have a specific value set.

Setting up the Related work items condition

1. Select the related work item type:

   • Sub-tasks

   • Parent

   • Stories (or other work items in this Epic)

   • Epic

   • Created work items

   • Linked work items

2. Select the condition to check if related work items:

   • Are present

   • Are not present

   • All match specified JQL

   • None match specified JQL

   • Some match specified JQL

3. Select Save.

Learn more

Check out how we use related work items in our Jira automation template library.