Dataraptor Load And Extract

DataRaptor Load and Extract

Use this skill when building or troubleshooting DataRaptor Extract (reading data from Salesforce via SOQL) or DataRaptor Load (writing data to Salesforce via DML) in OmniStudio. This covers multi-object extracts, Turbo Extract vs standard Extract selection, load upsert configuration, output mapping, and error handling patterns.

Before Starting

Gather this context before working on anything in this domain:

• Identify whether you need to read data (Extract) or write data (Load). These are different DataRaptor types with different configuration surfaces.
• For Extract: know the SOQL relationships you need — cross-object lookups use dot notation, parent-child relationships use sub-selects.
• For Load: know the DML operation (insert, update, upsert, delete) and the upsert key field if using upsert.
• Be aware that DataRaptor Load does NOT support Bulk API — it uses standard row-at-a-time DML. Do not use DataRaptor Load for high-volume data operations.

Core Concepts

DataRaptor Extract

DataRaptor Extract is an OmniStudio data retrieval tool that executes SOQL queries and maps results to output JSON. Key behaviors:

• SOQL base object: The primary FROM object. Cross-object fields use dot notation (e.g., Account.Name).
• Parent-to-child relationships: Use SOQL sub-selects to retrieve child records.
• Output mapping: Maps SOQL field paths to JSON keys in the output, using dot-notation to define nested JSON structure.
• Preview tab: Always test your extract in the Preview tab before embedding in an Integration Procedure.

Turbo Extract vs Standard Extract

DataRaptor Turbo Extract is a faster read-only variant:

• Supports only direct field reads — no relationship queries, no sub-selects
• Cannot traverse parent-child relationships
• Significantly faster for simple lookups
• Use Turbo Extract for single-object field retrieval where performance matters

Standard Extract supports relationship queries, sub-selects, and complex output mapping. Use it when you need cross-object data.

DataRaptor Load

DataRaptor Load is an OmniStudio DML tool for writing records to Salesforce sObjects. Key behaviors:

• Supported operations: Insert, Update, Upsert, Delete
• Upsert key: For upsert operations, specify the External ID field for matching. Must be designated as External ID on the field definition.
• Multi-object support: A single Load can write to multiple objects in sequence.
• Error handling: Load returns an iferror node in output JSON when DML fails. Check this node downstream in your Integration Procedure.
• No Bulk API: Uses standard DML — row-at-a-time. Not suitable for high-volume operations.
• No rollback on partial failure: Records written to early objects in a multi-object Load are not rolled back if a later object fails.

Common Patterns

Multi-Object Relationship Extract

When to use: Need to retrieve an Account and its related Contacts together for an OmniScript.

How it works in Extract configuration:

1. Set base object to Account
2. SOQL: SELECT Id, Name, (SELECT Id, LastName, Email FROM Contacts) FROM Account WHERE Id = :accountId
3. Output mapping: Name → account.name, use the Contacts sub-select relationship name for nested child records

Why not two separate extracts: Single extract with sub-select is more efficient — one SOQL query vs two. Child records are automatically nested in output JSON.

Upsert with External ID

When to use: Receiving data from an external system where records may or may not already exist.

How it works in Load configuration:

1. Set operation to Upsert
2. Specify the External ID field (e.g., External_Id__c) — must be designated as External ID on the field
3. Map the incoming JSON path to External_Id__c and all other fields to update

Handling iferror in Load

When to use: Any Load step that needs to handle DML failures gracefully.

How it works:

1. After the Load step in your Integration Procedure, add a conditional check
2. Check output path <LoadStepName>:iferror — if present, a DML error occurred
3. Read <LoadStepName>:iferror:message for the error description
4. Branch on the error to return a user-friendly message or attempt compensating actions

Decision Guidance

Recommended Workflow

1. Determine operation type. Read → Extract. Write → Load.
2. For Extract: Write and validate the SOQL in Developer Console first. Confirm it returns expected data.
3. For Extract: Design output mapping — map each SOQL field path to desired JSON key path. Test in Preview tab.
4. For Load: Identify DML operation and input JSON structure. Map each input path to the target sObject field.
5. For Load with upsert: Confirm the External ID field exists on the object and is marked External ID. Map it in Input Mapping.
6. Test using the Preview tab before embedding in an Integration Procedure.
7. Add error handling downstream in the Integration Procedure — check iferror output path from any Load step.

Review Checklist

• Extract SOQL validated in Developer Console before configuring the DataRaptor
• Output mapping tested in Preview tab and JSON structure confirmed
• Turbo Extract used where only simple field reads are needed
• Load upsert key field confirmed as External ID on the sObject
• Integration Procedure checks iferror output from Load steps
• No Load operation used for more than ~200 records (Bulk API not supported)
• Multi-object Load: team aware there is no rollback on partial failure

Salesforce-Specific Gotchas

1. DataRaptor Load does not use Bulk API — Row-at-a-time DML means governor limits apply. For anything over a few dozen records, this causes performance problems or limit violations.
2. No rollback on multi-object Load failure — If Load writes to Object A then fails on Object B, Object A records are already committed. Design single-object Loads where possible, or implement compensating actions.
3. Output mapping path uses API relationship name, not label — SOQL child relationship paths must use the API relationship name (e.g., Contacts, not Contact). Using the label causes empty output.

Output Artifacts

Related Skills

• dataraptor-patterns — DataRaptor Transform operations (different type)
• integration-procedures — Using DataRaptor as steps within an Integration Procedure
• omnistudio-debugging — Debugging DataRaptor Preview and Integration Procedure execution