--- title: "Triggers" canonical: "https://support.appfire.com/space/CDML/649563178/Triggers" format: markdown --- > Macro (aura-html) ![image](media://ad5b1f57-ad50-4027-bb78-d5b3a97095ae) ## Overview > Macro (excerpt) > > Triggers wait for an event, then perform one or more actions. Triggers, implemented with the [trigger macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859133), wait for [events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655) and then perform one or more [actions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649858941). 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. ### 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694110) 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. ```plaintext {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 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 > Macro (excerpt) > > 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: > > ```plaintext > {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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649925434) 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649923873) actions, particularly for [remote-space publishing](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649728423) actions using the [remotepublish-page](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649628625) macro or [remoteremove-page](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649628704) macro - Sending lots of emails to a user group using the [send-email macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649924039) - Approving or rejecting large numbers of child pages using the [approve-children](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649531735) or [reject-children](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649793152) 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: ```plaintext {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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649728423) - 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649924353). ## Workflow builder Currently, [workflow builder](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650151179) requires the wiki markup for the trigger to be added. ![image](media://d9f53379-8e88-4bb4-a523-98913113d698) The number of triggers in the workflow is displayed as **Rules** in Workflow Builder. ![image](media://a0276226-5114-48b0-83ff-b95113d5e9d7) **The workflow builde**r does not allow editing of rules. Instead, each one displays a summary of the trigger event and event filter. ![image](media://86415ae4-5dba-40f5-94c7-d7474721bbb4) ## Macros - [trigger macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859133) For a list of action macros to add to a workflow trigger, see: [Actions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649858941) ## Examples > Macro (contentbylabel) ## Related pages - [https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859133](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859133) - [https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655) - [https://appfire.atlassian.net/wiki/spaces/CDML/pages/649858941](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649858941)