Triggers
Overview
Triggers, implemented with the trigger macro, wait for events and 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, and by using filters, you can perform different actions for different situations related to that event.
Filtering events
Events are generic. For example, the statechanged event happens every time there is a state transition, regardless of which state is being transitioned to or from.
So, the trigger has to filter to make sure it's acting not just on the correct event but also in the right situation in relation to 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 a number of 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 workflow, each state can transition to any other state. However, we can filter the trigger so it only acts when the statechanged event changes to the Second state
Required filters
Most of the filters are optional; however, some are required depending on which event you are listening to.
See: trigger macro for details of the available filters.
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 at that point in time.
Condition filters
Triggers support the use of conditions as a filtering mechanism that can be used for any event.
For example, you could 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
There are some special filters that go beyond simple comparison checks. They are:
initial– unique to thestatechangedevent, 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 contentpartial– 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 completedsuccess– 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 create a custom 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 is available in the first two triggers, is not available in the third trigger.
Queuing actions
When a trigger receives an event, it checks its filters and then performs its actions. It performs 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 that can take longer to complete. For example:
Publishing actions, particularly for remote-space publishing actions using the remotepublish-page macro or remoteremove-page macro
Sending lots of emails to a user group using the send-email macro
Approving or rejecting large numbers of child pages using the approve-children or reject-children macros
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:
{workflow:name=Queued actions}
{state:Editing|submit=Published}
{state}
{state:Published}
{state}
{trigger:statechanged|state=Published|queue=true}
{remotepublish-page:ToCloud}
{trigger}
{workflow}Error handling
Triggers that 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 is displayed as Rules in Workflow Builder.
The workflow builder does not allow editing of rules. Instead, each one displays a summary of the trigger event and event filter.
Macros
For a list of action macros to add to a workflow trigger, see: Actions
Examples
-
Add workflow review information to a header for inclusion in a page export — Use the workflow to add a header containing details of the workflow review to comply with a records retention policy for exported approved page PDFs
-
-
Adding page activity to email — Include page activity report, or a link to it, in custom email notifications
-
Dynamic page header using a metadata value and triggers — Use a trigger to display a different page header for each state in the workflow. Page header content is set as a metadata value.
-
How can I fast-track a single rejection or a single approval decision — How to require everyone to approve, but only need one person to reject
-
-
-
Require Parameters on a state transition — Require workflow parameter values to be set before moving into a workflow state.
-
-
Select the workflow that is applied using content labels — This is a way for space administrators to automatically apply workflows to different documents in a space based on the content label.
-
State expiry dates — Using state expiry dates, defining them with metadata, and making them editable
-
Stiltsoft Handy Status Macro for Confluence — A user changes the Stiltsoft Handy Status macro value for a page, and this automatically changes the Comala Document Management applied workflow state.
-
-
Use attachment events in workflow triggers — Triggering events when attachments are created, updated, or removed.
-
Use blog post events in a workflow trigger — Workflow events associated with blog posts
-
Using different styles in a trigger message notification action — Using the
styleparameter of theset-messagemacro -
-
Using set-message and metadata to display different information for the draft and published content — Using the
viewparameter of theset-messagemacro to display a different metadata when users view the draft or published versions
Related pages
Need support? Create a request with our support team.