--- title: "workflowparameter macro" canonical: "https://support.appfire.com/space/CDML/650348884/workflowparameter%20macro" format: markdown --- > Macro (aura-html) ## Overview > Macro (excerpt) > > Define editable workflow [value references](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302) The **workflow parameter** macro lets you create editable [value references](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302). This feature lets you 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. A workflow parameter can be configured to act as a placeholder for a type of data value, for example, a **due date** value; a Confluence user name(s) value ; a Confluence **group** name(s) value; a text **string** value; or a **list **of set option values. ## Where to use it? Optional. One or more `workflowparameter` macros can be put in a [workflow macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649662219). Must be placed *before* the [state macro(s)](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649531575) in the workflow markup. [Workflow builder](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650151179) can be used to add one or more workflow parameters to a workflow. ![image](media://c4220d81-87ba-4cbf-be67-20760ca4d960) Workflow parameters are useful placeholders for values such as content expiry dates or approval reviewers. The values for these placeholders can be set differently for individual spaces or when the workflow is applied to individual pages without the need to edit the workflow itself. ## Where can parameter values be edited? Where you can edit a parameter value depends on the workflow parameter. The use of the updated parameter value depends on the workflow and how the workflow is applied **Space administrator** The space administrator can view workflow parameters and their current value in the space in the space **Parameters screen**: - **Space tools** > [Document Management dashboard](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650314379) >  [Parameters - Space Tools](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649726501) ![spacedocumentmanagementdashboard_parameters_twoaddedparameter.png](media://ef50af4f-5e46-40bc-ab03-3e626f1f2732) For a workflow parameter to be added to the **Parameters screen**, a default value must have been added to the workflow. The workflow parameters in a page workflow and a space workflow are on this screen. A space workflow retrieves the value set in the **Parameters screen** only on a related workflow event, such as when the workflow is first applied to a page. Changing the workflow parameter in the parameters screen - Does not change the default value set in a workflow template, or - Does not update the value used in an applied workflow unless a related workflow event occurs to retrieve the updated workflow parameter value **Users** [Users](https://appfire.atlassian.net/wiki/spaces/CDML/pages/648907144) can edit a workflow parameter value using the [workflow state dialog box](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846) for a [space workflow](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649531846) and a [page workflow](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649628831). If a workflow parameter is configured as `editable`, a user can edit the parameter value using - The three-dot menu option in the workflow state dialog box ![image](media://3d917474-f333-47a5-9f40-421486ef9e09) - using the page tools **Edit Parameters** option ![image](media://1f97c55a-bb42-4923-ac33-da1f6d651281) When a workflow is applied as a space workflow for the first time, if the workflow parameter is configured as `editable`, a user is prompted to add or confirm the workflow parameter value(s) when adding the workflow to content ![image](media://df109b4f-fde3-4d87-ac99-8014c85407f4) > 📝 If a workflow parameter value has been edited in the space **Parameters screen**, the new value is used by the workflow the next time the workflow action to retrieve the parameter value occurs. ## Parameters The workflow parameter must be defined with a unique name and the type of data used for its value. This can be done using the [Parameters editor](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649792431) in the workflow builder ![image](media://05750840-9acf-4f37-971f-28923e47e757) Options let you set a default value, add a description, and let a user edit the workflow parameter value. | **Parameter** | **Required** | **Default** | **Notes** | **Ver** | | --- | --- | --- | --- | --- | | *unnamed first parameter* or `name` | :check_mark: | | Name of the parameter. | | | *macro body* | | | The default value for the parameter
- Can use any character set supported by your Confluence server – except some [reserved characters](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859070) - Can be overridden in [Parameters - Space Tools](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649726501) if the template is used in [space mode](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649531846) - Can be overridden at page or blog post level, using the [workflow state dialog box](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846), in both [page mode](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649628831) and [space mode](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649531846), if `edit=true` is set | | | `description` | | | The description for the parameter
- Plain text - Can use any character set supported by your Confluence instance – except some [reserved characters](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859070)
> Macro (contentbylabel) | | | `edit` | | `false` | Should this parameter be editable at the page or blog post level?
- `true` – yes, make it editable using the [workflow state dialog box](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649659846) - `false` – no, it can only be edited using [space Parameters screen](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649726501)
> ✅ If set to `true`, the value of the parameter can be used as a normal [value reference](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302) and can be accessed using the [get-metadata](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649826804)**[ ](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649826804)**[macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649826804).
`edit=true` can also be required to be set upon transition to a state by setting this in the [requiredparams](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649793313) list for that state. | | | `type` | :check_mark: | `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
> Macro (contentbylabel) | | | `options` | :blue_star: | `string` | :blue_star: Required if the parameter `type` is `list.`
List options
- Comma-separated list of values - Can use any character set supported by your Confluence instance – except some [reserved characters](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859070) - Supports [value references](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302) | | ## Parameter values and unprocessed content > ℹ️ When adding a space workflow, a [parameter reference](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649760641) value might only be available for use by the workflow ***after a workflow process occurs*****,** such as a state transition. Because of this, the initial state should not include the use of the parameter reference value for use in this first state, as these values might not be available until after a workflow process has taken place. For example, the workflow might not work as expected, or block your workflow process, if the initial state - has a due date, and a workflow parameter value is used to set this expiry - Has an approval with pre-assigned reviewers configured to use a workflow parameter value To process content and ensure workflow parameter values are set up, a space administrator can choose to [Initialize states](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649827807) when applying a space workflow. This action processes the pages, and the workflow parameter value is then available for use by the workflow in the initial state. This is a manual job, and it is usually better to avoid using parameters in the initial state to avoid the need for this every time you apply a new space workflow. ## Events The following [events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655) are generated when page-level parameters are updated - **pageparameterupdate** A workflow trigger can be configured to listen for this event. ## Examples When the following workflow is first added to a space, a space administrator can edit the value in the [Parameters screen](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649726501): - 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 screen](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649726501) is used when the workflow is added to the content. ```plaintext {workflow:name=Parameters} {workflowparameter:Review Group|type=group} confluence-users {workflowparameter} {state:Test} {approval:Review|group=@Review Group@} {state} {workflow} ``` The workflow parameter must have a value set in the workflow for it to be added and editable in the space tools [parameters screend](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649726501). > 📝 Editing the parameter value in the [space parameters screen](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649726501) does 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650216852), both in [page mode](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649628831) and [space mode](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649531846). ```plaintext {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 then be used in approval conditions. ```plaintext {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. ```plaintext {workflowparameter:OpDivision|description=Business Operating Division|type=list|options=hr,dev,marketing,finance,global} global {workflowparameter} ``` ## Use cases > Macro (contentbylabel) ## Related pages - [https://appfire.atlassian.net/wiki/spaces/CDML/pages/649760641](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649760641) - [https://appfire.atlassian.net/wiki/spaces/CDML/pages/649726501](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649726501) - [https://appfire.atlassian.net/wiki/spaces/CDML/pages/649792431](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649792431) - [https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649694302) - [https://appfire.atlassian.net/wiki/spaces/CDML/pages/650216852](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650216852)