Overview
The state macro is used to define a state in a workflow macro. Every workflow requires at least one state macro. State macros are used to automatically set tasks and approvals on a page.
Where to use it?
Required – at least one.
One or more {state} macros can be put in a {workflow} macro.
Parameters
| Parameter | Required | Default | Notes | Ver |
|---|---|---|---|---|
unnamed first parameter |
| Name of the workflow state:
In addition to being used for transitions, event triggers, etc., the state name is also shown in many aspects of the user interface and reporting. | ||
| macro body | Can be empty, or one or more of the following macros:
| |||
TransitionsDefine the name of target state for common transitions. If required, custom transitions can be implemented by using Events to | ||||
| see notes | |||
| see notes | |||
submit | Define a single state to transition to from the current state. Note: This causes a drop-down menu to appear in the Workflow Popup to allow direct transition to that state. See also:
| |||
| If the associated content is edited (updated), which state should the workflow transition to?
| |||
If used on a state that is final=true (published), the Workflow Popup will show a message about the content having gone through an approval process and a button linking to the Activity Report will be displayed. | ||||
| Require a given list of workflow parameters to be set before transitioning into this state.
| |||
ExpiryStates can be set to expire on either an explicit date, or, more commonly, a time period from when the state was transitioned in to. If a state expires while it is active, the state specified by the Events: | ||||
changeduedate | false | Can users set and/or change the
Note: Can be used with or without the
| 4.5+ | |
duedate | If defined, the state will be given an expiry date.
Note: The due date will be logged in the Activity Report - Content when the state is entered (v4.5.1+)
| 3.2+ | ||
expired | The state to change into if the page expires after its
| 3.2+ | ||
If you're viewing the page when expiry occurs, you won't see the state update until you refresh the page. Also, if the expiry date has already passed when entering the state, the transition won't occur. For best results always use an ISO 8601 duration rather than a specific date. | ||||
TasksWant to add tasks automatically when a state is transitioned to? See: When all tasks are completed, the state specified by the Events: | ||||
completed | The state to change into if all the tasks in the state are completed.
Filter by labelThere are no items with the selected labels at this time. | |||
|
| Whether or not tasks can be manually defined in this state via the Tasks button. | ||
PublishingSpecify which state in your workflow is a final, published state. See also: Same-space publishing and State Status Indicator Circles. | ||||
final | false | Should content in this state be considered "Published"?
Setting to
| ||
If the updated parameter is applied to a final=true state, the Workflow Popup will display a message about the content going through an approvals process before being published, and an "Activity Report" button will also be shown. | ||||
versioncompleted |  | false | When using this parameter, the
Filter by labelThere are no items with the selected labels at this time. | |
| This parameter is exclusively used for integration with the K15t Scroll Versions app, and is must be used for workflows in spaces where the Scroll Versions app is being used. | ||||
User InterfaceThe following parameters can be used to customise the user interface associated with workflow states. | ||||
| By default, states are coloured as described in State Status Indicator Circles, namely:
If desired, you can override the colour of individual states by specifying a colour in one of the following formats:
Note: Invalid colour specifications will default to Grey. See also: Confused States - Grey Circle. Tip: Triadic colour schemes yield good visual colour segregation.
| 5.1+ | ||
description | Add a plain text description to the Workflow Popup when this state is active. Supports Value References.
| |||
hidefrompath | false | Should the state be hidden from the Progress Tracker bar on the Workflow Popup?
Note: The state will still appear in the tracker bar when the workflow is in that state.
See also: | ||
hideselection | false | By default, direct state transition buttons (to every other state in the workflow) will be added to the Workflow Popup, unless you specify any of the following parameters: If none of those parameters are specified, should the default buttons be hidden?
Alternatively, you can use a
| 3.0+ | |
Deprecated ParametersThese parameters are either deprecated or obsolete and should no longer be used. | ||||
assignable | false | OBSOLETE Use | 3.2.2 | |
| OBSOLETE Use | 3.0 ↓ 4.0.2 | ||
Editing duedate
The duedate and changeduedate parameters can be used on their own or together. The following table describes what will happen with each possible combination:
duedate | changeduedate | Description |
|---|---|---|
| not set | false | State will not have an expiry date nor can users add an expiry date. |
| set | false | State will have an expiry date based on the duedate parameter that the user cannot change. |
| not set | true | State will not initially have an expiry date, but the user can add an expiry date. |
| set | true | State will initially have an expiry date based on the duedate parameter, but the user can change the expiry date. |
Events
The following Events are applicable to transitions between states:
statechangedpagestatechangednewsstatechanged
Example
{workflow:name=States}
{state:Start|submit=Stop}
{state}
{state:Stop|submit=Start}
{state}
{workflow}
All examples
-
Adding Multiple Reviews — Add multiple reviews to a content review, set assignee requirements and review dependencies
-
Adding page activity to email — Include page activity report, or a link to it, in custom email notifications
-
-
-
Assignment Examples — Define who can take part in, or be assigned to, a content review.
-
Attachment events — Triggering events when attachments are created, updated or removed.
-
Blog Post Events — Workflow events associated with blog posts
-
Communardo Metadata for Confluence app — Using the Communardo metadata as value references in a workflow - including use in a custom condition for a trigger macro
-
Customise Approval Buttons — How to change captions of the Approve and Reject buttons created by the
{approval}macro. -
Expiry Dates — States, tasks, and messages can be set to expire on a certain date or after a certain amount of time
-
Fast-tracked Rejections and Approvals — How to require everyone to Approve, but only need one person to Reject
-
Message notification styles — Test the
styleparameter of the{set-message}macro -
Require Parameters on a state transition — Require workflow parameter values to be set before moving into a workflow state.
-
State expiry dates — Using state expiry dates, defining them with metadata, and making them editable
-