Extract Data from Salesforce Objects

Learning Objectives

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

• Build a DataRaptor Extract with relationship queries.
• Build an Integration Procedure to get data from a parent sObject.

Introduction

Imagine that you design a guided interaction for customer service agents to update, change, or create a primary contact for an account. You also want it to display different fields when the customer service agent selects different options. The interaction could look something like this. 

How does the data appear in the fields displayed in this interaction? And how is the data saved once it is updated? This is where OmniStudio DataRaptors and Integration Procedures enter the OmniStudio story. And one of the main characters in this story is the DataRaptor Extract. A DataRaptor Extract retrieves data from the Account and Contact objects in Salesforce. Then, one of three different DataRaptor Loads saves the data updates to these objects. An Integration Procedure uses conditional actions to determine which of the DataRaptor Loads to execute. 

A basic DataRaptor, such as a DataRaptor Turbo Extract, pulls data from one Salesforce object (sObject) in your org at a time. The more powerful DataRaptor Extract does this, too. However, a DataRaptor Extract can also pull data from multiple sObjects.

Take the example above. In your Update Account Primary Contact OmniScript, you want to pull primary contact data from both an account and a contact. This data is stored in two sObjects: Account and Contact. (Primary Contact is a custom field in the Account record). To pull data to this OmniScript, you need to use a DataRaptor Extract. 

Build a DataRaptor Extract with Relationship Queries

Client applications need to be able to query more than a single type of object at a time. SOQL provides syntax to support these types of queries, called relationship queries, against standard objects and custom objects. Relationship queries traverse parent-to-child and child-to-parent relationships between objects to filter and return results.

Here’s how you can build a DataRaptor Extract with relationship queries. 

1. When creating the DataRaptor Extract, enter a descriptive name for the DataRaptor Interface Name field (1). Here are some best-practices for naming DataRaptors:
   • Follow prefixVerbObjectDetail.
   • Use camelCase to facilitate reading.
   • Begin with a lowercase letter for Lightning web component compatibility
2. Select Extract as the Interface Type (2).
3. Select JSON (JavaScript Object Notation) for the Input Type (3) and Output type (4) because you’re pulling data for an OmniScript.

Next, use tabs in the DataRaptor Designer to specify what you want the Extract to do. Here are the tabs you’ll use.

• Extract tab
• Output tab
• Preview tab

Let’s explore these tabs in more detail.  

Extract Tab

In the Extract tab, specify the sObject you want the DataRaptor to query, set the filters that determine the data retrieved from the object, and specify the fields to extract. 

For the Update Account Primary Contact OmniScript example, you want to extract data from the Account object. 

1. The Extract Output Path (1) specifies the top-level JSON node in the output. Because this is typically the same as the source object, select Account.
2. Create a filter to determine the data to be read. A filter consists of three fields. The first field (2) refers to a field of the source object, the second field (3) is a comparison operator. The third field (4) is a quoted literal value, input parameter, or another field of the same source object. To retrieve data for the Update Account Primary Contact OmniScript example, the filter would be Id = AccountId.

Output Tab

In the Output tab, you map data from the extract step JSON to the output JSON.

1. Click the grey plus icon (1) to add an empty mapping to the list.
2. In the Extract JSON Path field (2), choose the source field from the extract step JSON.
3. In the Output JSON Path field (3), specify the output path you want.

At this point, the DataRaptor is extracting data from the Account object. Extracting data from a single object type requires only one extract step. However, the DataRaptor also needs to extract primary contact data—such as the contact’s name, email address, and phone number—from the Contact object. 

To do this, instead of adding Contact as a second sObject in the DataRaptor’s Extract tab, use relationship notation in the Extract JSON Paths for the parent sObject’s fields.  

Relationship notation in DataRaptors is based on relationship queries in Salesforce. Using them to filter and return results improves the performance of DataRaptors that retrieve data from objects related to the primary sObject. 

Let’s look at how to configure relationship queries in a DataRaptor. The Primary Contact ID field appears four times in the Extract JSON Path. 

• The first reference is Account:PrimaryContactId__c, the Primary Contact field in the Account object.
• The other three references are fields in the Contact object:
  • Account:PrimaryContactId__r.Email
  • Account:PrimaryContactId__r.Name
  • Account:PrimaryContactId__r.Phone

The r. creates a relationship query within the Salesforce Object Query Language (SOQL) query of the DataRaptor to pull any field of the related Contact sObject. 

Preview Tab

You can test the input and output of the DataRaptor using the Preview tab. 

Specify a Key/Value pair in the Input Parameters panel (1), such as AccountId for the Key and an account’s RecordId for the Value (2). When you execute the DataRaptor Extract, the Response pane (3) returns results to confirm it is extracting data correctly.

All records in Salesforce have a unique RecordId, which you need to preview the DataRaptor. To find a RecordId for an account, open any Account record in your org and copy the RecordId from the URL. 

Now that you’ve learned how to build a DataRaptor Extract, connect it to an Integration Procedure, which is connected to the Update Account Primary Contact OmniScript.

Get Data from a Parent sObject with an Integration Procedure

After building your DataRaptor Extract, the next step is to build an Integration Procedure that passes data from the DataRaptor to the Update Account Primary Contact OmniScript.

1. In the Integration Procedure, drag a DataRaptor Extract Action from the Available Components panel to the Structure panel.
2. Give it a name that describes its purpose, such as DRGetPriContactDetails(1).
3. In the DataRaptor Extract Action’s Properties panel, select the DataRaptor Extract you want to use in the DataRaptor Interface field (2).
4. Under Input Parameters (3), add AccountId as the Data Source and Filter Value. AccountId is an arbitrary name for the RecordId, but it must be the same in each of the elements in order for the data to flow properly between them and Salesforce.

After you add a Response Action to tell the Integration Procedure what data to send back to the Update Account Primary Contact OmniScript, you’re ready to test the Integration Procedure.

In the Integration Procedure’s Preview tab, follow the same steps you took in the DataRaptor’s Preview tab.

1. In the Input Parameters panel, specify AccountId for the Key (1) and an account’s RecordId for the Value (2).
2. Click Execute (3) to run the Integration Procedure.
3. The Response pane (4) returns results to confirm it is extracting data correctly.

The Preview tab includes a debug log, which identifies any issues with the output and input for each element in the Integration Procedure. 

• To make sure the DataRaptor is connected to the Integration Procedure, select DRGetPriContactDetails and confirm that the account information displays.

If everything is correct, you can activate this version of the Integration Procedure. This makes it available for use by the Update Account Primary Contact Account OmniScript. 

After you add the Integration Procedure to the OmniScript, use the OmniScript’s Preview tab to confirm it’s working. 

• Enter the RecordId into the Context ID field (1). The existing Primary Contact is displayed (2).

Now that you know how to extract Primary Contact data from Salesforce for an entire OmniScript, head to the next unit to learn how to extract data for a Type Ahead Block within the OmniScript. 

Resources

• Salesforce Help: Relationship Queries
• Trailhead: OmniScripts
• Trailhead: OmniStudio Integration Procedures
• Trailhead: OmniStudio DataRaptors
• Trailhead: OmniScripts with Branching