Purpose

The state macro is used to define a state in a workflow. Every workflow requires at least one state macro. State macros are used to automatically set tasks and approvals on a page.

Syntax

{state} Syntax

{state:state_name[|approved=approved_state][|rejected=rejected_state][|updated=updated_state][submit=submitted_state][|expired=expired_state][|duedate=ISO8601_duration][|completed=completed state][|final=true/false][|hideselection=true/false][|taskable=true/false][|hidefrompath=true/false]}
   <None or one state-selection macro>
   <None, one or more approval macros>
   <None, one or more task macros>
{state}

Parameters

Parameters	Mandatory	Default	Description
unnamed first parameter or `name`	Yes		Name of the state. Names must be unique withing a state macro and can use any character set supported by Confluence expect the special characters used by the workflow syntax and Confluence (e.g. {. \|}, ,\|, etc.).
`approved`	No		The state to change into if all the defined approvals are approved.
`rejected`	No		The state to change into if all the defined approvals are rejected.
`updated`	No		The state to change into if the page is updated (edited).
`submit`	No		The state to change into if the page is submitted (via the Accept button). Only applicable if there are no approvals in the state.
`expired`	No		The state to change into if the page expires based on `duedate` time range or the user set expiry date from `changeduedate`. For more details, please see Expiry Date below.
`completed`	No		The state to change into if all the tasks in the state are completed
`final`	No	`false`	If set to `true`, when a page or blog post reaches this state, its version is marked as Published. Used for same space publishing. Refer to Understanding the Comala Workflow Engine for more information on different publishing options.
`description`	No		The description to be shown in the page's state box.
`hideselection`	No	`false`	By default, if `rejected`, `approved`, `updated`, `submit`, `expired` or `completed` parameters are not set, then the engine will allow changing the state to any other state. If this value is set to `true` then no state selections are allowed. See also state-selection.
`taskable`	No	`false`	Whether or not tasks can be manually defined in this state via the Tasks button.
`duedate`	No		Duration of time before the state expires following the ISO 8601 standard for duration or exact date the state should expire. For more details, please see Expiry Date below.
changeduedate	No	`false`	If set to `true`, the due date of the state can be adjusted by users. Can be used with or without `duedate`. For more details, please see Expiry Date below.
`hidefrompath`	No	`false`	If set to `true,` this state will be hidden from the progress tracker for the workflow.
`colour`	`No`		Colour of the state in hexadecimal value (e.g., #ff0000) or simple colour names (e.g., red). Grey if the value is invalid. Default colors for states: Blue if there is not a final state in the workflow; Green if the state is set as final; Yellow if the workflow has a final state which is not the current state
macro's body	No		Can be empty, the state-selection macro, or a combination of task and/or approval macros.

State Transition

A page's state transitions based upon on of the parameters above (for example, approvals given or rejected, tasks completed, expiration date, etc.), or alternatively, be changed in a {trigger} macro using the {set-state} macro.

Expiry Date

The duedate parameter can take a duration value based on the time the state was created, or an exact date.

Duration examples:

Duration	Value to use
1 year	`P1Y`
1 month	`P1M`
1 day	`P1D`
1 hour	`PT1H`
1 minute	`PT1M`

These values can be combined to create expiry date of any duration, such as P1DT12H15M for a duration of 1 day, 12 hours and 15 minutes.

To set the exact date use the following format: YYYY-MM-dd HH:mm

The duedate value can also be specified using a value reference that is read when the state is created.

Using duedate and changeduedate

The duedate and changeduedate parameters can be used on their own or together in the same state. 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.

Content

Space Tools