Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
maxLevel2
minLevel2
absoluteUrltrue
excludeSee also
typeflat
separatorpipe

Overview

Excerpt
hiddentrue

Define the milestones and key stages in your workflow

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

state macro.

Info

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.

Code Block
theme
languagetextRDark
{workflow:name=Three states}
   {state:Editing}
   {state}
   {state:Review}
   {state}
   {state:Publish}
   {state}
{workflow}
Image Modified

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 state

  • updated – an automatic transition which occurs when content is edited

  • approved and rejected – transitions triggered by completion of Reviews

expired  –
  • expired  – triggered when a state expires – see Expiry Dates

completed  –
  • completed  – 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
Info

Further informationTransitions.

Reviews

You can add Reviews to states. When the workflow enters the state, the 

Workflow Popup will display

workflow popup displays options for 

Content Image Removed
Image Added

Reviewers must decide whether to approve or reject the content, and once they are in agreement the state will transition to

the 

the destination state for the approved or rejected

 state

 decision as applicable.

See
Info

Further informationReviews.

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.

Code Block
{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 

the Submit

 button

 button displays a warning icon.

Image Removed
Image Added

Choosing

the 

the Submit

 button

 button opens a text box to enter the value of the required workflow parameter.

Image Removed
Image Added

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.

Info

Once a parameter value has been set in a workflow it will not be prompted for again unless the saved value is removed.


Required parameters can be added to a state using the state editor in workflow builder.

Image Removed
Image Added

Workflow parameters added to the workflow will be available as options to the dropdown menu.

Info

Further information: Require Parameters.

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.

Code Block
languagetext
themeRDark
{workflow:name=Tasks}
   {state:Editing}
   {state}
   {state:Review|completed=Publish}
      {task:Check links}
   {state}
   {state:Publish}
   {state}
{workflow}
See
Info

Further informationTasks

Note that tasks

.

Info

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


Final state

States can be designated as a "final", Published state for the content.

Image Removed

Image Added

In the workflow markup, a state is defined as the final state using the final=true parameter.

Code Block
languagetext
{workflow:name=Tasks}
   {state:Editing}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review}
   {state}
   {state:Published|final=true}
   {state}
{workflow}

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 

SameView will only

 only see the most recently published version of content.

Info
See

Further informationPublishing.

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
Info

Further informationExpiry DatesState expiry date.

Notifications

By default, page watchers will only be notified if a state expires.

Additional notifications can be added if

desired – see 

desired.

Info

Further information: Notifications.

Macros

Filter by label (Content by label)
showLabelsfalse
max100
showSpacefalse
sorttitle
excerptTypesimple
cqllabel = "concept-states" and label = "macro" and space = currentSpace ( )

Events

State transitions and expiry generate 

Events, which can be used to Trigger Actions.

events, for example

  • statechanged

  • pagestatechanged

  • newsstatechanged

  • stateexpired

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

Filter by label (Content by label)
showLabelsfalse
max100
showSpacefalse
sorttitle
excerptTypesimple
cqllabel = "macro-state" and label = "example" and space = currentSpace ( )

See also

User Guide

::::

{state} macro