JSON Trigger actions

"change-state"

The trigger action "change-state" causes a change of the state to the specified state if the provided parameters are valid.

• action (change-state)

  • state❗️ destination workflow state for the action

    • state must be a state in the workflow

    • state names are case-sensitive

❗️ Mandatory parameter

state parameter

• state parameter must be included with a valid value for the destination state

Example trigger code

"triggers":
[
	{"event": "on-change-state",
	"conditions":
	[
		{"final":true}
	],
	"actions":
	[
		{"action": "change-state",
			"state": "Archive"}
	]}
]

The example trigger listens for the workflow's change of state to the final state and immediately moves the workflow to the Archive state.

Another use of the trigger action is to move from the workflow Review state, which contains an approval, immediately on a reviewer rejection, to the Editing state. This can be used to fast-track a single rejected decision, for example, when multiple reviewers are assigned to an approval.

"triggers":
[
	{"event": "on-reject",
	"conditions":
	[
		{"state":"Review"}
	],
	"actions":
	[
		{"action": "change-state",
			"state": "Editing"}
	]}
]

"publish-page"

When added to a workflow trigger, publishes a single page on a workflow event to a different space using Comala Publishing for Cloud app.

• action (publish-page)

For the workflow shown below:

Adding the following trigger publishes the page on the state change to the First Published state.

"triggers":
[
	{"event": "on-change-state",
	"conditions":
	[
		{"state":"First Publish"}
	],
	"actions":
	[
		{"action": "publish-page"}
	]}
]

The publish-page action macro publishes the content in the target space on the state change event.

The Comala Publishing breadcrumb is updated on the draft page header and on the target space page.

The target space for publishing the page is configured in the Comala Publishing space settings. Publishing can also occur based on the configuration of the Comala Publishing app, such as a space publishing action or a single-page publishing.

"approve"

The trigger action "approve"sets an approved decision for a named approval if the provided parameters are valid.

• action (approve) 

  • approval Name of the Approval to be approved. If not specified, the default approval^† is used

  • user❗️ Atlassian userID of the approver

❗️ Mandatory parameter

user

The trigger action must define a value for the user parameter for the approve action to take place.

† Default approval

If no approval name is specified in the trigger action, the default approval is the approval in the state named in the trigger event condition.

If the state has multiple approvals, the default approval is the first approval listed in the state's JSON markup.

Example trigger code

"triggers":
[
	{"event": "on-change-state",
	"conditions":
	[
		{"final":true}
	],
	"actions":
	[
		{"action": "approve",
			"approval": "Sign-off",
			"user":"5d52a37ef0f22a0da2d6f070"}
	]}
]

The Atlassian user Identification Number (userId) is visible in the URL when viewing the User Profile.

o

"reject"

The trigger action "reject" sets a rejected decision for a named approval if the provided parameters are valid.

• action (reject) 

  • approval Name of the approval to be rejected. If not specified, default approval^† is used

  • user ❗️ Atlassian userID of the rejector

❗️ Mandatory parameter

user

The trigger action must define a value for the user parameter for the reject action to take place.

†Default approval

If the trigger action does not specify a named approval, the action uses the default approval in the workflow.

The default approval is the approval in the state named in the trigger event condition. If there are multiple approvals in the state, the default approval is the first approval listed in the JSON markup.

Example trigger code

"triggers":
[
	{"event": "on-change-state",
	"conditions":
	[
		{"final":true}
	],
	"actions":
	[
		{"action": "reject",
			"approval": "Sign-off",
			"user":"5d52a37ef0f22a0da2d6f070"}
	]}
]

The Atlassian user Identification Number (userId) is visible in the URL when viewing the User Profile.

o

"assign" and "unassign"

The trigger action "assign" assigns a user to a named approval.

• action (assign) 

  • approval - the name of the approval to assign. If not specified, the default approval^† is used

  • assigner - Atlassian  userID for the assigner (if no value is added the app add-on user is the assigner for the action)

  • user ❗️ Atlassian userID for the assignee (accepts one value only)

  • group❗️ Atlassian groupID or groupName for assignees (accepts one value only)

  • comment - comment for the assignation operation

Only one user and one group can be assigned in a single "assign" action. You cannot add multiple values for the user or group parameters.

❗️ Mandatory parameters

user and group parameters for assignees

At least one value must be added for an assignee (using either user or group). The user parameter value must be specified unless a group is specified using the group parameter instead.

† Default approval

If no approval name is specified in the trigger action, the default approval is the approval in the state named in the trigger event condition.

If the state has multiple approvals, the default approval is the first approval listed in the state's JSON markup.

Example trigger code

"triggers":
[
	{"event": "on-change-state",
	"conditions":
	[
		{"state":"Review"}
	],
	"actions":
	[
		{"action": "assign",
			"approval": "Triagereview",
			"user": "5d52a37ef0f22a0da2d6f070",
			"group": "qa_reviewers"}
	]}
]

Notes

When assigning a reviewer, the user parameter only accepts one userID value.

The Atlassian User Identification Number (userId) is visible in the URL when viewing the User Profile.

To assign multiple users as reviewers, you must use a Confluence group for the reviewers instead of a single user by using the group parameter, for example:

• "group":"qa_reviewers"

• where "qa_reviewers" is a Confluence group name.

The trigger action "unassign" removes a user or members of a Confluence group from a named approval.

"set-expiration"

"set-expiration" sets an expiry period for a state.

• action (set-expiration)

  • dueDate❗️ Due date

    • period in ISO 8601 format

    • or specific date (in Confluence preferred user format for the site)

❗️ Mandatory parameter

dueDate

A value must be added for the due date.

Example trigger code

"triggers":
[
	{"event": "on-change-state",
	"conditions":
	[
		{"final":true}
	],
	"actions":
	[
		{"action": "set-expiration",
			"dueDate": "P6M"}
	]}
]

The "dueDate" period is set using ISO 8601 format. For example, "P6M3W5D" will be 6 months, 3 weeks, and 5 days from the date of transition into the state. This overrides any existing expiration periods.

"clear-expiration"

The "clear-expiration" action removes an existing workflow state expiration period.

• action (clear-expiration )

"triggers":
[
	{"event": "on-change-state",
	"conditions":
	[
		{"final":true}
	],
	"actions":
	[
		{"action": "clear-expiration"}
	]}
]

"set-message"

The trigger action "set-message" creates a message notification and can include a message title and a body.

• action (set-message) 

  • type ❗️ Indicator of the level of the message

    • info

    • warning

    • error

  • title  For adding a title to the message

  • body❗️ For adding the content for the body of the message

❗️ Mandatory parameters

type

The "type" parameter value must be included.

body

The "body" parameter value must be included.

Trigger example

"triggers":
[
	{"event": "on-change-state",
	"conditions":
	[
		{"state":"Expired"}
	],
	"actions":
	[
		{"action": "set-message",
			"type": "info",
			"title": "Stale content",
			"body": "Content may be out of date"}
	]}
]

The above trigger listens for a state change event to the Expired state and displays an on-screen message notification on the change of state.

If the "set-messsage action parameter is "type":"warning, the displayed notification is:

If the "set-messsage action parameter is "type":"error, the displayed notification is:

"clean-messages"

The "clean-messages" action removes all messages (set by a “set-message" trigger action) on the content.

• action (clean-messages) 

Example trigger code

"triggers":
[
	{"event": "on-change-state",
	"conditions":
	[
		{"final":true}
	],
	"actions":
	[
		{"action": "clean-messages"}
	]}
]

"remove-restrictions"

The trigger action  "remove-restrictions" removes content view and edit restrictions for all users and groups.

• action (remove-restrictions)

  • contentId - the content id of the page to remove page-level restrictions

    • if no content id is included, the current page contentId is used

Example trigger code

A typical use of this trigger action is to remove all view and edit restrictions from the final state in a workflow.

"triggers":
[
	{"event": "on-change-state",
	"conditions":
	[
		{"final":true}
	],
	"actions":
	[
		{"action": "remove-restrictions"}
	]}
]

In the document management dashboard, a space administrator can configure the space to remove all page-level restrictions on transitioning to the active workflow’s final state.

"send-email"

The trigger action "send-email" sends a custom email to one or more specified recipients. 

• action (send-email)

• recipients (array) ❗️Recipients to send the email to (at least one recipient value must be added). A comma-separated list of one or more recipients is added using a combination of:

  • one or more email addresses

  • one or more users using {"user"="userID"} specifying the Atlassian userID.†

  • one or more user groups {"group":"groupID"} specifying Atlassian groupID‡ or the Atlassian groupName‡

  • one or more user type workflow parameters using @userTypeParameterName@(see workflow parameter references)

  • one or more group type workflow parameters using @groupTypeParameterName@(see workflow parameter references)

  • One or more of the following Confluence value references

    • @watchers (set at document level only)

    • @lastUpdatedBy

    • @creator

• notification (object) ❗️ Notification holder. This includes the following parameters as a comma-separated list within curly brackets:

  • "title" (optional)

  • "subject" ❗️

  • "body" ❗️

You can embed any of the following as part of the text value in the "title", "subject", and "body" parameters

• ${content.title} - inserts the name of the page or blog post

• ${content.link} - inserts the link of the page or blog post

• ${content.space} - inserts the name of the space

❗️Mandatory parameters

recipients

At least one value for recipients must be included

notification

The "notification" holder is required. This must include both

• "subject"

• "body"

Example trigger code

"triggers":
[
  {"event": "on-change-state",
    "conditions":
    [
      {"state": "Review"}
    ],
    "actions":
    [
      {"action": "send-email",
        "recipients":
        [
          "@creator",
          "@watchers",
          "@lastUpdatedBy",
          "@user_type_parameter_1@",
          "@user_type_parameter_2@",
          "@group_type_parameter_1@",
          "@group_type_parameter_2@",
          "email_1@email.com",
          "email_2@email.com",
          {"user": "user_ID_1"},
          {"user": "user_ID_2"},
          {"group": "group_ID_1"},
          {"group": "group_ID_2"},
          {"group": "group_Name_1"},
          {"group": "group_Name_2"}
        ],
        "notification":
        {"subject": "${content.title} is In Review State",
          "title": "${content.title} is In Review State",
          "body": "Hello, ${content.link} in the ${content.space} space is in review state."
        }
      }
    ]
  }
]

Related Pages

• JSON Triggers

• JSON Trigger events

• JSON Trigger conditions

• Add a JSON trigger using workflow builder

• Users or groups within a trigger