Triggers

Owned by Robert Alexander Marshall
Last updated: Dec 18, 2023
5 min read
1 Filtering events | 1.1 Example – filtering by state | 1.2 Required filters | 1.3 Event-specific filters | 1.4 Condition filters | 1.5 Special filters | 2 Custom events | 3 Queuing actions | 4 Error handling | 5 Workflow Builder | 6 Macros | 7 Examples | 8 See also

Overview

Triggers, implemented with the trigger macro, wait for Events then perform one or more Actions.

You can add one or more trigger macros to a workflow.

Multiple triggers can listen to the same event. By using filters you can perform different sets of actions for different situations in each trigger relating to the event.

Filtering events

Events are generic. For example, the statechanged event will happen every time there is a state transition, regardless of which state is being transitioned to or from.

So, the trigger has to do some filtering to make sure it's acting not just on the correct event, but also that it's acting in the right situation concerning that event.

For example, you might want an action to occur

  • only when the workflow is in a specific state

  • or when the current user is in a specific group

To achieve this, the trigger macro has several parameters that allow it to filter events for common situations.

In the case of the statechanged event, for example, we want to know which state the transition has sent us to - because that can be used to determine which actions should be performed.

 

{workflow:Filters} {state:First} {state} {state:Second} {state} {state:Third} {state} {trigger:statechanged|state=Second} {set-message:duration=PT1M} We're in the second state {set-message} {trigger} {workflow}

Example – filtering by state

In this example above, each state can transition to any of the other states, so the statechanged trigger will be checked every time.

The trigger is filtered in the example, to only act when the current state is called Second.

Required filters

Most of the filters are optional, however, some are required depending on which event you are listening to – these are marked with  in the trigger macro documentation.

The state filter, state=Second, for example, is mandatory if you are listening to a statechanged event. It can still be used, optionally, for all other events, but there are also events where it must always be used.

Event-specific filters

Just as some events require specific filters, some filters require specific events. One example is the label filter which can only be used with events relating to labels – because those events send details of the label that was added or removed then.

Condition filters

Triggers support the use of conditions as a filtering mechanism which can be used for any event.

For example, use the haslabel condition on any of the available events.

{workflow:name=haslabel condition} {state:First} {state} {state:Second} {state} {trigger:statechanged|state=Second|haslabel=test} {set-message:duration=PT1M} We are in Second state, and the page has the "test" label {set-message} {trigger} {workflow}

Special filters

Some special filters go beyond simple comparison checks. They are:

  • initial – unique to the statechanged event, this filter can be used to make the trigger act only on the first occasion that a state is entered for a given piece of content

  • partial – unique to content review events, this filter can tell the trigger to act on each individual Approve or Reject, rather than waiting for the review to be completed

  • success – unique to custom events, this filter looks at whether the actions of the parent trigger encountered any errors (see Error handling section below)

Custom events

Triggers can be configured to create their own events, which can then be processed by other triggers.

This is achieved using the newevent parameter, for example:

{workflow:name=Custom Events} {state:First} {state} {state:Second} {state} {trigger:statechanged|state=First|newevent=FirstAndSecond} {trigger} {trigger:statechanged|state=Second|newevent=FirstAndSecond} {trigger} {trigger:FirstAndSecond} {set-message:duration=PT1M} Current state is: @state@ {set-message} {trigger} {workflow}

In the example above, the first two triggers both listen to the statechanged event.

  • the first trigger is filtered to the First state

  • the second trigger is filtered to the Second state

Both of these triggers will create a newevent of the same name: FirstAndSecond.

The third trigger listens for that FirstAndSecond event and then displays a message containing the name of the current workflow state (using the pre-defined @state@ value reference).

In essence, we are routing the statechanged events for two states, First and Second, into a single FirstAndSecond trigger, and then using that trigger to perform the action.

Event-specific Event references are not available in custom event triggers. For example, the @comment@ reference, which would be available in the first two triggers, would not be available in the third trigger.

Queuing actions

When an event is received by a trigger, it will check its filters and only then perform its actions. It will perform each action in turn, one after the other.

In most cases, this won't be a problem - because most actions happen very quickly, so the user won't have to wait before continuing their work.

However, there are some actions which may take longer to complete. For example:

In these cases, the user would have to wait for the actions to complete, before they could continue their work. To overcome this issue, you can queue the actions so the user can get on with their work whilst the actions are performed:

Error handling

Triggers which handle custom events can use the success parameter to filter depending on whether the actions of the parent trigger (that created the custom event) encountered errors.

Actions are very reliable, so errors are extremely rare, however there is an increased chance of error when using remote-space publishing – for example, the remote Confluence instance might be down for maintenance, or there might be a problem with the internet connection.

For an example of error handling, see Advanced remote-space publishing.

Workflow Builder

Currently workflow builder requires the wiki markup for the trigger to be added.

The number of triggers in the workflow are displayed as Rules in Workflow Builder.

Rules are not editable in workflow builder. Each one displays a summary of the trigger event and event filter.

Macros

For a list of action macros, see Actions

Examples

See also

Workflow Authoring Guide