Page Comparison

...

Table of Contents

maxLevel	2
minLevel	2
absoluteUrl	true
exclude	Overview
type	flat
separator	pipe

Overview

Excerpt

hidden	true

Define workflow states & basic transitions

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.

...

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 or `name`			Name of the workflow state

:

Within

within a

{

workflow

}

macro, each

{

state

}

macro must be given a unique name

The

the name can use any character set supported by your Confluence server – except some reserved characters

.

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:

Filter by label (Content by label)

showLabels	false
showSpace	false
sort	title
excerptType	simple
cql	label = "body-state" and label = "macro" and space = currentSpace ( )

Transitions

Define the name of target state for common transitions.

If required, custom transitions can be implemented by using Events to

{

trigger

} a {

a set-state

} transition

transition.

approved

see notes

If a content review is Approved, which state should the workflow transition to?

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label = "parameter-approved" and label = "example" and space = currentSpace ( )

Concepts: Transitions, Reviews

rejected

see notes

If a content review is Rejected, which state should the workflow transition to?

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label = "parameter-rejected" and label = "example" and space = currentSpace ( )

Concepts: Transitions, Reviews

submit

Define a single state to transition to from the current state.

Note: This

This causes a drop-down menu to appear in the

Workflow Popup

workflow popup to allow direct transition to that state.

Expiry

States can be set to expire on either an explicit date, or, more commonly, a time period from

when

the occurrence of the transition to the state

was transitioned in to

.

If a state expires while it is active, the state specified by the expired parameter, if present, will be transitioned to.

Macros:

{

set-state-expiry

}

Events: stateexpired

changeduedate

false

Can users set and/or change the duedate for this state?

true – yes, they can change it – see: State expiry date
false – no, they can't

Note: Can

Can be used with or without the duedate parameter. See Editing duedate section below parameter table for more information.

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label = "parameter-changeduedate" and label = "example" and space = currentSpace ( )

Concepts: Expiry Dates

4.5+

duedate

If defined, the state will be given an expiry date.

Format

format can be either:

Explicit

- explicit date in the format: YYYY-MM-DD HH:mm (v4.12+)
- ISO 8601 Duration Period
supports Value References

See Expiry Dates for more information

Supports Value References

Note: The

.

The due date will be logged in the Activity Report - Content when the state is entered (v4.5.1+).

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label = "parameter-duedate" and label = "example" and space = currentSpace ( )

Concepts: Expiry Dates

3.2+

expired

The state to change into if the page expires after its duedate (regardless of how the due date was set).

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label = "parameter-expired" and label = "example" and space = currentSpace ( )

Concepts: Transitions, Expiry Dates

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.

Tasks

Want to add tasks automatically when a state is transitioned to? See:

{

task

} macro

macro.

When all tasks are completed, the state specified by the completed parameter, if present, will be transitioned to.

Events: taskcreated, taskassigned, taskcompleted and taskexpired.

completed

The state to change into if all the tasks in the state are completed.

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label = "parameter-completed" and label = "example" and space = currentSpace ( )

Concepts: Transitions, Tasks

taskable

false

Whether or not tasks can be manually defined in this state via the Tasks button.

Concepts: Tasks

Publishing

Specify which state in your workflow is a final, published state.

final

false

Should content in this state be considered "Published"?

true – yes, this state is published
false – no, this state is draft (unpublished)

Setting to true will cause all other non-final states in the workflow to be treated as drafts (unpublished content). By default, users with view-only permission can not see draft content, they can only see the most recently published version of content.

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label = "parameter-final" and label = "example" and space = currentSpace ( )

Concepts: Publishing, Roles and Permissions

If the updated parameter is applied to a final=true state, the

Workflow Popup

workflow popup will display a message about the content going through an approvals process before being published, and

an "

the Activity Report

"

button will also be shown.

versioncompleted

false

When using this parameter, the final parameter must be removed.

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label = "parameter-versioncompleted" and label = "example" and space = currentSpace ( )

Concepts: Publishing

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 Interface

The following parameters can be used to customise the user interface associated with workflow states.

colour

By default, states are coloured as described in State Status Indicator Circles, namely:

Blue – there is no final=true state in the workflow
Orange – there is a final=true state, but the current state isn't that state
Green – the current state is final=true

If desired, you can override the colour of individual states by specifying a colour in one of the following formats:

#rrggbb – Hexadecimal representation of RGB (Red, Green, Blue) color space – see: Color Picker
name – A valid HTML Color Name

Note: Invalid

Invalid colour specifications will default to Grey. See also: Confused States - Grey Circle.

Tip:

Triadic colour schemes

yield

yield good visual colour segregation.

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label in ( "parameter-color" , "parameter-colour" ) and label = "example" and space = currentSpace ( )

5.1+

description

Add a plain text description to the

Workflow Popup

workflow popup when this state is active.

Supports Value References.

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label = "parameter-description" and label = "example" and space = currentSpace ( )

hidefrompath

false

Should the state be hidden from the Progress Tracker bar on the

Workflow Popup

workflow popup?

true – yes, hide it
false – no, show it

Note: The state will still appear in the tracker bar when the workflow is in that state.

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label = "parameter-hidefrompath" and label = "example" and space = currentSpace ( )

See also: progresstracker parameter on

{

workflow

} macro

macro.
`hideselection`		`false`	By default, direct state transition buttons (to every other state in the workflow) will be added to the

Workflow Popup

workflow popup, unless you specify any of the following parameters: approved, rejected, submit, updated, expired or completed.

If none of those parameters are specified, should the default buttons be hidden?

true – hide default state transition buttons
false – show default state transition buttons, if applicable

Alternatively, you can use a

{

state-selection

} macro

macro to specify which direct state transition buttons should be shown.

Filter by label (Content by label)

showLabels	false
max	6
showSpace	false
sort	title
cql	label = "macro-state" and label = "parameter-hideselection" and label = "example" and space = currentSpace ( )

Concepts: Transitions

3.0+

Deprecated Parameters

These parameters are either deprecated or obsolete and should no longer be used.

assignable

false

Status

subtle	true
colour	Red
title	Obsolete

Use assignable parameter on

{

approval

} macro

macro instead.

3.2.2
↓
4.2.1

style or cssstyle

class or cssclass

Status

subtle	true
colour	Red
title	Obsolete

Use colour parameter instead.

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:

statechanged
pagestatechanged
newsstatechanged

Example

Code Block

language	text	theme	RDark

{workflow:name=States}
   {state:Start|submit=Stop}
   {state}
   {state:Stop|submit=Start}
   {state}
{workflow}

All examples

Filter by label (Content by label)

showLabels	false
max	500
showSpace	false
sort	title
excerptType	simple
cql	label = "macro-state" and label = "example" and space = currentSpace ( )

Versions Compared

Old Version 5

New Version 6

Key

Overview

Parameters

Transitions

Expiry

Tasks

Publishing

User Interface

Deprecated Parameters

Editing duedate

Events

Example

All examples

See also