Using workflow parameters to create reviewer teams in a space

Owned by Robert Alexander Marshall
Dec 14, 2023

Overview

You can use workflow parameters to create teams of users.



You can use these, for example in approvals, to manage your reviewers.


The values of the workflow parameterss can be managed by a space admin in the space tools Parameters dashboard.


Changes made by a space admin by editing the values in the Parameters dashboard will be used when a workflow is first applied to content in the space.

A workflow author can use a workflow parameter (set as either a user or group type) to allow their workflow to be used across multiple spaces by different teams of users

  • the workflow parameter values for the Confluence users or groups can be edited by the space admin for each space
  • changes made by the space admin to the workflow parameter values will be used when adding the workflow to content

Multiple team reviews in a state

You can add multiple reviews in a state and use each approval to assign different users using the workflow parameters.

For example, using workflow builder in a state Product Review, add three reviews Design, Technical, and Quality.


This will create the following markup in the markup editor.

{workflow:name=Using Workflow Parameters for Team Approvals}
   {state:Product Development|submit=Product Review}
   {state}
   {state:Product Review|approved=Approved|rejected=Product Development}
      {approval:Design|description=Design approval team}
      {approval:Technical|description=Technical approval team}
      {approval:Quality|description=Quality Lead to be assigned for final approval}
   {state}
   {state:Approved}
   {state}
{workflow}

Workflow parameters for the review teams

We can create three workflow parameters, one to manage the reviewers for each approval.

In our example, the Design Team parameter is a user parameter and has a default value of two users.

{workflowparameter:Design Team|description=Design team members who must approve|type=user}
        matilde,suni
{workflowparameter}


Adding a default value for a workflow parameter when creating the workflow adds the workflow parameter to the space tools Parameters dashboard in the space where the workflow is added.

The second workflow parameter, Technical Team is also a user parameter.

The third  workflow parameter, QA Reviewers, is added as a group parameter. Its value will be one or more Confluence groups.



In our example the default value is set as two Confluence user groups in our instance.

In our example these Confluence user groups are

  • project-alpha-leads that is specific to the project and the space
  • project-quality-leads that is a cross project quality group

Adding the team parameters as reviewers

Approvals can use the workflow parameters (a value reference) to set the reviewers for each approval.

For the Design approval the Design Team workflow parameter is used to mandate the reviewers who must undertake the approval.



The Technical approval uses the Technical Team workflow parameter to mandate reviewers.



The Quality approval limits the assignment to one approver. The Quality Team workflow parameter is used to specify the list of reviewers from which the reviewer can be chosen.



The Quality approval also excludes any users from being assigned who have been mandated to undertake either the Design or the Technical approval using the same workflow parameters added to these two approvals.

In our example, the Design and Technical approvals in the Product Review state are populated with the avatars for the mandated reviewers.

These reviewers are the user values for the workflow parameters Design Team and Technical Team.

The assignment reviewer for the Quality approval is limited to members of the Confluence user groups added as values for the QA Reviewers workflow parameter

The choice of Confluence groups for the value of the QA Reviewers workflow parameter in the space is made by the space admin.

The membership of the groups is managed by the global admin

  • project-quality-leads


  • project-alpha-leads


Elle Bracus will not be available for assignment to this approval as elle is also a Technical Team workflow parameter user value and this workflow parameter is used with the exclude parameter condition for the approval to prevent a user from being assigned.

Managing the space workflow parameter values

When a workflow is added to a space and contains a workflow parameter with a default value, the workflow parameter and default value is added to the space tools Parameters dashboard.


The values in the dashboard will be used by workflow containing the workflow parameter on the first application of the workflow to content.

For a space the space admin can

  • choose the reviewers for the Design approval by editing the users for the Design Team workflow parameter
  • choose the reviewers for the Technical approval by editing the users for the Technical Team workflow parameter
  • choose the Confluence user group(s) (if available) for the QA Reviewers workflow parameter. This provides the list of group members who can be assigned as the approver for the Quality approval

Editing the workflow parameter value in this dashboard will not change the value used by a workflow that is already applied to content. The new value will only be used when the workflow is initially applied.

When a workflow is first applied to content, the content is considered as "unprocessed pages" and the workflow parameter value may not be available until after a workflow process (such as a transition) has occurred.

A space admin can choose to Initialize states on the first application of the workflow. This action causes the page to become "processed" and the workflow parameter value is updated.

Alternatively, the workflow author can include an initial state in the workflow that does not utilize any workflow parameter value. A transition from the initial state will "process" the page and update the workflow parameter value.


Example workflow markup

The example workflow contains the following markup 

{workflow:name=Using Workflow Parameters for Team Approvals}
	{description}
   		An approval workflow with 3 states. The Product Review state has 3 approvals.
    {description}
    {workflowparameter:Design Team|description=Design team members who must approve|type=user}
        matilde,suni
    {workflowparameter}
    {workflowparameter:Technical Team|description=Technical team members who must approve|type=user}
        simone,elle
    {workflowparameter}
    {workflowparameter:QA Reviewers|description=Quality leads|type=group}
        project-alpha-leads,project-quality-leads
    {workflowparameter}
   {state:Product Development|submit=Product Review}
   {state}
   {state:Product Review|approved=Approved|rejected=Product Development}
      {approval:Design|user=&@Design Team@|description=Design approval team}
      {approval:Technical|user=&@Technical Team@|description=Technical approval team}
      {approval:Quality|exclude=@Design Team@,@Technical Team@|selectedapprover=@QA Reviewers@|description=Quality Lead to be assigned for final approval}
   {state}
   {state:Approved}
   {state}
{workflow}

See also

Workflow Authoring Guide

User Guide

Reporting Guide