state macro

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	Default	Notes	Ver
unnamed first parameter or `name`		Name of the workflow state: Within a `{workflow}` macro, each `{state}` macro must be given a unique name 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: Content by label There is no content with the specified labels
Transitions Define the name of target state for common transitions. If required, custom transitions can be implemented by using Events to `{trigger}` a `{set-state}` transition.
`approved`	see notes	If a content review is Approved, which state should the workflow transition to? Note: If not specified, but `rejected` is specified, an "Approve" button will still appear during the review and will Content by label There is no content with the specified labels Concepts: Transitions, Reviews
`rejected`	see notes	If a content review is Rejected, which state should the workflow transition to? Note: If not specified, the content review won't get a "Reject" button. Content by label There is no content with the specified labels Concepts: Transitions, Reviews
`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: `hideselection` parameter, `{state-selection}` macro Content by label There is no content with the specified labels Concepts: Transitions
`updated`		If the associated content is edited (updated), which state should the workflow transition to? Moving the page will not trigger the `updated` transition (v4.5+) – you can use the `pagemoved` event if you require such functionality. Link updates due to moving pages (eg. to another space) or renaming of other pages will not trigger the `updated` transition (v4.5+) Content by label There is no content with the specified labels Concepts: Transitions
`updated`		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.
Expiry States 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 `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 be used with or without the `duedate` parameter. See Editing duedate section below parameter table for more information. Content by label There is no content with the specified labels Concepts: Expiry Dates	4.5+
`duedate`		If defined, the state will be given an expiry date. Format can be either: Explicit date in the format: `YYYY-MM-DD HH:mm` (v4.12+) ISO 8601 Duration Period See Expiry Dates for more information Supports Value References Note: The due date will be logged in the Activity Report - Content when the state is entered (v4.5.1+) Content by label There is no content with the specified labels 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). Content by label There is no content with the specified labels Concepts: Transitions, Expiry Dates	3.2+
`expired`		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.	3.2+
Tasks Want to add tasks automatically when a state is transitioned to? See: `{task}` 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. Content by label There is no content with the specified labels 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(s) in your workflow is a final, published state. See also: Same-space publishing and Status Indicator Circles.
`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. Content by label There is no content with the specified labels Concepts: Publishing, Roles and Permissions
`final`	`false`	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 `final` parameter must be removed. Content by label There is no content with the specified labels Concepts: Publishing
`versioncompleted`	`false`	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 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 colour specifications will default to Grey. See also: Confused States - Grey Circle. Tip: Triadic colour schemes yield good visual colour segregation. Content by label There is no content with the specified labels	5.1+
`description`		Add a plain text description to the Workflow Popup when this state is active. Content by label There is no content with the specified labels
`hidefrompath`	`false`	Should the state be hidden from the Progress Tracker bar on the 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. Content by label There is no content with the specified labels See also: `progresstracker` parameter on `{workflow}` macro.
`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: `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 to specify which direct state transition buttons should be shown. Content by label There is no content with the specified labels Concepts: Transitions	3.0+
Deprecated Parameters These parameters are either deprecated or obsolete and should no longer be used.
~~`assignable`~~	~~`false`~~	OBSOLETE Use `assignable` parameter on `{approval}` macro instead.	3.2.2 ↓ 4.2.1
~~`style` or `cssstyle`~~ `class` or `cssclass`		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

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

All examples

Content by label

There is no content with the specified labels

Content

Space Tools

state macro

Overview

Where to use it?

Parameters

Transitions

Expiry

Tasks

Publishing

User Interface

Deprecated Parameters

Editing duedate

Events

Example

All examples

See also