---
title: "state macro"
canonical: "https://support.appfire.com/space/CDML/649531575/state%20macro"
format: markdown
---
> Macro (aura-html)


## Overview

> Macro (excerpt)
> 
> Define workflow states & basic transitions

The state macro is used to define a state in a [workflow macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649662219). 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649662219).

## Parameters

| Parameter | Required | Default | Notes | Ver |
| --- | --- | --- | --- | --- |
| *unnamed first parameter*   
or `name` | :check_mark: |  | Name of the workflow state<br>- 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859070)<br>In addition to being used for [transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425), [event](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655) [triggers](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859133), etc., the state name is also shown in many aspects of the [user interface](https://appfire.atlassian.net/wiki/spaces/CDML/pages/648907144) and [reporting](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649070833).<br>> ✅ The current workflow state name parameter can be retrieved  a report or third party metadata app/macro by using the `@awpState@` value reference. |  |
| *macro body* |  |  | Can be empty, or one or more of the following macros:<br>> Macro (contentbylabel) |  |
| ## Transitions<br>Define the **name** of target state for common [transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425).<br>If required, custom transitions can be implemented by using **[Events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655)** to [trigger](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859133) a [set-state](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649727251) transition. |
| `approved` |  | *see notes* | If a [content review](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649662337) is Approved, which state should the workflow transition to?<br>> Macro (contentbylabel)<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425), [Reviews](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650153766) |  |
| `rejected` |  | *see notes* | If a [content review](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649662337) is Rejected, which state should the workflow transition to?<br>> Macro (contentbylabel)<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425), [Reviews](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650153766) |  |
| `submit` |  |  | Define a single state to transition to from the current state.<br>:info: This causes a drop-down menu to appear in the [workflow popup](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846) to allow direct transition to that state.<br>See also: `hideselection` parameter, [state-selection macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649826719).<br>> Macro (contentbylabel)<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425) |  |
| `updated` |  |  | If the associated content is edited (updated), which state should the workflow transition to?<br>- moving the page will not trigger the `updated` transition (v4.5+) – you can use the [pagemoved event](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655) 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+)<br>> Macro (contentbylabel)<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425) |  |
| If used on a state that is `final=true` (published), the [workflow popup](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846) will show a message about the content having gone through an approval process and a button linking to the Activity Report will be displayed. |
| `requiredparams` |  |  | Require a given list of workflow parameters to be set before transitioning into this state.<br>- Comma separated list of parameter names
- Workflow parameters must be defined in the existing workflow and have the edit=true condition set to be valid
- Note that users will only be prompted to enter parameters when the workflow transitions via a user action, like an approval or state submission. Internal state changes from triggers will not prompt for the required parameters |  |
| ## Expiry<br>States can be set to expire on either an explicit date, or, more commonly, a time period from the occurrence of the transition to the state.<br>If a state expires *while it is active*, the state specified by the `expired` parameter, if present, will be transitioned to.<br>[Macros](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650151673): [set-state-expiry](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563686)<br>[Events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655): `stateexpired` |
| `changeduedate` |  | `false` | Can users set and/or change the `duedate` for this state?<br>- `true` – yes, they can change it – see: [State expiry date](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649693610)
- `false` – no, they can't<br>:info: Can be used with or without the `duedate` parameter. See **Editing duedate** section below parameter table for more information.<br>> Macro (contentbylabel)<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Expiry Dates](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649890606) | 4.5+ |
| `duedate` |  |  | If defined, the state will be given an expiry date.<br>- format can be either:
  - explicit date in the format: `YYYY-MM-DD HH:mm` (v4.12+)
  - ISO 8601 Duration Period
- supports [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302)<br>See [Expiry Dates](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649890606) for more information.<br>:blue_star: The due date will be logged in the [Activity Report - Content](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650119122) when the state is entered (v4.5.1+).<br>> Macro (contentbylabel)<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Expiry Dates](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649890606) | 3.2+ |
| `expired` |  |  | The state to change into if the page expires after its `duedate` (regardless of how the due date was set).<br>> Macro (contentbylabel)<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425), [Expiry Dates](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649890606) | 3.2+ |
| If you're viewing the page when expiry occurs, you won't see the state update until you refresh the page.<br>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<br>Want to add tasks automatically when a state is transitioned to? See: **[task](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650315819)**[ macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650315819).<br>When all tasks are completed, the state specified by the `completed` parameter, if present, will be transitioned to.<br>[Events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655): `taskcreated`, `taskassigned`, `taskcompleted` and `taskexpired`. |
| `completed` |  |  | The state to change into if all the tasks in the state are completed.<br>> Macro (contentbylabel)<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425), [Tasks](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694408) |  |
| `taskable` |  | `false` | Whether or not tasks can be manually defined in this state via the **Tasks** button.<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Tasks](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694408) |  |
| ## Publishing<br>Specify which state in your workflow is a final, published state.<br>See also: [Same-space publishing](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649794062) and [State Status Indicator Circles](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650152863). |
| `final` |  | `false` | Should content in this state be considered "Published"?<br>- `true` – yes, this state is published
- `false` – no, this state is draft (unpublished)<br>Setting as `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 cannot see draft content, they can only see the most recently published version of content.<br>> Macro (contentbylabel)<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Publishing](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649923873), [Roles and Permissions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650217543) |  |
| If the `updated` parameter is applied to a `final=true` state, the [workflow popup](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846) will display a message about the content going through an approvals process before being published, and the **Activity Report** button will also be shown. |
| `versioncompleted` | :info: | `false` | When using this parameter, the `final` parameter must be removed.<br>> Macro (contentbylabel)<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Publishing](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649923873) |  |
| :info: This parameter is exclusively used for [integration with](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650153358) the [K15t Scroll Versions app](https://marketplace.atlassian.com/plugins/com.k15t.scroll.scroll-versions/server/overview), and is must be used for workflows in spaces where the Scroll Versions app is being used. |
| ## User Interface<br>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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650152863), namely:<br>- <span style="color: #3366ff">**Blue**</span> – there is no `final=true` state in the workflow
- <span style="color: #ff9900">**Orange**</span> – there is a `final=true` state, but the current state isn't that state
- <span style="color: #339966">**Green**</span> – the current state is `final=true`<br>If desired, you can override the colour of individual states by specifying a colour in one of the following formats:<br>- **#rrggbb **– Hexadecimal representation of RGB (Red, Green, Blue) color space – see: [Color Picker](https://htmlcolorcodes.com/color-chart/)
- ***name ***– A valid [HTML Color Name](https://htmlcolorcodes.com/color-names/)<br>:yellow_star: Invalid colour specifications will default to **Grey**. See also: [Confused States - Grey Circle](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649532620).<br>:check_mark: [Triadic colour schemes](https://www.w3schools.com/colors/colors_schemes.asp) yield good visual colour segregation.<br>> Macro (contentbylabel) | 5.1+ |
| `description` |  |  | Adds a **plain text** description to the [workflow popup](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846) when this state is active.<br>> Macro (contentbylabel) |  |
| `hidefrompath` |  | `false` | Should the state be hidden from the Progress Tracker bar on the [workflow popup](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846)?<br>- `true` – yes, hide it
- `false` – no, show it<br>Note: The state will still appear in the tracker bar when the workflow is in that state.<br>> Macro (contentbylabel)<br>See also: `progresstracker` parameter on **[workflow](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649662219)**[ macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649662219). |  |
| `hideselection` |  | `false` | By default, direct state transition buttons (to every other state in the workflow) will be added to the [workflow popup](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846), unless you specify any of the following parameters: `approved`, `rejected`, `submit`, `updated`, `expired` or `completed`.<br>If none of those parameters are specified, should the default buttons be hidden?<br>- `true` – hide default state transition buttons
- `false` – show default state transition buttons, if applicable<br>Alternatively, you can use a **[state-selection](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649826719)**[ macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649826719) to specify which direct state transition buttons should be shown.<br>> Macro (contentbylabel)<br>[Concepts](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692701): [Transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425) | 3.0+ |
| ## Deprecated Parameters<br>These parameters are either deprecated or obsolete and should no longer be used. |
| `assignable` |  | `false` | [Obsolete] Use `assignable` parameter on **[approval](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649662337)**[ macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649662337) instead. | 3.2.2  
↓  
4.2.1 |
| `style`~~<span style="color: #999999"> or </span>~~`cssstyle`<br>`class`~~<span style="color: #999999"> or </span>~~`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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655) are applicable to transitions between states:

- `statechanged`
- `pagestatechanged`
- `newsstatechanged`

## Example

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

## All examples

> Macro (contentbylabel)

## See also

[Workflow Authoring Guide](https://appfire.atlassian.net/wiki/spaces/CDML/pages/648611901)

- [States](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649595551)
- [Transitions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563425)
- [Events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655)
- [Triggers](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563178)
- [Actions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649858941)
- [Conditions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694110)
- [Value References](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302)

[User Guide](https://appfire.atlassian.net/wiki/spaces/CDML/pages/648907144)

- [Workflow Status Bar](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650117676)
- [Workflow Popup](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846)

[Reporting Guide](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649070833)

- [Report on states](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650216427)

[Integration Guides](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649396230)

- [Workflow Supplier](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649726882)

[Developer Guides](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649330694)

- [CQL REST API](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649921636)
- [Java API](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649560824)
- [REST API](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649692021)