Require Parameters on a state transition
- Robert Alexander Marshall
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 value to be set by a user prior to transitioning from 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 - the approve or reject button for an approval or a submit button for a state selection.
The user will be required to add a parameter value for the required parameter(s) or simply confirm a default workflow parameter value (if set when creating the parameter) before the transition will take place.
The Require Parameters option is only available in the Edit State dialog box in workflow builder if the workflow includes at least one workflow parameter. The parameter must be set as editable.
Example of use
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.
The required parameters for entering a state will only be prompted if a user is performing a workflows action such as approving/rejecting an approval or selecting a destination state in a submit or select transition.
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 for the parameter.
If a state is transitioned by a trigger, like a page update, the required parameter check will not be carried out.