Build a Data Mapper Turbo Extract and Data Mapper Load

Learning Objectives

After completing this unit, you’ll be able to:

• Build an Omnistudio Data Mapper Turbo Extract.
  
• Build an Omnistudio Data Mapper Load.
  
• Explain how an Omnistudio Data Mapper Load decides to create or update records.
  

Here’s a simple guided user interaction. A user updates some basic customer account details, such as the account’s phone number and website. The steps are intuitive and simple to complete, even though some complex functionality happens behind the scenes. That’s because an Edit Account OmniScript guides users through the process. 

Now let’s consider the complex functionality the user doesn’t see. How does this data appear in the fields displayed in this interaction? And how does the updated data get saved? This is where Omnistudio Data Mappers get to play their part. A Omnistudio Data Mapper Turbo Extract retrieves the data from the Account object, and an Omnistudio Data Mapper Load saves the data updates back to the Account object. In this unit, you learn how to build these Omnistudio Data Mappers.

Ready? Let’s dive in.

Build a Omnistudio Data Mapper Turbo Extract

You learned in the last unit that when you’re ready to configure an Omnistudio Data Mapper, you use the OmniStudio Omnistudio Data Mapper Designer, which you access via the OmniStudio Omnistudio Data Mappers tab in the OmniStudio app. 

When you build an Omnistudio Data Mapper Turbo Extract, use the following tabs in the Omnistudio Data Mapper Designer to specify what you want the Turbo Extract to do. 

• Extract tab
  
• Preview tab
  

Let’s explore these tabs in more detail and get an overview of the steps you need to take in the tabs. 

Extract Tab

On the Extract tab, you need to:

• Specify the Salesforce object that you want the Omnistudio Data Mapper to query.
  
• Set the filters that determine the data retrieved from the object.
  
• Specify the fields to extract.
  

Here’s how to do that for our Edit Account OmniScript example. 

1. For the Edit Account OmniScript, you want to extract data from the Account object, so you choose Account for the source object.
   
   
2. The Extract Output Path (1) specifies the top-level JSON node in the output. This is typically the same as the source object, so you type Account in the Extract Output Path field.
   
3. Create a filter that determines the data to be read. A filter consists of three fields: The source object (2); a comparison operator (3); and either a quoted literal value, an input parameter, or another field of the same source object (4). In our example you want to retrieve data for the Edit Account OmniScript, so enter Id = AccountId in the three fields.
   
4. Under Search Fields, use the right arrow to select Name, Phone, and Website. These are the fields you want to extract.
   
5. You can enter a value in the Search Fields box (5) to filter the field list. The Id field (6) is always included in the output.
   

Preview Tab

Test the input and output of the Omnistudio Data Mapper on the Preview tab. 

Specify a Key/Value pair in the Input Parameters panel (1), by entering AccountId for the Key and an account’s RecordId for the Value (we explain how to find the RecordId next). When you execute the Omnistudio Data Mapper Turbo Extract, the Response pane (2) returns results to confirm it is extracting data correctly.

All records in Salesforce have a unique RecordId. To find a RecordId for an account, simply open any Account record in your org, and copy the RecordId from the URL. 

Now that you’ve learned how to retrieve data from a Salesforce object, let’s see how to save updated data back to the object with an Omnistudio Data Mapper Load.

Build an Omnistudio Data Mapper Load

When you create an Omnistudio Data Mapper Load, use the following tabs in the Omnistudio Data Mapper Designer to specify what you want the Omnistudio Data Mapper Load to do.

• Objects tab
  
• Fields tab
  
• Preview tab
  

Let’s discover how to configure these tabs to build the Omnistudio Data Mapper Load.

Objects Tab

The Objects tab is where you specify the Salesforce objects that you want to update. 

Because you want to write data back to the Account object, click + Add Object (1) and then select Account (2).

Fields Tab

On the Fields tab, map the input data to the Salesforce object fields that you want to update.

The Input JSON Path (1) specifies the key of the JSON node containing the data you want to write to the Salesforce object. The Domain Object Field (2) specifies the field in the Salesforce object that you want to update. 

1. Get the JSON. When you execute the OmniScript, it builds a Data JSON that is populated with the data required for the interaction. This OmniScript JSON is what you use as input data for the Omnistudio Data Mapper Load. You can find the OmniScript JSON in the Request Data pane in the OmniScript’s Action Debugger.
   
2. Paste this JSON into the Input JSON panel (3) to create input mappings, then use the Quick Match button (4) to match the input mappings with the object fields.
   

Preview Tab

On the Preview tab, test the output of the Omnistudio Data Mapper. 

Make a change in the OmniScript JSON input in the Input panel (1). For example, change the account’s phone number or website. The Objects Created panel (2) lists the resulting objects, which are saved permanently.

Create or Update: How Does an Omnistudio Data Mapper Load Decide?

An Omnistudio Data Mapper Load saves updates to records in Salesforce by either overwriting existing data, or creating new records, too, if that data doesn’t yet exist. We call this process of updating or inserting records upsert. 

It’s possible to designate any field in the Omnistudio Data Mapper Fields mapping as an Upsert Key (1) by selecting the checkbox, which means it is required to match a unique record in Salesforce. 

To control how data is upserted, select the Is Required For Upsert checkbox (2). When this is selected for a field, there must be data present in that field, otherwise the Omnistudio Data Mapper will not upsert the record. It’s also possible to designate any field in the Omnistudio Data Mapper Fields mapping as Required For Upsert, meaning data must be present in the field for an upsert to take place.

Let’s look at this for the AccountId mapping in the Fields tab.

Before an Omnistudio Data Mapper Load decides how to save data, it checks for two conditions. 

1. Does the new record have data in all of the Is Required For Upsert fields?
   
2. Do all of the Upsert Key fields for the new record match a unique record in Salesforce?
   

This is what the process looks like when you combine the two conditions.

1. For each Object in the Input JSON, the Omnistudio Data Mapper Load looks at each field.
   

• If the field is marked Is Required For Upsert, the Omnistudio Data Mapper Load checks to see if the field has data.
  
• All Is Required For Upsert fields must have data. If not, the Omnistudio Data Mapper Load skips that record.
  

2. If the field does have data, the Omnistudio Data Mapper Load checks to see if the field is an Upsert Key, and then compares all the fields that are Upsert Keys.
   

• If all of the Upsert Keys together find a match with an existing record in Salesforce, the Omnistudio Data Mapper updates the target record rather than create a duplicate record.
  
• If the Omnistudio Data Mapper Load can’t find a match with any existing record, it creates a new record.
  

You wanted the deets on Omnistudio Data Mappers, and we delivered! However, this is just the start of your Omnistudio Data Mapper journey. We recommend you continue to other modules on this trail, where you learn how to build the other types of Omnistudio Data Mappers. 

The Omnistudio Data Mapper naming convention needs to be in the lowerCamelCase.