Using workflow parameters to create reviewer teams in a space

Overview

You can use workflow parameters to create teams of users.

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

A space administrator can manage the values of the workflow parameters in the space tools Parameters dashboard, which are used by an applied space workflow.

Changes made by a space administrator by editing the values in the Parameters dashboard are used when a workflow is first applied to content in the space. The workflow does not retrieve an updated space parameter value unless an appropriate workflow event takes place.

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 administrator for each space
Changes made by the space administrator to the workflow parameter values will be used when adding the workflow to a document.

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 the workflow builder, add three reviews: Design, Technical, and Quality, in the state Product Review.

This creates 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-type parameter.

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

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

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 space administrator chooses the Confluence groups for the value of the QA Reviewers workflow parameter in the space.

The membership of the groups is managed by the global administrator:

project-quality-leads
project-alpha-leads

In the example, user Elle Bracus is not available for assignment to this approval, as they are 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 are used by the workflow containing the workflow parameter on the first application of the workflow to content.

For a space the space administrator can choose the

Reviewers for the Design approval by editing the users for the Design Team workflow parameter
Reviewers for the Technical approval by editing the users for the Technical Team workflow parameter
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 might not be available until after a workflow process (such as a transition) has occurred.

A space administrator 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 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}