States
- Robert Alexander Marshall
Overview
States act like milestones in your workflow – key stages of your process where something has to happen.
States are always implemented with the state macro.
State names are case sensitive. There are also a number of reserved characters that cannot be used in a workflow state name such as = # @ { | [.
Example
Let's assume we've got a really simple content production process where content is edited, then it goes through a review, and if the review is approved the content is published.
{workflow:name=Three states}
{state:Editing}
{state}
{state:Review}
{state}
{state:Publish}
{state}
{workflow}
The boxes in the diagram above are the states, and the lines between them are Transitions.
Transitions
States can handle several common Transitions directly, namely:
submit– a direct transition to one stateupdated– an automatic transition which occurs when content is editedapprovedandrejected– transitions triggered by completion of Reviewsexpired– triggered when a state expires – see Expiry Datescompleted– triggered when the last remaining task is completed – see Tasks
For approved, rejected and submit transitions Workflow Parameter can also be required to be entered.
Further information: Transitions.
Reviews
You can add Reviews to states. When the workflow enters the state, the workflow popup displays options for content reviews.
Reviewers must decide whether to approve or reject the content, and once they are in agreement the state will transition to the destination state for the approved or rejected decision as applicable.
Further information: Reviews.
Require parameter
A state can be configured to require the setting of one or more workflow parameter values. The value must be set before a transition into the state can occur. The workflow popup will display a warning for the transition in any state that has this state as a destination.
The Reviewed state in the markup below would require the setting of the value of the workflow parameter pagefield1 before a transition can occur into the Reviewed state.
{workflowparamter:pagefield1|edit=true}
{workflowparameter}
{state:Draft|submit=Reviewed}
{state}
{state:Reviewed|requiredparams=pagefield1}
{state}In our example, the transition option is to a single state from the Draft state to the Reviewed state the Submit button displays a warning icon.
Choosing the Submit button opens a text box to enter the value of the required workflow parameter.
The required parameters for entering a state will only be prompted if a user is performing a workflow action such as approving/rejecting content or making state selection. If a state is transition is actioned by a trigger, like a page update, the required parameter check for the destination state will not be carried out.
Required parameters can be added to a state using the state editor in workflow builder.
Workflow parameters added to the workflow will be available as options to the dropdown menu.
Tasks
Tasks can be created automatically when a workflow enters a state, and states can automatically transition when tasks are completed.
In the example, a task to Check links is created when entering the Review state, and when that task is completed a transition will occur to the Publish state.
{workflow:name=Tasks}
{state:Editing}
{state}
{state:Review|completed=Publish}
{task:Check links}
{state}
{state:Publish}
{state}
{workflow}For the task to be created, the state must be transitioned to from another state; it must be entered. When a workflow is first applied to content, the initial state is not entered and thus any tasks it contains won't be created.
Final state
States can be designated as a "final", Published state for the content.
In the workflow markup, a state is defined as the final state using the final=true parameter.
A state can also be edited in the workflow builder visual editor to set the final parameter by checking the Final state checkbox in the State editor.
When using this feature, called same-space publishing, view-only users only see the most recently published version of content.
Expiry dates
States can be given expiry dates. There are many uses for this, but one of the most interesting is to trigger periodical reviews of published content:
It's a really simple way to ensure that documentation doesn't go stale.
Notifications
By default, page watchers will only be notified if a state expires.
Additional notifications can be added if desired.
Macros
-
pagestatus macro — Display workflow state lozenge
-
set-state macro — Immediately transition to a state
-
set-state-expiry macro — Set state expiry duration
-
state macro — Define workflow states & basic transitions
-
state-selection macro — Specify direct state transitions
-
Events
State transitions and expiry generate events, for example
statechangedpagestatechangednewsstatechangedstateexpired
Events can be used in workflow triggers to set one or more actions.
App configuration
Setting | Where | Notes |
|---|---|---|
State's Task Behaviour | Should incomplete tasks be carried over to the next state during transitions? | |
State Expired Notification | Should page watchers receive a notification when a state expires? |
Examples
-
Add parallel approvals in a state — 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
-
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
-
Customize approval decision buttons — How to change captions of the Approve and Reject buttons created by the
approvalmacro. -
Expiry Dates — States, tasks, and messages can be set to expire on a certain date or after a certain amount of time
-
How can I fast-track a single rejection or a single approval decision — 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
-
-
-
Use attachment events in workflow triggers — Triggering events when attachments are created, updated, or removed.
-
Use blog post events in a workflow trigger — Workflow events associated with blog posts
-
Who can be assigned, or assign users to an approval — Define who can take part in, or be assigned to, a content review.