DataRaptor: Extract a List of Records

Create a DataRaptor that returns a list of records. 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 list of records from Salesforce. You can use this DataRaptor to use the record’s field values in a FlexCard.

I come across the following use cases the most (or some combination thereof). These are like the basic G-C-D chords on a guitar – learn the basics and riff from there:

• Get records that are related to a specific record (e.g. on an Account, see a list of all Contacts).
• Get records that meet certain criteria (e.g. see a list of all Cases where Status = Open).
• Get records that share the same parent as the current record (e.g. from a Case, see a list of other Cases that are open for the same Account).

The main steps of this guide cover the first scenario. At the end, there are notes on how to modify it for the other two.

---

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.
   1. 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).
   2. Interface Type:  Extract
      Read data from Salesforce with Extracts; insert and/or update data with Loads; manipulate data with Transforms.
   3. 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.
   4. Output Type:  JSON
      You output JSON because that’s what FlexCards are setup to consume.
   5. 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).
   In this example, I refer to the Contact object.
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, I use “Contact”.
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 record Id. In this example, I use AccountId.
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). In this example, I use “currentAccountRecordId”.

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

Nothing truly special has to be done to make a DataRaptor return a list vs. a single record… just like any query, if it finds more than one record matching the criteria, it will return them all. If there are certain situations where you want to hedge your bet and limit the returned results, you can always add a LIMIT in your filter criteria.

---

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.  This also allows us to more easily refer to field names in our FlexCards.

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.

Do you notice that in the response, some of my Contacts don’t have a rank? When a field is blank, the DataRaptor doesn’t even return a blank value. Your FlexCard won’t either. This is an important lesson to learn: make sure your test records have data in all the fields you are referencing so they show up in your DataRaptor and FlexCards with test data that’s complete – you will go nuts trying to find that missing field during your build, only to find your test records were incomplete the entire time. Logout, pop two Advil, and call your therapist if necessary.

---

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.
• I can’t get my query to filter based on a boolean (checkbox) field.
  OmniStudio is finicky – it wants some values in very specific formats. To query based on a boolean field, you need to refer to the values true or false in quotations, as if that’s the literal field value (because, in a way, it is). So if I were querying Cases using the IsClosed field, the values would be entered as “true” or “false” (yes, you must include the parentheses).
• How do I query for records where the value is blank or empty?
  Oooh, you’re getting deep: searching for something that isn’t there? Existential. Like a toddler that only eats chicken nuggets and apple sauce, they want it in a specific way. For the DataRaptor, make the field value is $Vlocity.NULL (no quotation marks). For a toddler, make sure the nuggets aren’t touching the apple sauce.
• How do I do custom logic in my query?
  In a Flow’s Get Records resource, you might have 3 criteria and the logic might be 1 AND (2 OR 3). That’s a bit much for a simple DataRaptor. I think. I haven’t found a documented way. You can do basic 1 AND 2 AND 3, but the moment I start mixing ANDs and ORs, I get undesirable results. If this is you, I believe you might want to explore an Integration Procedure or a SOQL query as your FlexCard’s data source.

---

Extend This: Get Records That Meet Certain Criteria

If you don’t want records based on a record Id, no problemo. You can base your query on whatever filter criteria you want.

In this scenario, I want all Cases where the Status = New. Simples. See the below screenshots.

Extract tab:

Output tab:

Preview tab:

---

Extend This: Get Records That Share the Same Parent

Well, what if you want to see some related records. They aren’t directly related to your current record, but they share a parent. Consider a Case record layout: sometimes it’s important to see a list of other cases that are currently open for the same Account.

Mafi mushkila! But you will need at least two Extract Steps, the current record’s Id, and the number of a good therapist because what happened to you to make you this way!?

1. Extract Step #1 queries Case where Id = currentRecordId (or whatever your input parameter is called). You call the Output Path “Case”. In the DataRaptor aether, the AccountId field is now available to you as Case:AccountId (you can’t see it, but Ted Lasso would say you need to Believe).
2. Extract Step #2 queries Case where AccountId = Case:AccountId. You call the Output Path “OtherCases”.
3. On the Output tab, you map the fields: OtherCases:Id, OtherCases:CaseNumber, OtherCases:Subject, OtherCases:Status, and any others to extract them with your DataRaptor and make them available in a FlexCard. You only need your DataRaptor to output these OtherCases records (nothing from the Case node), so only map values from Extract Step #2 and remove the node name in your Output JSON Path for each mapping, like this:
   1. Extract JSON Path = OtherCases:Subject
   2. Output JSON Path = Subject
   3. This allows you to easily reference the field names while building your FlexCard.

If I did a terrible job of walking through the configuration steps, see the below screenshots for the help I failed to provide.

Extract tab:

Output tab:

Preview tab:

---