Build a DataRaptor Turbo Extract and DataRaptor Load

Learning Objectives

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

• Build a DataRaptor Turbo Extract.
• Build a DataRaptor Load.
• Explain how a DataRaptor 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 DataRaptors get to play their part. A DataRaptor Turbo Extract retrieves the data from the Account object, and a DataRaptor Load saves the data updates back to the Account object. In this unit, you learn how to build these DataRaptors.

Ready? Let’s dive in.

Build a DataRaptor Turbo Extract

You learned in the last unit that when you’re ready to configure a DataRaptor, you use the OmniStudio DataRaptor Designer, which you access via the OmniStudio DataRaptors tab in the OmniStudio app. 

When you build a DataRaptor Turbo Extract, use the following tabs in the DataRaptor 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 (sObject) that you want the DataRaptor 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 DataRaptor 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 DataRaptor 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 a DataRaptor Load.

Build a DataRaptor Load

When you create a DataRaptor Load, use the following tabs in the DataRaptor Designer to specify what you want the DataRaptor Load to do.

• Objects tab
• Fields tab
• Preview tab

Let’s discover how to configure these tabs to build the DataRaptor 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 DataRaptor Load. You can find the OmniScript JSON in the Request Data pane (1) 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 DataRaptor. 

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 a DataRaptor Load Decide?

A DataRaptor 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 DataRaptor 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 DataRaptor will not upsert the record. It’s also possible to designate any field in the DataRaptor 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 a DataRaptor 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 DataRaptor Load looks at each field.
   1. If the field is marked Is Required For Upsert, the DataRaptor Load checks to see if the field has data.
   2. All Is Required For Upsert fields must have data. If not, the DataRaptor Load skips that record.
2. If the field does have data, the DataRaptor Load checks to see if the field is an Upsert Key, and then compares all the fields that are Upsert Keys.
   1. If all of the Upsert Keys together find a match with an existing record in Salesforce, the DataRaptor updates the target record rather than create a duplicate record.
   2. If the DataRaptor Load can’t find a match with any existing record, it creates a new record.

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