Triggers

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, and by using filters you can perform different sets of actions for different situations relating to that 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 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 which 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. However, we've filtered the trigger 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 which was added or removed at that point in time.

Condition filters

Triggers support the use of conditions as a filtering mechanism which 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 which 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:

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 via 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:

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

trigger macro

For a list of action macros, see: Actions

Comala Document Management for Data Center and Server

This site has moved to the integrated Appfire documentation and information site for our apps.