Add a workflow trigger using the code editor

Adding a workflow trigger

You can automate some actions in a custom workflow by adding one or more workflow triggers. A workflow trigger listens for a specific workflow event to occur, such as a change of state, and if any set conditions are met, it actions a change.

A workflow trigger can be added as JSON code using the code editor.

cdmc_codeeditor_trigger_onchangestate_approvedstate_multipleactions.png

Code editor - on change state trigger

Adding a trigger requires a number of JSON properties, values, and data:

an event
an optional condition
one or more trigger actions

The code editor provides the JSON schema for each workflow trigger attribute and attribute parameters with an autocomplete function.

You can toggle from the code editor to the visual editor to view a list of the workflow triggers added to the workflow.

You can also add one or more workflow triggers to a custom workflow using the visual editor.

Adding a trigger

In the app space settings, open the code editor for a custom workflow:

add a trigger after the closing bracket for the last "state".

cdmc_codeeditor_highlight_addpoint_afterlaststatedefinition_for trigger.png

add a comma after the last square bracket ] but before the overall workflow closing curly brace }
add "" to display the JSON schema options

cdmc_codeeditor_triggers_selected_initialschema_object.png

use the keyboard arrow keys to highlight and select triggers array

Add trigger attributes

You must now add the workflow trigger parameters and values - the event, conditions, and actions for the trigger.

For example, when using Create New Workflow in the space document management dashboard:

the starter workflow has no workflow trigger
the empty "triggers":[ ] property is available at the end of the template code to add one or more triggers

The trigger properties are added as contents to the square brackets [ ] in "triggers": [ ].

When adding curly brackets { }, square brackets [ ], and apostrophes "", the editor adds these in pairs. You only need to type the first character.

Add a trigger event - change of state

add the event object
- within the square brackets [ ]
  - type {"
  - this adds the curly bracket and apostrophe pair {""}
- select and add event string from the JSON schema dropdown

To activate the JSON schema prompt, click within the "" . If the JSON schema dropdown disappears before you select a property, retype the apostrophes to display the dropdown again.

add a single event name for the trigger to listen for
- after "event": add the apostrophes ""
- choose an event name from the JSON schema dropdown

cdmc_codeeditor_trigger_eventname_schema_onchangestate_highlighted.png

In our example, we have chosen on-change-state.

All available event names are displayed in the JSON schema. You can:

scroll with the mouse in the JSON Schema box to view additional options
click the keyboard’s Arrow keys to move up or down to highlight an event and select it

Add a trigger condition - state

You can add a condition for the trigger event. Adding a condition is optional.

To add the next JSON code item and activate the JSON schema dropdown, add a comma.

add a condition for the chosen event
- after “on-change-state”
  - add a comma
  - add apostrophes ""
- choose conditions array in the schema

cdmc_codeeditor_triggers_event_eventtype_conditions_schema.png

At each stage of adding our trigger code to create the workflow trigger, the editor displays a small red error in the code line. This indicates that we have not fully completed the required JSON for the property and helps identify the next point where the code for a property, value, or data should be added.

add any conditions for the event
- within the square brackets in "conditions": [ ]
  - type {" to add the curly bracket and apostrophe pair {""}
- choose state string in the schema to constrain the trigger to listen for a change to a selected workflow state

cdmc_codeeditor_trigger_conditions_state_selected_JSON_schema.png

The code editor displays a prompt to add an existing state in the workflow for the state condition.

cdmc_code_editor_trigger_condition_statechange_statename_prompt.png

add the name of an existing state in the workflow with the provided apostrophes in the JSON ""

cdmc_codeeditor_trogger_condition_state_added_rejectedstate_bracketpairhighlighted_conditions_value.png

In our example, we constrained our trigger to listen for a change of state to the Rejected state.

Some event conditions can have multiple values added. For example, the condition for the change of state event can be added as state plus initial or final.

Each condition is added within a set of curly brackets { }. These separate conditions are a comma-separated list within the provided square brackets [ ] of the "conditions" object. Add a comma immediately after an existing closing condition curly bracket to display the conditions JSON schema again and select another condition.

Add a trigger action - send an email

You can add one or more actions to a trigger.

Add an action to perform when the event occurs and the conditions are met.

add a comma after the closing conditions square bracket ]
click within the apostrophes "" ( or type these and click) to display the actions array JSON schema option

choose actions array from the schema dropdown

cdmc_codeeditor_trigger_actions_emptyarray_promptlistofactions.png

You can add one or more actions for each workflow trigger event. These are performed when the event occurs, and the conditions are met.

add at least one action for the workflow trigger
- within the square brackets in "actions": [ ]
  - type {" to add the curly bracket and apostrophe pair {""}

In the JSON schema dropdown, action is selected by default. This default action is to send an email

cdmc_codeditor_trigger_actions_defaultaction_jsonschema.png

The first element in the JSON schema is action. By default, this adds an action to send a custom email notification. For other actions, delete the "send-email" and add " " to display the schema for other actions.

choose the action option to send an email

Each action has a JSON schema. These must be added in the defined order for the action.

add the recipients for your email
- after "send-email" code
  - add a comma and apostrophes ""
  - choose recipients array

add one or more recipients as a comma-separated list within the square brackets [ ] in "recipients": [ ]

Recipients can be one or more of userID, groupID or groupName, email address, Confluence smart data @creator, @lastUpdatedby, @watchers, and user and group workflow parameters. If adding more than one Confluence user or group, these are added to the list within curly brackets { }. For example

"recipients":[ "@creator", {"user": "userXYZ"}, {"user":"userLMN"}, {"group": "group123"}, {"group": "group789"}]

add a title for the email
- after the recipients closing square bracket
  - add a comma and apostrophes ""
  - scroll down the JSON schema dropdown and choose notifications object

Notifications are added, but it has an empty value.

cdmc_codeeditor_extract_notifications_object_added_noparameters.png

We need to add parameters and values for the notification. The subject, title, and body of our email notification are as follows:

"notification": {"title": "Rejected content", "subject": "Page rejected", "body": "Please check this page and triage"}

Save the updated workflow template in the editor.

The saved workflow is formatted in a tab code.

cdmc_codeeditor_workflowschema_sendemailtrigger_onchangestate_event.png

You can add more actions by adding more "action": attributes as a comma-separated list within the "actions":[ ] array.

In our example below, we have added the "action": "set-message" with its parameters:

after the closing curly bracket for the "action": "send-email" for each additional action
before the closing square bracket of the "actions":

cdmc_codeeditor_workflowschema_sendemailtrigger_onchangestate_event_secondaction_setmessage.png