OmniStudio DataRaptors

Exercise Guide

Before You Begin

Did you sign up for a special OmniStudio Developer Edition org already? You’ll need one to
do the steps in this guide. Here’s how to request one if this is your first time completing an
OmniStudio module:
1. Sign up for a free Developer Edition org with OmniStudio.
2. Fill out the form.
a. For Email, enter an active email address.
b. For Username, enter a username that looks like an email address and is
unique, but it doesn't need to be a valid email account (for example,
[email protected]).
c. After you fill out the form, click Sign me up. A confirmation message appears.
3. When you receive the activation email (this might take about 10 minutes), open it
and click Verify Account.
4. Complete your registration by setting your password and security challenge question.
Tip: Write down your username, password, and login URL for easy access later.

Update Session Settings

1. Click the “Gear” > Setup. This opens a new tab.

2. In the Quick Find enter session and select Session Settings.
3. Scroll up the page and clear the checkbox next to Use Lightning Web Security for
Lightning web components. (The checkbox should be blank.)
4. Scroll back down and click Save.

You are logged in to your Developer Edition and you can begin practicing.

© Copyright 2021 Salesforce.com, inc. All rights reserved. 1

OmniStudio DataRaptors
Exercise Guide

Build a DataRaptor Turbo Extract and a

DataRaptor Load
Requirements
“As a user, I'd like the OmniScript that allows me to update basic account details to be able to
extract the data from Salesforce and save any updated data back into Salesforce.”

A DataRaptor Turbo Extract retrieves data from the Salesforce Account object, and a
DataRaptor Load saves the updated data back to the Account object.

Prerequisites
● None

We’ve designed our exercises for each OmniStudio module on the Build Guided
Experiences with OmniStudio trail to work regardless of whichever module a student takes
first on the trail. We’ve done the same for students who use more than one special org to
complete the trail.

If you’ve taken all the modules on the trail in order and if you’ve used the same org to build
“Team” FlexCards and OmniScripts, you can use them instead of the samples we provide.
However, the steps in these exercises are for the samples.

Tasks
1. Build a DataRaptor Turbo Extract to get Account data
2. Use an OmniScript JSON to Build a DataRaptor Load

Time
● 30 mins

© Copyright 2021 Salesforce.com, inc. All rights reserved. 2

OmniStudio DataRaptors
Exercise Guide

Task 1: Build a DataRaptor Turbo Extract to Get Account Data

1. Create a DataRaptor to pull Account data from your org.

a. Open the App Launcher, and select the OmniStudio app.

b. Select OmniStudio DataRaptors from the dropdown.

c. Click New, then enter the following information to create the DataRaptor:

Property Value Notes

DataRaptor teamGetAccountDetails Best practice naming
Interface Name conventions for
DataRaptors follow
prefixVerbObjectDetail,
use camelCase to facilitate
reading, and begin with a
lowercase letter for
Lightning Web
Component compatibility.

Interface Type Turbo Extract There are four types of

DataRaptors: Extract (to
get data from Salesforce),
Turbo Extract (retrieves
data from a single
Salesforce object type),
Load (to write data back
into the database) and
Transform (transform or
convert data from one
structure to another).

© Copyright 2021 Salesforce.com, inc. All rights reserved. 3

OmniStudio DataRaptors
Exercise Guide

Input Type JSON Click to review the

different output types but
leave as JSON.

Output Type JSON Click to review the

different output types but
leave as JSON.

d. Click Save.

2. Define the objects you are extracting data from.

a. Confirm you are on the EXTRACT sub-tab.

b. In the top field, select Account.

c. In the Extract Output Path, enter Account. This is the name of the incoming
JSON node the DataRaptor needs to find.

d. Next, define which field you want to use to identify which Account record to
pull data from. In the Interface Field API Name field, select Id. This is the field
used to filter the results, which in this case is an AccountId.

e. In the comparison operator field (the next field), confirm = is selected,

because you wish to pull from the record where the Id matches the value in
the final field.

f. In the final field, enter AccountId. This is the name of the key in the incoming
JSON.

3. Select the fields you want to extract data from.

a. At the bottom of the Extract tab, notice the list of all the fields you can extract
data from. Select the fields to extract by moving them from the left list to the
right list. The Id field is always included in the output.

b. For the Edit Account OmniScript, select Name, Phone, and Website. (Enter a
search value in the SEARCH FIELDS text box to filter the left list.)

© Copyright 2021 Salesforce.com, inc. All rights reserved. 4

OmniStudio DataRaptors
Exercise Guide

4. Preview the JSON for your DataRaptor.

a. Select the PREVIEW tab.

b. If needed, click Edit as Params.

c. Click + Add New Key/Value Pair.

d. Enter the following:

Property Value Notes

Key AccountId The Key is the parameter

you are passing to the
JSON - which was defined
in the Extract sub-tab.

value [Acme’s AccountId]

NOTE:
If you don’t already have it, locate Acme's Record Id as follows:
1. Select Accounts from the Object dropdown.

© Copyright 2021 Salesforce.com, inc. All rights reserved. 5

OmniStudio DataRaptors
Exercise Guide

2. If needed, switch the view to All Accounts.

3. Click Acme to view Acme's detail page.
4. Copy the RecordId from the URL (Account Ids always begin with 001,
Contact Ids with a 003) and paste it somewhere to use it again.
5. Return to the DataRaptor and paste the RecordId into the Value field.

e. Click Execute. (You may have to scroll down to view the button).

f. Confirm the Account details for Acme display in the response. Note,
DataRaptor Turbo Extracts always present data in a nested array, even if there
is one value.

© Copyright 2021 Salesforce.com, inc. All rights reserved. 6

OmniStudio DataRaptors
Exercise Guide

Task 2: Use an OmniScript JSON to Build a DataRaptor Load

1. Access a JSON node that you will use to build a DataRaptor Load.

a. Select OmniScripts from the dropdown menu, and open the

sample/editAccount>Sample Edit Account (Version 1) OmniScript.

b. In the Header, click Preview.

c. Enter Acme's RecordId in the Context ID field. Click Refresh if it does not
automatically do so.

d. On the right side of the screen, click Action Debugger.

e. On the preview screen, click the Next button to execute the Integration
Procedure Action that saves data.

f. In the Action Debugger, expand the IPSaveAccountDetails entry.

g. Expand the Request Data section.

Select and copy the data there and paste it to save for use in step 3d. below.
This is what you will use to build your DataRaptor. There is a clipboard icon
next to Request Data. You may use this, use keyboard shortcuts, or right-click
and select copy.

© Copyright 2021 Salesforce.com, inc. All rights reserved. 7

OmniStudio DataRaptors
Exercise Guide

2. Create your DataRaptor.

a. Select OmniStudio DataRaptors, and click New.

b. Enter the following information to create the DataRaptor:

Property Value

DataRaptor Bundle teamSaveAccountDetails

Name

Interface Type Load

c. Click Save. The DataRaptor designer opens.

© Copyright 2021 Salesforce.com, inc. All rights reserved. 8

OmniStudio DataRaptors
Exercise Guide

3. Build the teamSaveAccountDetails DataRaptor using the text you copied from your
OmniScript in Step 1.

a. On the OBJECTS sub-tab, select + Add Object.

b. Type Acc and select Account from the filtered list of options.

c. Click the FIELDS sub-tab.

d. Delete any text in the Input JSON text box, then paste in the text you copied
from the OmniScript Action Debugger (in Step 1).

e. Click Quick Match.

f. Drag the INPUT MAPPINGS over to match with the OUTPUT MAPPINGS as
follows:

Input Mappings Output Mappings

StepAccount:Name 1-Account:Name

Id 1-Account:Id

StepAccount:Phone 1-Account:Phone

StepAccount:Website 1-Account:Website

© Copyright 2021 Salesforce.com, inc. All rights reserved. 9

OmniStudio DataRaptors
Exercise Guide

NOTE:
Use the search fields at the top of the columns to filter the lists. For example,
under OUTPUT MAPPINGS, type web to quickly locate Account:Website.

g. Review the mappings, comparing them to the image above. If they’re not
correct, click the X on the match, and try again. If they’re correct, click Save.

h. Click on the mapping for Id and select the Upsert Key and Is Required For
Upsert checkboxes.

© Copyright 2021 Salesforce.com, inc. All rights reserved. 10

OmniStudio DataRaptors
Exercise Guide

NOTE:
Before a DataRaptor Load updates or inserts a new record, it checks for two
conditions: (1) does the new record have data in all of the Required for
Upsert fields, and (2) do all of the Upsert Key fields for the new record match
a unique record in Salesforce.

Each field in the DataRaptor Fields Mapping can be designated as Required for
Upsert (data must be present in the field for an upsert to take place) and/or as
an Upsert Key (required to match a unique record in Salesforce).

If a DataRaptor Load finds that one of the fields in a record is marked as

Required for Upsert but contains no data, it skips that record. Otherwise, the
DataRaptor compares all of the Upsert Key fields of the load record to fields in
existing records in Salesforce. If it finds a unique match between the Upsert
Keys and a record in Salesforce, it overwrites the existing record and updates it
with the new data. If the DataRaptor finds no match between the Upsert keys
and Salesforce, it creates a new record.

4. Click the PREVIEW sub-tab.

a. At the bottom of the Input text box, click Clear Data to refresh the data to
what you pasted before.

b. Make a small change to the data such as editing the website to be

www.acme4.com.

c. Click Execute.

© Copyright 2021 Salesforce.com, inc. All rights reserved. 11

OmniStudio DataRaptors
Exercise Guide

d. In the Objects Created text box, click the link to the Account record.

e. In the new tab, confirm the data you changed was updated. Keep this tab
open to return to later.

© Copyright 2021 Salesforce.com, inc. All rights reserved. 12

OmniStudio DataRaptors
Exercise Guide

© Copyright 2021 Salesforce.com, inc. All rights reserved. 13

OmniStudio DataRaptors
Exercise Guide

Challenge: Build Additional DataRaptors

Create more DataRaptor Turbo Extracts and DataRaptor Loads to solidify what you learned.
We’ve summarized the requirements; refer to the step-by-step instructions above if you get
stuck.

Build a DataRaptor Turbo Extract to extract data from the Contact object, and build a
DataRaptor Load to save the updated Contact data back into Salesforce.

1. Build a DataRaptor Turbo Extract that extracts the following fields from a Contact
record with exactly these names in the JSON output: Id, First Name, Last Name,
Email, and Phone.

○ To preview, locate the RecordId for Leanne Tomlin’s contact record.

2. Use the JSON output from the sample/editContact OmniScript to build your
DataRaptor Load.

○ DataRaptors assume RecordIds are Upsert Keys. Try leaving that check box
blank, but don’t forget to select the Is Required For Upsert checkbox for the
Id mapping.

Build a DataRaptor Turbo Extract to extract data from the Case object, and build a
DataRaptor Load to save the updated Case data back into Salesforce.

1. Build a DataRaptor that extracts the following fields from a Case record with exactly
these names in the JSON output: CaseNumber, Subject, Status, Id, and
CreatedDate.

○ To preview, locate the recordId for case number 00001026.

2. Use the JSON output from the sample/editCase OmniScript to build your DataRaptor
Load.

○ Don’t forget to select the Is Required For Upsert checkbox for the Id mapping.

© Copyright 2021 Salesforce.com, inc. All rights reserved. 14