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: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 | 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.). |
| No |
| The state to change into if all the defined approvals are approved. |
| No |
| The state to change into if all the defined approvals are rejected. |
| No |
| The state to change into if the page is updated (edited). |
| 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. |
| No |
| The state to change into if the page expires based on |
| No |
| The state to change into if all the tasks in the state are completed |
| No |
| If set to |
| No |
| The description to be shown in the page's state box. |
| No |
| By default, if |
| No |
| Whether or not tasks can be manually defined in this state via the Tasks button. |
| 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 |
|
1 month |
|
1 day |
|
1 hour |
|
1 minute |
|
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. |