Value References

Overview

Value references allow you to add dynamic information and parameter values to your workflow markup – they are placeholders for information that's located somewhere else.

Each time the reference is encountered, for example in a trigger action or macro condition, the value at that moment in time will be retrieved. This means your workflow can dynamically adapt to changing situations.

Reference types

There are several types of value reference, depending on where the information is stored:

Where can I use them?

Value references can be used in macro parameters, sometimes macro body, and even conditions. However, actual availability depends on two factors:

• the type of reference determines which macros it can be used in

• the macro used determines which parameters support value references

For a full list of places where value references can be used, see Conditions, Content and Value References. But remember it's the reference type and macro which determine the specifics.

Comala Document Management includes

• get-metadata macro that can be used to retrieve the value of a value reference

• set-metadata macro that can be used to create metadata or set a value for a metadata reference

• workflow parameter references are bespoke value references that can be created and defined for a workflow using workflow builder

Workflow parameters can be used as placeholders for the users who are reviewers for approvals; duration periods for the expiry of your content or labels to be added to your documents allowing you to create a workflow that can be used for different teams or projects but these values set within a space or for a specific document.

Value reference retrieval order

If a named value reference is requested then the value reference is resolved in the following order:

1. Confluence page properties macro

2. Comala Metadata which include workflow parameters with edit=true that have been saved and metadata set using Comala Document Management set-metadata macro

3. Communardo Metadata

4. Workflow parameters saved at the space level - without edit=true

5. Page references

6. Suppliers (ServiceRocket, Workflows, Metadata)

Basic example

In your workflow you might need to refer to the author of a piece of content. You won't know this information in advance. To get around this problem, you can use the @author@ value reference, which is one of the references that the Workflows app creates and updates automatically. When a macro that uses the reference is activated, the reference gets replaced with the username of the person who most recently created or edited the content.

{workflow:Value references}
   {state:Editing|submit=Review}
   {state}
   {state:Review|approved=Published|rejected=Editing}
      {approval:Review}
   {state}
   {state:Published|final=true|updated=Editing}
   {state}
   {trigger:pageapproved|approval=Review|partial=true}
      {send-email:@user@|Subject=Your recent @approvalname@ approval} 
         Thank you for approving @page@ which was created by @author@ 
      {send-email}
   {trigger}
{workflow}

All examples

• Page:
  Adding page activity to email — Include page activity report, or a link to it, in custom email notifications
• Page:
  Assignment Examples — Define who can take part in, or be assigned to, a content review.
• Page:
  Attachment events — Triggering events when attachments are created, updated or removed.
• Page:
  Communardo Metadata for Confluence app — Using the Communardo metadata as value references in a workflow - including use in a custom condition for a trigger macro
• Page:
  Make tasks disable a review — Two ways to use tasks to disable a review. The first way uses a precursor task state where the tasks can be set and completed. The second example uses a Value Reference as a condition to check that all tasks are complete. For the value reference method, you will need the Reporting for Confluence app in addition to Comala Document Management.
• Page:
  Scaffolding app - Retrieve list-data via supplier reference
• Page:
  State expiry dates — Using state expiry dates, defining them with metadata, and making them editable

See also

Workflow Authoring Guide:

• Actions

• Conditions

• Events

• Reviews

• States

• Triggers

Integration Guides:

• Metadata, Forms and Reporting Integrations