How to use Merge fields

Almost all Step inputs allow selecting and using Merge fields defined on Flow/Bot level. To see the list of available Merge fields, click {x} next to the input box. The list displays the sections Flow, Shared, and Global that show respective Merge fields.

Clicking a specific item in the list enters the Merge field getter in the input box. When inserted into a text expression component, the Merge field reference is visualized in a friendly way - {mergeFieldName.subProperty} displayed in blue color. When the Flow is executed, the Merge field value is automatically substituted in the input.

How to use Merge fields in code mode

Switching an input that contains a Merge field to code mode reveals the underlying javascript expression. For example:

{mergeFieldName.subProperty}

becomes

${await this.mergeFields['mergeFieldName'].get({path: 'subProperty'})}

which is the actual code that is executed when the Flow runs.

Get value from Merge fields

To get a value from the Merge field in a code mode input, javascript input, or Step logic, use this standard synchronous getter function:

await this.mergeFields['mergeFieldName'].get({path: 'optional.path[0].to.subProperty', 
defaultValue: 'optional value to default/fallback to if there was no value'})

This getter function is valuable because it is universal for all Merge field types and will always work even if you change the type when setting up another Step. Even though this getter function is asynchronous, there is no performance penalty for this method relative to this.get when retrieving Session Merge field values. We recommend using this getter function in most cases.

The original method still works, but you can only use it to access Session Merge fields:

this.get('mergeFieldName.optional.path', 'optional default')

Below are specialized getters for Shared and Global Merge field types. However, we have deprecated these functions and do not recommend using them:

await this.getShared(fullPath, defaultValue) // an async getter for Shared Merge fields 
await this.getGlobal(fullPath, defaultValue) // an async getter for Global Merge fields

fullPath is a path to the object property and defaultValue is a value that will be returned in case the Merge field is empty.

Getter aliases

Below are a couple of alternative methods that can help you get any Merge field. Here's an example of an object that is stored in a Merge field named myMf:

{
 a: {
  b: 1
 }
}


// standard method
await this.mergeFields['abc'].get({path:'a.b', defaultValue: 42}); // 1

// aliases using typical dot and bracket object notation
await this.mergeFields.myMf;        // {a: {b: 1}}
await this.mergeFields.myMf.a.b;    // 1
await this.mergeFields.myMf.a.b.c;  // null
await this.mergeFields.myMf['a'];   // {b: 1}
await this.mergeFields.myMf.a['b']; // 1

// dot notation merge field name with getter method
await this.mergeFields.myMf.get({defaultValue: 42, path : 'a.b'});   // 1
await this.mergeFields.myMf.get({defaultValue: 42, path : 'a.b.c'}); // 42

Set value to Merge fields

Use this standard asynchronous getter function to set a value to a Merge field in code mode input, javascript, or Step logic:

await this.mergeFields['mergeFieldName'].set(value, path)

This setter function is universal for all Merge field types. We recommend using it in most cases. If you have previously set a Merge field to a particular type (Session, Shared, or Global), this setter will overwrite the value using the same type. If you haven't set the Merge field to any type, the setter will define it as the Session type.

Below are specialized setters for Shared and Global Merge field types. However, we have deprecated these functions and will remove them in the future:

await this.setShared(fullPath, value, ttl) // an async setter for Shared Merge fields 
await this.setGlobal(fullPath, value, ttl) // an async setter for Global Merge fields

fullPath is a path to object property, value is any serializable type of data that should be stored in the Merge field, and ttl is the Merge field value expiration time in milliseconds.

Setter aliases

Here are two alias/alternative methods of setting any Merge field. Below is an example of an object that is stored in a Merge field named myMf:

{
 a: {
  b: 1
 }
}

// standard method
await this.mergeFields['myMf'].set(42, 'a.b'); // {a: {b: 42}}

// alias methods
await this.mergeFields.myMf.set(42, 'a.b') // {a: {b: 42}};
await this.mergeFields.myMf.a.b.set(42)   // {a: {b: 42}};

TIP

this.get and this.set are synchronous methods. However, all methods described in this article are asynchronous. Remember to await them, even before exiting a Step or Flow. Otherwise the data might not be available later on in the code execution.

# How to use Merge fields