workflowparameter macro

Overview

The {workflowparameter} macro allows you to create editable Value References.

This incredibly useful feature allows you to create configurable, portable workflows that can be used across spaces. Each space then has the option to use the default value set in the workflow or to use a custom value specified for that space only.

Where can values be edited?

Depending on the parameter

Space Admins – Parameters - Space Tools when your workflow is used in Space Mode
Users – Workflow setup via the Workflow Popup (in both Space Mode and Page Mode)

For a workflow parameter to be added to the space tools Parameters tab, a default value must have been added to the workflow.

If the workflow parameter is editable, a user will be prompted to add or confirm the workflow parameter value(s) when adding the workflow to content.

A value for the workflow parameter added by the user in the workflow set up dialog box may only be available for use by the workflow after a transition occurs from this initial state.

When adding a space workflow, a parameter reference value may only be available for use by the workflow after a workflow process, such as a transition, occurs. For example, the initial state should not include the use of the parameter reference value for a duedate or pre-assigned reviewers for approvals to avoid blocking your workflow. Alternatively, a space admin can choose to Initialize states when applying a space workflow. This will process the pages and the workflow parameter value will be available for use by the workflow in the initial state.

Where to use it?

Optional.

One or more {workflowparameter} macro can be put in a {workflow} macro.

Must be placed before the {state} macro(s).

Workflow builder can be used to add one or more workflow parameters to a workflow.

Parameters

Parameter	Default	Notes	Ver
unnamed first parameter or `name`		Name of the parameter.	3.0+
macro body		The default value for the parameter can use any character set supported by your Confluence server – except some reserved characters can be overridden in Parameters - Space Tools if the template is used in Space Mode can be overridden at page or blog post level, via Workflow Popup, in both Page Mode and Space Mode, if `edit=true` is set	3.0+
`description`		The description for the parameter plain text can use any character set supported by your Confluence server – except some reserved characters Page: State expiry dates	3.0+
`edit`	`false`	Should this parameter be editable at the page or blog post level? `true` – yes, make it editable via the Workflow Popup `false` – no, it can only be edited via Parameters - Space Tools Tip: If set to `true`, the value of the parameter can be used as a normal Value Reference and can be accessed via the `{get-metadata}` macro. `edit=true` can also be required to be set upon transition to a state by setting them in the `requiredparams` list for that state. Filter by label There are no items with the selected labels at this time.	3.0.3+
`type`	`string`	Parameter type `string` – text Usually plain text, but can contain wiki notation depending on where the parameter value will be used `user` – a single username or comma separated list of usernames `duration` – an ISO 8601 duration `group` – a single Confluence group or comma separated list of group names `list` – a list of values to choose from – see: `options` parameter below Page: Require Parameters on a state transition Page: State expiry dates	3.0+
`options`	`string`	Required if the parameter `type` is `list.` List options comma-separated list of values can use any character set supported by your Confluence server – except some reserved characters supports Value References Filter by label There are no items with the selected labels at this time.	3.0+

Events

The following Events are generated when page-level parameters are updated

pageparameterupdate

Examples

When the following workflow is first added to a space or page in a space, then a space admin can edit the value via Parameters - Space Tools.

the workflow parameters type=group and type=users can be used to define different users when adding the workflow to content
this can allow a workflow to be used across multiple spaces by different teams without having to change the workflow

A new value for the parameter added to the Parameters dashboard will be used when the workflow is added to the content.

{workflow:name=Parameters}
   {workflowparameter:Review Group|type=group}
      confluence-users
   {workflowparameter}
   {state:Test}
	  {approval:Review|group=@Review Group@} 
   {state}
{workflow}

A default value needs to be added to the body of the workflow parameter for the parameter value to be editable in the space tools Parameters dashboard.

Editing the parameter value in the Parameters dashboard will not change the value used in a workflow that has already been added and applied to content in the space.

Adding edit=true allows end-users to edit the value at the page or blog post level, both in Page Mode and Space Mode.

{workflow:name=Parameters}
	{workflowparameter:Review Group|type=group|edit=true}
      confluence-users
   {workflowparameter}
   {state:Test}
	  {approval:Review|group=@Review Group@} 
   {state}
{workflow}

Both group and user type workflow parameters, accept comma-separated lists. These lists can be then used in approval conditions.

{workflow:name=Parameters}
   {workflowparameter:Review Groups|type=group}
      group-1,group-2,group-3
   {workflowparameter}
   {state:Test}
	  {approval:Review|group=@Review Groups@} 
   {state}
{workflow}

For a type=list workflow parameter, the list options are added using the list parameter.

{workflowparameter:OpDivision|description=Business Operating Division|type=list|options=hr,dev,marketing,finance,global}
      global
{workflowparameter}

All examples

Page:

Require Parameters on a state transition — Require workflow parameter values to be set before moving into a workflow state.
Page:

State expiry dates — Using state expiry dates, defining them with metadata, and making them editable
Page:

Using workflow parameters to create reviewer teams in a space — Using workflow parameters to create teams of users for use in approvals

This site has moved to the integrated Appfire documentation and information site for our apps.