Parameter References

Overview

A workflow parameter reference can be used to allow an applied workflow to indirectly access a value that can be set elsewhere, for example in the space tools Parameters dashboard or a workflow parameter value set by a user on the page.

One or more workflow parameters can be added to a workflow using workflow builder.

The workflow parameter can be set to use one of the following data types

• character string

• Confluence username(s)

• Confluence groupname(s)

• duration

• a list of set values

Workflow parameters can be referenced in the workflow by their name wrapped in @ (at) symbols.

In the workflow markup the workflow parameter is defined by the workflowparameter macro.

Where can they be used?

You can use parameter references in the following situations

• any macro parameter (including macro bodies, where applicable) which supports value references

• Conditions, including custom value reference conditions

• workflow triggers and actions that are initiated by events

Workflow parameter value

A workflow parameter reference

• can be set to allow a user to edit the parameter value

• can be added to the workflow with a default value

Space workflow parameter

If a default value for the workflow parameter is included when the workflow is first added to/created in a space the workflow parameter and this default value is added to the space tools Parameters dashboard.

Its value in the space parameters dashboard can be edited by the space administrator.

The parameter dashboard value will be used when a space workflow or a page-level workflow is added first added to content.

If the space parameter value is changed by the space administrator this value will be used for all subsequent applications of the workflow in the space irrespective of the default value set in the workflow.

The workflow parameter can be deleted from the parameters dashboard. This will not remove the workflow parameter from the workflow. Any application of the workflow will use the default value defined in the workflow itself or, if the parameter is editable, the value set by a user on the page or blog post where the workflow is applied.

Editable value

A workflow parameter can be added to a workflow template as editable by a user. This can be done by either

• adding using editable=true in the workflow parameter macro markup

{workflowparameter:The Message:editable=true}

• or, checking Editable in the Workflow Parameters editor in workflow builder

By default, a workflow parameter is added as editable when using workflow builder.

A workflow parameter added to a workflow template in a space with a default value and the Editable attribute unchecked is still editable by a space administrator in the space parameters dashboard.

Adding a workflow with a workflow parameter

In the example below, a parameter called "The Message" is referenced as "@The Message@" in the body of the set-message macro which is triggered by transitioning to the Stop state.

{workflow:Parameter references}
   {workflowparameter:The Message}
      Default value for "The Message"
   {workflowparameter}
   {state:Start}
   {state}
   {state:Stop}
   {state}
   {trigger:statechanged|state=Stop}
      {set-message}@The Message@{set-message}
   {trigger}
{workflow}

If the workflow parameter is added as editable using editable=true 

{workflowparameter:The Message:editable=true}

On the first application of the workflow to content, a user is asked to undertake some minor setup by editing the workflow parameter value.

The parameters dialog box will display any default values (or the space parameter value) set for the workflow parameter.

The user can choose to Save the current value or add a new value.

For a page workflow, an Editable workflow parameter can also be edited by using the Edit Parameters option in the page tools menu.

After changing the value for a workflow parameter, the workflow will only use the new value after a workflow event has taken place, for example a transition

Changes in the workflow parameter value

A change in the value of a workflow parameter may require a workflow event to take place before the workflow can access and use the updated value.

If a parameter reference is used to pre-assign reviewers, the value of the parameter reference will not be available in the initial workflow state. The approval will need to be added to a different state so the value is available for the workflow to use.

{approval:Check Review|user=&@Editor@,admin}

This occurs because when a workflow is first applied to a page as a space workflow

•  only the link to the workflow is created (and any page restrictions, if using same-space publishing, are applied)

• the page (or blog post) itself won't actually transition into the initial workflow state, despite it appearing that way when you look at the workflow status bar

In the Document Activity Report - Content for the content, you'll see that there are no workflow-specific entries listed. These pages are referred to as "unprocessed".

• assigning a reviewer is a workflow process and it will use the workflow parameter value

• pre-assigned reviewers will not use the workflow parameter value until after a workflow process had occurred such as a transition

Example - using an initial state to add workflow parameter values for an approval pre-assigned reviewers

In the example below, we are using a workflow parameter reference, Editor, to set the pre-assigned reviewer for an approval. The workflow is applied as a space workflow.

The Initial state is added to ensure that the content is processed by the workflow and the value for the workflow parameter Editor is available for use by the Check Review approval.

{workflow:name=Parameter Reference to pre-assign a reviewer|label=wfspaceapprovalinitialassignee}
    {workflowparameter:Editor|type=user|edit=true}
        elle
    {workflowparameter}
    {state:Initial|submit=Check}
    {state}
    {state:Check|approved=Stop|rejected=Initial|taskable=true|colour=#0052CC}
        {approval:Check Review|user=&@Editor@}
    {state}
    {state:Stop}
    {state}
{workflow}

Any changes to the workflow parameter Editor value can be made in the Initial state by a user

• editing the value by choosing Parameters in the Workflow setup dialog box
  

  

A space admin can also change the parameter value using the space tools Parameters dashboard before any workflow activity has taken place or a user has set up the parameter value.

Choosing Initialize states in space tools Document Management dashboard can also be used to process the content and allow the workflow access to a workflow parameter value.

Related pages

• workflowparameter macro

• Editing workflow parameters using workflow builder

• Initialize States