DataRaptor Post

In this article we are going to cover basics of OmniStudio DataRaptor Post action. I believe you have fair understanding of OmniStudio concepts and OmniStudio DataRaptor Extract. I posted couple of articles related to that and I would recommend going through that if you are new to OmniStudio. You can go to Home page and access the articles in OmniStudio category.

In this article also I would not be covering basic of DataRatpor and I assume you have gone through other articles, or you already have explored OmniStudio.

As we know DataRaptor Extract is used to pull the data from Salesforce and as the name suggests DataRaptor we are going to use to load the data or push the data in Salesforce. This accepts JSON as input and returns JSON as response and it returns ID of created / updated records. This also provides error details if it fails because of any data or validation error or any other trigger error.

It can run in insert of update mode. We can define the upsert key to indicate if we want to insert a record or update existing records.

We are going to explore this concept using a hypothetical scenario.

Scenario – Create a Contact record in Salesforce

In this example we assume we have a simple form built in OmniScript and it captures basic details like FirstName, LastName, Email and Phone. When this form is submitted it calls our DataRaptor Post action to create or update a Contact record in Salesforce. Let’s assume email address is going to be key to decide if we are going to create a record or update an existing record.

As I mentioned DataRaptor works with JSON. You have to pass some JSON and it would return the JSON. It means two things for us: –

DataRaptor is going to read any input from JSON message only
Most importantly we need to learn basic JSON. It is simple to learn, and I assume you know the basics and you can always learn or improve.

For this scenario we are going to use below request, and we would be expecting the response as given below: –

Request JSON	Response JSON
{ “FirstName” : “Matt”, “LastName” : “Bauer”, “Email” : “mb@example.com”, “Phone” : “1212121212” }	Format of response is predefined, and we cannot control unless we wrap this DataRaptor in an Integration Procedure so for now let’s continue with default response that our DataRatptor would be providing.

Solution Approach

We got the scenario, and we got a developer org with OmniStudio. We are all set to start our journey. We normally follow a systematic approach that you would be doing when you work on real-time project but here, we can just jump on to development.

1. Prepare Data Mapping Document

Map both Input and Output JSON attributes to Salesforce Object and Fields. This is simple JSON so we know where to get the information, but things would not be same for all scenarios.

For this requirement we know we have to update “Contact” Object and we need to populate FirstName, LastName, Email & Phone and we are going to stick with default response that our DataRaptor would be providing.

2. Create new DataRaptor

In your Salesforce Developer Org Search for DataRaptor

Create a new DataRaptor record using New Button and provide details like Name and Interface Type. Since we are developing a DataRaptor POST (also referred as Load) we would be using “Load” as Interface type. Input Type and Output Type you can leave the default for now as we are going to work on JSON. Here output type is indicated as sObject but you get output as JSON only. Other type like XML / Custom most likely you would never use.

3. Configure Object Details

Since we are going create / update a contact record we would be using only one object here and configuration is going to be very simple as given below

4. Configure Fields tab to define mapping between Salesforce field and JSON structure

Configure all fields that you would like to update during this action. You can provide default value during mapping. Let’s give a closer look at how the window to define fields mapping looks like.

1.Contact: – This is coming from our configuration at Objects tab. since we have defined only one object it is showing the number and corresponding Object name. If we add more than one objects (will see it below) it would show tab for each objects defined.
All: – This tab is going to show all mapping. In this case it would show same as 1.Contact but if you have multiple Object configured this would show you list of all mapping at single tab
INPUT JSON PATH: – This refers to JSON attribute in input. This could be at root level or nested inside two level down
DOMAIN OBJECT FIELD: – This is going to be field from Salesforce Object. In this case it would be Contact
Input JSON: – This is going to be very useful once you are comfortable with basic. We can add our input JSON here and use the Quick Match to quickly match the JSON attributes with corresponding Salesforce fields
Quick Match: – This provides a drag and drop ability to do the mapping to Salesforce fields using input JSON

Since we have Input JSON we are going to use Quick Match to save time. Believe me this would be vey helpful once you start working on complex input structure. I can simply copy our input JSON to this placeholder (as given below) and click on Quick Match button

Refer the below image and you can see our input JSON appears in input section and all Salesforce fields appear in output mapping section

See how it looks like once we are done with our field mappings. We can use search to find the field if list is big

Once you are done and click Save it is going to create mapping records that you can see and update as needed

You can expand the mapping reocord if you need to update additional information that would not be available on “Quick Match”. Few important attributes are highlighted here: –

Default Value: – You can add a default value for scenario where you have some mandatory attributes blank in input JSON or anything else you are not capturing on OmniScript form but want to default it
Upsert Key: – We are going to check this flag here for Email as we decided to use Email as key to decide if we are going to Create a record or Update an existing record
Is Required For Upsert: – As name says we can check this flag if we want to flag this attribute as require for Upsert purpose

5. Formulas & Options Tab

We are going to skip these two tabs for now and we would cover it in some other articles. We can do lot in formulas and knowledge of Options would be useful in some scenarios.

6. Preview the configuration

This tab allows us to validate our configuration. Most of the time when we work on DataRaptor we would not be having front end ready to connect and test so this provides us ability to unit test the DataRaptor before considering it done.

When we start the DataRaptor configuration we get set of requirements and based on requirement we prepared our request JSON, so we got everything to validate our work and deploy to integrated environment for testing and integrating with other components like Integration Procedures, Flex Cards or OmniScripts.

In Preview we see three panels: –

Input Parameters: – This is where we provide input JSON for our testing. We can use key value pair for simple JSON, or we can move to “Edit as JSON” and add our JSON directly. Most of the time we get JSON from requirement or from OmniScript / IP Data JSON and use that as input.
Response: – As the name suggests this is the panel where we see our response. This is the response that DataRaptor would be returning when it is called from OmniScripts / IP / APEX etc…
Error / Debug Output: – This panel provides important information mostly used during debugging if something is not working properly. We can validate the SOQL to ensure DataRaptor is generating correct SOQLA as per our configuration

With this we are done with development and unit testing of our DataRaptor Post / Load. You can try testing with different JSON and validate the result in Salesforce. You can try using same email and see if it updates the same contact record and does not create a new record. Try adding default value for some fields and see how it works. You have lot to explore and master the concept.

Before closing this article, I would add one more requirement and that would give you exposure of working on multiple objects. Let’s assume we got an additional requirement where input would contain one additional attribute AccountName. We would like to create a new Account and new Contact and associate the new Contact with new Account.

Refer the below image to understand what we have to do to meet this requirement.

Updated Configuration for Objects

Added Account Object
Changed the sequence of Account to 1 and Contact to 2 by dragging it
Create a Link using “Add Link” button and use Contact:AccountId to link Account:Id