Require Parameters on a state transition
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, a state can be configured to require a user to set a value before transitioning from that state to a destination state.
Requiring a parameter for the transition to a state to occur adds a warning emoji to the workflow popup transition option to this state. For a state, the approve or reject button for an approval in the state or a submit button for a state selection
Before the transition takes place, a user is required to
Add a parameter value for the required parameter(s), or
Confirm a default workflow parameter value (if set when creating the parameter)
The Require Parameters option is only available in the Edit State dialog box in the workflow builder if the workflow includes at least one workflow parameter. The parameter must be set as editable.
Example of use
We are editing the Workflows Exchange Editor and Staff Approval workflow to use the parameters feature.
Using workflow parameters, we can:
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, allow parameters to be set at the page level by adding edit=true to each workflow parameter.
{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 the workflow builder.
Choose each parameter
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 is prompted to set the parameter values when applying the workflow.
Require parameters for a state
Second, add the parameter prompt for 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 the workflow builder:
Now, the workflow state dialog box in the Draft state displays a warning icon on the Submit button.
The user who transitions the workflow from Draft to Ready is prompted for the parameter values.
The required parameters for entering a state will only be prompted if a user is performing a workflow action, such as approving or rejecting an approval, or selecting a destination state in a submit or select transition.
Once a parameter value has been set, its valid is not prompted 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 for the parameter.
If a state is transitioned by a trigger, like a page update, the required parameter check is not carried out.
See also
Need support? Create a request with our support team.