Overview
Using workflow parameters, you can extend the functionality of your workflows by including editable value references.
These parameters can be set for a whole space or entered at the individual page level. When parameters are utilized for page-level editing they can require a value to be set by a user when transitioning from state to state in the workflow.
In this example, we are going to edit the Workflows Exchange Editor and Staff Approval workflow to use the parameters feature.
Using workflow parameters we will:
- require users to input the appropriate review group when the workflow starts
- prompt the user to enter the review groups once the Draft state has been approved, but before it reaches the Ready state.
Workflow parameters
First, we are going to allow parameters to be set at the page level by adding edit=true
to each of them.
{workflowparameter:Reviewers|description=Reviewers group|type=group|edit=true} confluence-users {workflowparameter} {workflowparameter:Editor in Chief|description=User able to give final approval|type=user|edit=true} @user@ {workflowparameter}
The workflow parameters can also be edited using workflow builder.
Choose each parameter and check the Editable box to allow the workflow parameter values to be edited by a user.
With this change complete, the user creating the page will be prompted to set the parameter values when starting the workflow.
Require parameters for a state
Second, we are adding the parameter prompt to the Ready state transition by adding a requiredparams
attribute to the Ready state definition.
{state:Ready|approved=Reviewed|rejected=Draft|requiredparams=Editor in Chief,Reviewers}
This can also be done by editing the Ready state using workflow builder:
Now the workflow popup in the Draft state will display a warning icon on the Submit button.
The user who transitions the workflow from Draft to Ready will be prompted for the parameter values.
Some things to note:
- the required parameters for entering a state will only be prompted if a user is performing a workflows action such as approving/rejecting or state selection.
- if a state is transitioned by a trigger, like a page update, the required parameter check will not be carried out.
- once a parameter value has been set, it will not be prompted for again unless the saved value is removed.
- if you want to prompt the user to enter a value every time the workflow resets, you can add a trigger with a
set-metadata
action macro to clear the relevant metadata value.