Configure an Omnistudio Data Mapper Extract

Configure a Data Mapper Extract by specifying the object and filters. To enhance the performance of the Data Mapper Extract, you can define formulas, add fields to write data to, create mappings, and configure additional properties.

1. From the App Launcher, find and select Data Mappers.
2. Select the Data Mapper Extract that you want to configure.
3. Click Extract, and complete these steps:
   1. To add an object, click +. If you’re using the designer on a managed package, click Add Object.
   2. Search and select an extraction object.
   3. Enter an extraction object path.
   4. Add required filters that determine the data to be read. To filter for null values, use the $Vlocity.NULL variable.

      The most basic filter is Id = Id, which sets the Id of the object to an input parameter named Id. Data Mapper Extract also supports case-sensitive filter queries using Equals, and case-insensitive filter queries using Not Equal To. The INCLUDES and EXCLUDES operators apply only to multi-select picklist fields. See Querying Multi-Select Picklists in Salesforce Help. Turbo Extract has an additional operator option, IN. The IN operator lets you match values to items in an array. For example, if the filter is LastName IN Names, and the JSON input is {"Names": ["Miller", "Torres"]}, records with Miller or Torres in their LastName fields are retrieved.

      When you use the Equals filter (=) with a null value, the filtering doesn't function correctly due to a known limitation. To prevent this issue, add an additional Not Equal To (!=) filter. For example, to filter for null account values that have a phone number associated with them, use accountId = null AND phone != null.

   5. To configure additional filters, click and choose filters:

      • AND: Add another filter and specify that both filters must be true.

      • OR: Add another filter and specify that either filter can be true.

      • LIMIT: Valid values are 1 through 50000; the default is 50000.

      • OFFSET: To implement paging logic, add a filter to specify where record retrieval starts. The OFFSET must be a dynamic, not a static, value. Choose OFFSET from the dropdown list and specify the name of a node in the input payload where the caller maintains the offset (for example, offsetValue).

        

        Note The Data Mapper Extract designer adjusts filter logic when a new OR filter is inserted between existing filters. For more information, see this Salesforce Knowledge Article.

        Use OFFSET with LIMIT to specify the first record to appear on a page in a multi-page retrieval. The offset must be an integer. For example, if the LIMIT is 5, the offsets for successive pages are 0, 5, 10, and so on.

        

        Note Salesforce imposes a 2000-record limit on queries that use OFFSET. Allowed OFFSET values are from 0 to 2000. See Workaround for offset 2000 limit on SOQL query.

      • ORDER BY: Sort the results by the specified field. To sort by multiple fields, specify a comma-separated list of field names in order of precedence, for example LastName,FirstName.

        You can optionally specify ASC or DESC for an ascending or descending sort. You can optionally specify NULLS FIRST or NULLS LAST to place blank values at the beginning or end. For example, you can sort Accounts by the number of employees, listing the companies of unknown size first and the largest employers last. Specify the ORDER BY value NumberOfEmployees ASC NULLS FIRST.

      • DELETE: Remove a filter.

   6. To add options to the Value list of Filter, click Data, and then click Edit Input Data. Add and define input values. For example, "BillingCountry": "USA".
   7. To view extraction step data and object fields, click Data, and then click View Extraction Step JSON. To view all objects, select Show all sObject Fields.
   

   Note

   Salesforce enforces a limit of 100 SOQL queries per Apex transaction. If you exceed this limit while extracting objects, the Data Mapper execution fails, and an error message is displayed. See Per-Transaction Apex Limits.

4. Click Formula, add a formula, and define it for the Data Mapper Extract. See Use Formulas in Omnistudio Data Mappers.
   1. To add a Formula block, click +. If you’re using the designer on a managed package, click Add Formula.
   2. In the Formula field, enter the desired logic.
   3. In the Formula Result Path field, specify a JSON node in which you want to store the formula result.
   4. If you’re using this Data Mapper for testing purposes, disable the formula. Click , and then click Disable. If you’re using the designer on a managed package, select the Disabled checkbox.
5. Click Mapping, and then click Create Mapping. If you’re using the designer on a managed package, click Output and then click +.

   Configure these settings for mapping:

   1. From the extraction step data, choose the source field.
   2. Specify the desired data output path.
   3. If you want to ensure the data is interpreted correctly, choose an output data type from the list.
   4. If needed, add a default value.
   5. To define a data transformation, add key-value pairs. This step replaces the defined key with the value in the output.
   6. Save your changes. If you want to add more mappings, click Save & New. If you’re using the designer on a managed package, click +.

   To make mapping easier for a large number of fields, paste the data from the calling Omniscript or Integration Procedure into the Expected Output pane. This populates the data output path list.

6. To quickly match an input field to an output data path, click Quick Match, and use one of these options:
   • Drag and drop: This option is available only if you’re using the designer on a managed package. Drag the source sObject field from the input field to the output field, or vice versa. For an output that has no source sObject input field, drag the output mapping from the output field to the Matched Mappings column.
   • Pair: Manually select an input field and an output field, and click Pair.
   • Auto Match: Click Auto Match. Fields with matching names are matched automatically.
7. To create a data output path and add it to the output path list for mapping, click Data > More > Edit Expected Output Data, and then add the expected output path.
8. To view the current data output path, click Data > More > View Current Output Data.
9. To view extraction step data and object fields, click Data > View Extraction Step JSON. To view all objects, select Show all sObject Fields.
10. To configure additional properties, click Options and configure these properties:
    • Specify the number of minutes that the cached value is retained in the org cache or session cache, if data caching is enabled.
    • To enable data caching, choose a cache type from the Salesforce Platform Cache Type list:
      • Session Cache: Data related to users and their login sessions.
      • Org Cache: All other types of data.

      See Improving Data Mapper Performance with Caching.

    • Configure field-level security to check the user's access permissions for the fields before executing the Data Mapper. Selecting this option disables the Org Cache, but not the Session Cache.
    • To include null values in the Data Mapper response, select Overwrite target for all null inputs.
11. Save your changes.

• When to Use Multiple Extract Steps
  The number of extract steps that you need depends on how the object types that you’re extracting from are related. There are three basic scenarios: single, single with relationship notation, and multiple.
• Relationship Notation versus Multiple Extract Steps
  Using relationship notation improves the performance of Omnistudio Data Mappers that retrieve data from a parent of the primary object. Use this notation in the Extract JSON Paths for the parent object's fields instead of adding a second object in the Data Mapper's Extract tab.