Catalytic is now PagerDuty Workflow Automation

Reference Fields

You can insert references to fields in places like instructions, the body of an email, and when configuring actions. These field references dynamically insert values each time an instance is run, allowing you to automatically customize the information, settings, and flow of every instance.

How reference fields work

The data collected in each Workflow instance is stored in data table rows; each column of the row is a field collected from that instance. In this example, a Vacation Approval instance started on Sep 24 is storing the Name and Department of an employee.

screen readers look here
Michael's boss hasn't approved the request yet, so the response is empty, but Michael has already submitted his name and department in an earlier task.

This information is referenced and reused in Michael’s managers approval task with a field reference. The fields that are referenced are highlighted in the data table and the next task.

screen readers look here
The name and department are dynamically added to this task, they were not typed in manually.

This concept of referencing fields is similar to mail merge in Microsoft Word or other applications.

Examples of Use

Field references are a powerful and dynamic way to create automation, you’ll find that almost all automation uses field references in some way:

  • Instructions: Include the name and department of an employee automatically based on a web form submission.
  • Email text: Include the address of an appointment by referencing the output of an address lookup
  • Action configuration: Set the starting row number of a spreadsheet based on a field collected earlier
  • Task timing: Set the date the task should start
  • Task deadlines: Set the due date by referencing current or adjusted date and times

How to reference a field

Field references are supported across PagerDuty Workflow Automation. If you’re configuring a Workflow, task, or any other field, you can use field references.

Type {{ to display the field reference picker, then just start typing to filter the fields. You can use the arrow and enter keys to select from the choices, or your mouse.

Safari browser bar
 

The picker displays all available fields. If a field reference is valid, it is identified in blue, like .

The picker does not display fields from parent Workflows, but they can still be referenced. If the field is not in the picker, type the field reference manually using the {{field-reference-name}} format. If correctly formatted, it will get the same blue outline, and maintain the {{ curly braces: .

How to use the field sidebar

If you know the field you’re looking for, the field picker is the easiest way to add it. If you want to browse all your fields, or look at the fields from a specific action, you can use the field sidebar.

screen readers look here

The field sidebar lists all actions from your Workflow, and the output fields from each. You can also quickly access Globally available fields. To use the sidebar:

  1. From the Builder screen, expand the field sidebar by clicking near the top of the page if it is not already open.
  2. Click on an action name in the sidebar to expand it
  3. Click a field to copy that field to your clipboard

    screen readers look here
  4. Select where you want to paste it with your cursor, then paste it using CTRL+V or CMD+V on a mac.

Here’s an example of that process:

Safari browser bar
 

The field sidebar is open by default, but can be closed or reopened while working. To close or reopen the sidebar, click between the build view and sidebar.

If you expand an action and it says “No Output Fields”, the action either has no output fields you can reference, or the action is not fully configured. Check the action first to make sure a required field isn’t missing.

More ways to use fields

How to manually type a field reference

Manually typing the reference is necessary if the field you need is not available in the picker. You can manually reference a field by the field reference name, {{field-reference-name}}. For example, .

You can find the field reference name for fields from the field configuration page or you can write it manually.

To write it manually, use all lowercase letters and use dashes, -, to replace spaces and special characters. Underscores are accepted and do not need to be replaced with dashes. Here are some examples of the field name, and the correct field reference format:

Field Name {{field-name}}
Country {{country}}
First Name {{first-name}}
emailSendDate {{emailsenddate}}
Is Approved? {{is-approved-}}
Street_Address {{street_address}}

Also, if you have an issue with a field reference, make sure both {{ and }} are on each end, if even one { or } is missing, the reference will not work.

note
  • Note: If the field name is changed, the name of the field reference name will NOT change. For example, if a field is created with the display name First Name and it’s changed to Customer First Name later, the field reference name will stay as {{first-name}}, even though the field name was changed. See more under basic field configuration
How to find the field name you want to reference

Output fields are where an action stores a result, for example, in the Companies: Look up company info by domain action, the output fields are fields like, Employees, Locale, Logo, and Website.

These output fields are essential for automation, and become the conditions or ingredients in other tasks and processes.

To find all the output fields from an action, look up the action on the Help Center, or Preview & Test the action and check the test fields.

  1. Preview & test the action which fields you want to check. For instructions to preview & test the action, check the Test Workflows and Actions page.
  2. After selecting the View this test task in a new tab, the test’s instance detail screen opens in a new tab.

    Safari browser bar
     
  3. From the instance detail screen, select the menu button, and select Fields to list all output fields for the action.
How to use a field reference stored in a field

It’s possible to store a field reference in a field or table, then reference that field reference. This makes the field reference itself dynamic, and makes it possible to chain field references.

To do this, add lookup this to the starting reference. So for the field {{field-one}}, change it to {{lookup this field-one}}.

For example, if you have two fields with values:

  1. {{field-one}} = field-two
  2. {{field-two}} = Final Result

Manually type the reference {{lookup this field-one}} in instructions or anywhere field references are supported, and the result is Final Result.

screen readers look here

But in the following example, the result would be blank:

  1. {{field-one}} = apples
  2. {{field-two}} = Final Result

In the example above, if field-one had the value Apples and you reference this field with {{lookup this field-one}}, the result will be blank, and it will not return Apples. If the lookup this notation is used, the target field must contain a field reference.

✅   Heads-up: This is not generally supported for Word, PowerPoint, or Excel actions that insert a field within a file, like Word: Create a Word Document.

How to reference a Workflow or Table by its name, field, or ID

When you configure an action and a field references a Workflow or table, there are drop-down menus to make picking the correct one easier.

 

There are three ways to reference Workflows or tables. You can change the method using the left hand drop-down:

  • Workflow/Table: Browse and select from a list of all the Workflows/tables available on your team. The list only includes objects you have permission to view.

  • Field: Reference a Workflow/table from a field. Browse and select from any fields that’s part of the process.

  • ID: Enter a Workflow or Table ID in manually.

    screen readers look here
    Here's an example of how to find the Workflow or Table ID

Field reference special cases

There are some special cases where field references can be used in unique or special ways. The unique formatting or instructions for these cases are below.

Use a field reference to generate options in multiple choice fields

You can populate Single Choice and Multiple Choice type fields with multiple options with a single reference. For example, where {{field-name}} equals:

apple
banana
cherry
durian
elderberry

Each line from the referenced field is assigned as one of the multiple choice options.

Use a field reference to conditionally display text

In task instructions and the body of emails, you can set text to display based on the value of a field. This method uses field references and conditions to conditionally display text and fields. For all the examples below, replace field-name with the field name of your choice:

💡   Tip: If you have trouble configuring the conditions, you may need to set them in the previous editor. See How to open a step in the previous editor.

IF: Defining a condition for text to appear only if a field value DOES exist:

{{#if field-name}}
This is the text will only display if field-name DOES exist
{{/if}}

IF / ELSE: Defining a condition for text to appear if a field value DOES exist and a second condition for different text to appear if the field DOES NOT exist:

{{#if field-name}}
This is the text will only display if field-name DOES exist
{{else}}
This is the text will only display if field-name DOES NOT exist
{{/if}}

UNLESS: Defining a condition for text to appear only if a field value DOES NOT exist:

{{#unless field-name}}
This is the text will only display if field-name DOES NOT exist
{{/unless}}

Exceptions to field reference formatting

When configuring conditions and the Field: Field Formulas action, fields are referenced using a fields["field-name"] format.

When referencing fields which are globally available within the PagerDuty Workflow Automation team, a specific format is used. See Globally Available Fields for information on this format.

Sorry about that. What was the most unhelpful part?









Thanks for your feedback

We update the Help Center daily, so expect changes soon.

Link Copied

Paste this URL anywhere to link straight to the section.