Parameter References

Overview

Workflow parameters, defined by the {workflowparameter} macro, can be referenced by their name wrapped in @ (at) symbols.

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
Triggers and Actions, which 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 parameter value

If a default value for the workflow parameter is included in the workflow

the workflow parameter is added to the space tools Parameters dashboard
its value can be edited by the space administrator
the parameter value will be used when the workflow is added to content

Workflow parameter references can be added to a workflow using workflow builder.

Example

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=true

{workflowparameter:The Message:editable=true}
      Default value for "The Message"
 {workflowparameter}

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

Changes in the workflow parameter value

If the value for an editable workflow parameter is changed by a user

the new value may not be available for use by the workflow in the current state
the new value will then only be available for use by the workflow after a transition occurs

If the value for an editable workflow parameter is changed by the space administrator in the Parameters dashboard

the value will be used when the workflow is added to content
the value is not updated on content where the workflow is already applied

The workflow parameter value may only be available for use by the workflow after a workflow process has occurred, for example, after a transition occurs from the initial workflow state.

In an approval

if a parameter reference Editor is used to limit the assignees for a review, the value of the parameter reference is available in the initial state of the workflow

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

if a parameter reference is used to pre-assign reviewers, the value of the parameter reference will not be available in the initial 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 in space mode

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.

If you look at the 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

‹ Back to Value References

This site has moved to the integrated Appfire documentation and information site for our apps.