Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

ParameterRequiredDefaultNotesVer

unnamed first parameter
or name

(tick)(tick)


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
showLabelsfalse
showSpacefalse
sorttitle
excerptTypesimple
cqllabel = "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 {set-state} transition.

approved


see notes

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

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "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?

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "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 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
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-state" and label = "parameter-submit" and label = "example" and space = currentSpace()

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
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-state" and label = "parameter-updated" and label = "example" and space = currentSpace()

Concepts: Transitions


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.

requiredparams



Require a given list of workflow parameters to be set before transitioning into this state.

  • 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

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?

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

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "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 can be either:
    • Explicit date in the format: DD.MM.YYYY  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
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "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).

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "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.

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
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "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.

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
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "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 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(info)false

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

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-state" and label = "parameter-versioncompleted" and label = "example" and space = currentSpace()

Concepts: Publishing


(info) 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:

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
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "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 when this state is active.

Supports Value References.

Content by Label
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "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?

  • 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
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "macro-state" and label = "parameter-hidefrompath" and label = "example" and space = currentSpace()

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
showLabelsfalse
max6
showSpacefalse
sorttitle
cqllabel = "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
subtletrue
colourRed
titleObsolete
Use assignable parameter on {approval} macro instead.

3.2.2

4.2.1

style or cssstyle

class or cssclass



Status
subtletrue
colourRed
titleObsolete
Use colour parameter instead.

3.0

4.0.2

...