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. There must be at least one state in every workflow.
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}
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.
See: Transitions
Reviews
You can add Reviews to states. When the workflow enters the state, the Workflow Popup will display 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 approved or rejected state as applicable.
See: Reviews
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}
See: Tasks
Note that tasks cannot be created this way in the initial state (the Editing state in our example).
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.
Publishing
States can be designated as a "final", Published state for the content.
When using this feature, called Same-space publishing, View-only users will only see the most recently published version of content.
See: Publishing
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.
See: Expiry Dates, State expiry date
'Read confirmation' for final states
Final states can be set to request specific users for 'read confirmation' of the published content.
Selected users will receive an email notification. On viewing the page, the user will be see a message asking for them to confirm reading of the content.
The invited user can confirm the reading of the content by choosing the following at the bottom of the page.
Read confirmations are added as a breadcrumb to the page content header.
For multiple user invitations, choose the icon to show completed individual user confirmations and number of outstanding requests.
See: read-ack macro
Notifications
By default, page watchers will only be notified if a state expires.
Additional notifications can be added if desired – see Notifications.
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, which can be used to Trigger Actions.
statechangedpagestatechangednewsstatechangedstateexpired
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
-
Adding Multiple Reviews — Add multiple reviews to a content review, set assignee requirements and review dependencies, list ordering
-
Adding page activity to email — Include page activity report, or a link to it, in email notifications
-
Administrator state override — Administrators can force a workflow in to a different state
-
-
-
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
-
-
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 — How to require everyone to Approve, but only need one person to Reject
-
-
-
-
-
Message notification styles — Test the
styleparameter of the{set-message}macro -
Reviewer Authentication — This example shows how to authenticate reviewers during a content review.
-
State expiry dates — Using state expiry dates, defining them with metadata, and making them editable
-
-
Template Comments — Examples of where the
{comment}macro can be used in your template markup. -
Transitions — Transitions create the routes between states
