Updating a mandatory reviewer for an approval assigned using a workflow parameter
Overview
In an approval process you may sometimes require a workflow to assign a specific reviewer for an approval and for this reviewer to be mandated to undertake the approval decision. On the transition to the review state, the reviewer is assigned and the workflow popup cannot be used to change the reviewer.
This sometimes can become a ‘blocker’ in your process if the user is unavailable, as the approval will be disabled for other users and it is difficult to effect a change of reviewer without resorting to help from an administrator.
One solution is to allow your page authors to change the reviewer by
using a workflow parameter to hold the user value for the workflow assignee for the approval
setting the workflow parameter to be Editable
using the pageparameterupdate event in a workflow trigger to listen for the update in the review state
The pageparameterupdate trigger actions two workflow transitions in sequence
a transition out of the Review state
a transition back into the Review state
On the transition back into the Review state the workflow uses the updated value of the workflow parameter to assign a new reviewer.
Adding the workflow parameter as the reviewer
You can add and use a workflow parameter in an approval to manage your assigned reviewer.
The workflow parameter as a value reference @Reviewer@. This can be added to an approval to automatically assign a user to undertake the approval review.
In the workflow markup
{approval:Review|user=&@Reviewer@}The & ampersand operator assigns and mandates the specified user to undertake the review.
When the workflow transition to the Review state occurs
the user is assigned by the workflow using the current value for the workflow parameter Reviewer
There is no easy way to change the assigned mandatory reviewer once the transition into the Review state has occurred.
Options would require space administrator permission, for example, to initialize the states, allowing a change of the parameter value to be undertaken and then transition the document back to the Review state to allow the workflow to assign the updated workflow parameter user value as the reviewer.
Using the workflow parameter to update the reviewer
An editor change easily change the value of the workflow parameter (if it is configured as Editable) using one of
the Edit parameters option in the workflow popup ellipsis menu
the Edit parameters option in the workflow inspector dialog box (accessed using the workflow icon in the page header)
the Edit parameters option in the page tools menu
If the content is already in the current Review state this does not change the assigned reviewer for the current approval as the user is assigned on transition into the Review state.
A workflow trigger can be set to listen for an update in the workflow parameter value using the pageparameterupdate event and we can set a number actions to update the workflow assigned reviewer for this approval.
{trigger:pageparameterupdate|parameter=Reviewer|state=Review}
{set-state:Draft|comment=Reviewer is updated}
{set-state:Review|comment=Automatic transition after Reviewer is updated. The new assignee is @Reviewer@}
{trigger} The pageparameterupdated trigger above, listens for an update of the Reviewer parameter when the page is in the review state Review.
A page editor can update the workflow parameter value using the Edit parameters option in the workflow inspector dialog box
The workflow parameter Reviewer value change is from matilde enios to suni conn.
This causes the pageparameterupdated trigger to
first, change the state from the Review state to the precursor state, Draft
then change the state back into the Review state with the approval
On the set-state transition to the Review state the workflow assigns the reviewer using the updated user value for the workflow parameter, Reviewer.
The Document Activity report displays the state changes actioned by the set-state trigger action macros and the change of assignee to the updated workflow parameter value.
Updating the space parameter value in this example does not update the workflow parameter value on the page and will not action the pageparameterupdate trigger.
Workflow markup
{workflow:name=Parameter update for reviewer and update for approval assignee}
{description}
Required reviewer managed by workflow parameter. Assigned reviewer updated by change in value of workflow parameter and use of pageparameterupdate trigger
{description}
{workflowparameter:Reviewer|description=Mandatory reviewer|type=user|edit=true}
matilde
{workflowparameter}
{state:Draft|submit=Review}
{state}
{state:Review|approved=Approved|taskable=true|colour=#0052CC|requiredparams=Reviewer}
{approval:Review|user=&@Reviewer@}
{state}
{state:Approved|final=true|updated=Review|hideselection=true}
{state}
{trigger:pageparameterupdate|parameter=Reviewer|state=Review}
{set-state:Draft|comment=Reviewer is updated}
{set-state:Review|comment=Automatic transition after Reviewer is updated Reviewer is now @Reviewer@}
{trigger}
{workflow}In the example markup the initial transition to the Review state requires the setting of the Reviewer workflow parameter using the state requiredparams parameter.
For ease of tracking in the document activity report the pageparameterupdate trigger can be used to transition to a separate workflow state added to the workflow, for example Parameter Updated, rather than the initial Draft state.
This ‘dummy state’ state can be hidden from the progress tracker bar in the workflow popup by checking Hide from path in workflow builder state editor. If required it can be configured as an approval state to review any change in the assigned reviewer or to undertake other housekeeping tasks.
The use of the ‘dummy state’ in this process allows the reviewer change to be easily identified in reports and logs with the activity linked to a specific workflow state that can used as as report filter.
See also