DataRaptor: Extract a Single Record

Create a DataRaptor that returns a single record. This post is part of the FlexCard Design Thinking mini series.

This is a step-by-step guide for creating a DataRaptor that extracts a single, specific record from Salesforce. You can use this DataRaptor to use the record’s field values in a FlexCard.

---

Create the DataRaptor

1. From the OmniStudio app (or in legacy installs, the Vlocity app), open the OmniStudio DataRaptor tab.
2. Click the “New” button to create a new DataRaptor.
   • DataRaptor Interface Name:  name_for_your_DataRaptor
     No spaces but underscores are okay. I usually have a prefix to sort/group my DRs followed by a “Get” statement (e.g. GPS_GetFundingProgram, GPS_GetFundingProgramObjectives, GPS_GetSetAsideCategories).
   • Interface Type:  Extract
     Read data from Salesforce with Extracts; insert and/or update data with Loads; manipulate data with Transforms.
   • Input Type:  JSON
     Your extract will be defined as JSON as you configure it; there’s no reason to change that for a basic Extract DR.
   • Output Type:  JSON
     You output JSON because that’s what FlexCards are setup to consume.
   • Description
     This is just a note for you to keep your DataRaptors straight, if you need a helpful description of what it does or how you are using it.
3. Click the “Save” button.

---

Configure the Extract Tab

On the Extract tab, you define your query. You have to do this first.

1. Add an Extract Step. Select the object you want to pull data from (listed by object API names).
2. Extract Output Path:  your_node_name
   Choose a short name for the node where the DR will store your returned data. I use abbreviated names for my object (e.g. “Eval” for “Evaluation__c”, “FP” for “outfunds__FundingProgram__c”). In this example, it doesn’t matter much – we aren’t going to use it for much.
3. Filter:  Id
   Select the field you will use to filter your query of the object. Most of the time, I’m filtering by a recordId, so I choose Id.
4. Operator:  =
   This should be the default value. You might choose a different operator for a more complex query, but we’re trying to match, so = it is. Make sure this is NOT blank.
5. Value:  name_of_your_input_parameter]
   This is the name of the input parameter you will use to pass a value from the FlexCard to the DataRaptor to make your query work. I tend to use descriptive parameter names so it’s obvious to me later what they are (e.g. RecordId, AccountId, CurrentRecordId, FundingProgramId, or something similar or appropriate for your query).

That’s it! For a more complicated query, you might add additional Extract Steps to query additional objects in the same DataRaptor.

---

Configure the Output Tab

On the Output tab, you take the field values from your query (called the Extract JSON Path) and map them to variable names you wish to use in your FlexCard (called the Output JSON Path). This is also a chance to structure the returned data JSON – we are actually going to simplify the output JSON so that data isn’t nested under any nodes… we want to keep it simple.

For each field you want to use in the FlexCard, you will create a pairing that maps the extract to the output. So for each field:

1. Click the Add New Mapping “+” icon.
2. Extract JSON Path:  field_api_name
   Select a field name from the drop down menu. Note that your fields are listed with your node name from the Extract tab – this is useful in situations where your query multiple objects with multiple Extract Steps, but we only have one.
3. Output JSON Path:  any_name_you_want
   No spaces but underscores are okay. I get easily confused if I rename these, so I usually stick with the api names.
4. Output Data Type
   By default, all output is formatted as a string value, so I usually leave this alone unless I’m working with Currency and Date fields.

Repeat for all the fields you want to bring into your FlexCard.

---

Test Your Extract on the Preview Tab

Now let’s see if your extract DataRaptor works.

1. In Salesforce, find an existing record from the object you are querying. Copy the record Id from the URL.
   Make sure this record has a value in each field you designated on the Output tab.
2. In your DataRaptor, go to the Preview tab.
3. In the Input Parameters pane, click “Edit as Params” and then “+ Add New Key/Value Pair”.
4. Key:  name_of_your_input_parameter_from_above]
   This is just the name of the input parameter you designated on the Extract tab to execute your query (e.g. RecordId, AccountId, CurrentRecordId, FundingProgramId, or something similar or appropriate for your query).
5. Value:  [paste your record Id]
   This is the Id you copied from the URL of your test record in Salesforce.
6. Click the “Execute” button.

If everything is working, you should see some returned data in the Response pane.

---

Common Troubleshooting for Your DataRaptor

• I don’t see a field listed in my test response on the Preview tab.
  Make sure your test record has a value in that field – DataRaptors do not return fields with null values. Also, check to make sure your input parameter Key matches what you specified in your Extract Step.

---

Extend This: Grab Related Record Details

If you have relationship fields on this object, you can reach through them to grab field values from the related record. For instance, if your object has a relationship field called Related_Account__c, grab the Account’s Name field and add that value to your extract output:

1. On the Output tab, click the Add New Mapping “+” icon.
2. Extract JSON Path:  field_api_name_for_the_relationship_field
3. Manually modify the Extract JSON Path to follow this format:  Related_Account__r.Name
4. Output JSON Path:  any_name_you_want
   No spaces, and don’t include the dot [.] notation… for related records, I usually include a prefix and then the field’s API name.
5. On the Preview tab, re-test your DataRaptor to see your new value in the JSON output.

---