Published on

OmniScript Merge Field Syntax

Authors

You can use merge fields in your OmniScripts to pull information from data stored in JSON format. Think of merge fields as placeholders that get replaced with the actual value from your data.

For example, if your data is "FirstName": "John", you will access the JSON node, FirstName with this syntax: %FirstName%. The result will be the value for FirstName: "John".

To let OmniScript know you're using a merge field, you need to follow a special rule for writing it. You put the JSON path (the "address" of the data) inside percent signs (%). This tells OmniScript, "Hey, look here for the data!"

So, if you want an OmniScript element to show someone's first name, you would write %FirstName%. OmniScript will then grab "John" from the JSON data and display it.

Common Use Cases

Common use cases for accessing Omniscript data JSON with merge fields:

  • Setting Values to rename elements, access JSON nodes, run formulas, and populate elements. For more information, see Set Values in an Omniscript
  • Access data stored in Omniscript elements in a formula or in a future step.
  • Access data returned from an Action. For example, an HTTP Action or Omnistudio Data Mapper Action returns data from Salesforce or an external source. For more information on Actions, see Omniscript Action Elements.
  • Access data passed in as a parameter from a page.

Access the Data JSON

Use existing data JSON in an element property by indicating the use of a merge field.

  1. Locate the name of the JSON node in the Omniscript's data JSON. step 1
  2. Enter the name of the JSON node and wrap the name in percentage signs to indicate it is a merge field. For example, a merge field accessing a JSON node named firstName must use the syntax %firstName%. step 2
  3. Preview the Omniscript to ensure the Merge field works correctly. step 3

Merge Field Syntax for Nested JSON Data

Example 1

"ContactInfo": { "FirstName": "John" }

To access the FirstName node in this JSON sample, use a colon symbol : to access a nested JSON node. %ContactInfo:FirstName%

Example 2

"ParentObject": { "NumberMap": [ 1, 2, 3 ] }

To access the number 2 in the NumberMap array in this JSON sample, use a colon symbol : to access nested JSON nodes and a pipe symbol. %ParentObject:NumberMap|2%

Example 3

"ContactInfoStep": 
    { "ContactInfoBlock": [ 
            { "FirstName": "John" }, 
            { "FirstName": "Adam" }, 
            { "FirstName": "Steve" } 
        ] 
    }

When a formula exists within a repeatable block, use |n to access the node in which the formula exists. Depending upon which node the formula exists in, it will return the correlating value. For more information, see Access to Data Within and Outside a Repeatable Block.

%ContactInfoStep:ContactInfoBlock|n:FirstName%

As always, review the official Salesforce docs for more information.

Discuss on X...