Building Omnistudio Integration Procedure

building-omnistudio-integration-procedure: OmniStudio Integration Procedure Creation and Validation

Expert OmniStudio Integration Procedure (IP) builder with deep knowledge of server-side process orchestration. Create production-ready IPs that combine DataRaptor/Data Mapper actions, Apex Remote Actions, HTTP callouts, conditional logic, and nested procedure calls into declarative multi-step operations.

Scope

• In scope: Creating well-structured Integration Procedures from requirements; selecting and wiring element types (DataRaptor, Remote Action, HTTP, Conditional Block, Loop, Set Values, nested IP); dependency validation; error handling patterns; 110-point scoring; deployment and activation
• Out of scope: Building OmniScripts (use building-omnistudio-omniscript), creating Data Mappers directly (use building-omnistudio-datamapper), designing FlexCards (use building-omnistudio-flexcard), mapping full dependency trees (use analyzing-omnistudio-dependencies), deploying metadata to org (use deploying-metadata)

---

Required Inputs

• Purpose: What business process is this IP orchestrating? (e.g., "onboard a new account", "process an order")
• Target objects / data sources: Which Salesforce objects, external APIs, or both?
• Type / SubType naming: PascalCase pair that uniquely identifies the IP (e.g., Type=OrderProcessing, SubType=Standard)
• Target org alias: Authenticated org alias for deployment (e.g., myDevOrg)

---

Quick Reference

Scoring: 110 points across 6 categories. Thresholds: ✅ 90+ (Deploy) | ⚠️ 67-89 (Review) | ❌ <67 (Block - fix required)

---

Core Responsibilities

1. IP Generation: Create well-structured Integration Procedures from requirements, selecting correct element types and wiring inputs/outputs 2. Element Composition: Assemble DataRaptor actions, Remote Actions, HTTP callouts, conditional blocks, loops, and nested IP calls into coherent orchestrations 3. Dependency Analysis: Validate that referenced DataRaptors, Apex classes, and nested IPs exist and are active before deployment 4. Error Handling: Enforce try/catch patterns, conditional rollback, and response validation across all data-modifying steps (DML — Data Manipulation Language)

---

CRITICAL: Orchestration Order

analyzing-omnistudio-dependencies -> building-omnistudio-datamapper -> building-omnistudio-integration-procedure -> building-omnistudio-omniscript -> building-omnistudio-flexcard (you are here: building-omnistudio-integration-procedure)

Data Mappers referenced by the IP must exist FIRST. Build and deploy DataRaptors/Data Mappers before the IP that calls them. The IP must be active before any OmniScript or FlexCard can invoke it.

---

Key Insights

Core Namespace Discriminator: OmniStudio Core stores both Integration Procedures and OmniScripts in the OmniProcess table. Use IsIntegrationProcedure = true or OmniProcessType = 'Integration Procedure' to filter IPs. Without a filter, queries return mixed results.

CRITICAL — Creating IPs via Data API: When creating OmniProcess records, set IsIntegrationProcedure = true to make the record an Integration Procedure. The OmniProcessType picklist is computed from this boolean and cannot be set directly. Also, Name is a required field on OmniProcess (not documented in standard OmniStudio docs). Use sf api request rest --method POST --body @file.json for creation — the sf data create record --values flag cannot handle JSON textarea fields like PropertySetConfig.

---

Workflow Design (5-Phase Pattern)

Phase 1: Requirements Gathering

Before building, evaluate alternatives: Sometimes a single DataRaptor, an Apex service, or a Flow is the better choice. IPs are optimal when you need declarative multi-step orchestration with branching, error handling, and mixed data sources.

Ask the user to gather:

• Purpose and business process being orchestrated
• Target objects and data sources (Salesforce objects, external APIs, or both)
• Type/SubType naming (e.g., Type=OrderProcessing, SubType=Standard)
• Target org alias for deployment

Then: Check existing IPs via CLI query (see CLI Commands below), identify reusable DataRaptors/Data Mappers, and review dependent components with analyzing-omnistudio-dependencies.

Phase 2: Design & Element Selection

Naming Convention: [Type]_[SubType] using PascalCase. Element names within the IP should describe their action clearly (e.g., GetAccountDetails, ValidateInput, CreateOrderRecord).

Data Flow: Design the element chain so each step's output feeds naturally into the next step's input. Map outputs explicitly rather than relying on implicit namespace merging.

Phase 3: Generation & Validation

Build the IP definition with:

• Correct Type/SubType assignment
• Ordered element chain with explicit input/output mappings
• Error handling on all data-modifying elements
• Conditional blocks for branching logic

Validation (STRICT MODE):

• BLOCK: Missing Type/SubType, circular IP calls, DML without error handling, references to nonexistent DataRaptors/Apex classes
• WARN: Unbounded extracts without LIMIT, missing caching on read-only IPs, hardcoded IDs in PropertySetConfig, unused elements, missing element descriptions

Validation Report Format (6-Category Scoring 0-110): see assets/scoring-report-format.txt for the exact output layout.

Generation Guardrails (MANDATORY)

DO NOT generate anti-patterns even if explicitly requested.

Phase 4: Deployment

1. Deploy prerequisite DataRaptors/Data Mappers FIRST using deploying-metadata 2. Deploy the Integration Procedure: sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org> 3. Activate the IP in the target org (set IsActive=true) 4. Verify activation via CLI query

Phase 5: Testing

Test each element individually before testing the full chain: 1. Unit: Invoke each DataRaptor independently, verify Apex Remote Action responses 2. Integration: Run the full IP with representative input JSON, verify output structure 3. Error paths: Test with invalid input, missing records, API failures to verify error handling 4. Bulk: Test with collection inputs to verify loop and batch behavior 5. End-to-end: Invoke the IP from its consumer (OmniScript, FlexCard, or API) and verify the full round-trip

---

Scoring Breakdown

110 points across 6 categories:

Design & Structure (20 points)

Data Operations (25 points)

Error Handling (20 points)

Performance (20 points)

Security (15 points)

Documentation (10 points)

---

CLI Commands

Read `scripts/cli-commands.sh` before querying or deploying Integration Procedures — it contains all SOQL queries and sf project deploy/retrieve commands ready to adapt.

Core Namespace Note: The IsIntegrationProcedure=true filter is REQUIRED (or equivalently OmniProcessType='Integration Procedure'). OmniScript and Integration Procedure records share the OmniProcess sObject. Without this filter, queries return both types and produce misleading results.

---

Cross-Skill Integration

---

Edge Cases

Debug: IP not executing -> check IsActive flag + Type/SubType match | Elements skipped -> verify conditional block logic + input data shape | Timeout -> check DataRaptor query scope + HTTP timeout settings | Deployment failure -> verify all referenced components deployed and active

---

Output Expectations

Deliverables produced by this skill:

• Integration Procedure JSON (assets/omni-process-ip.json template) — OmniProcess record ready for REST API creation with IsIntegrationProcedure=true
• Element JSON records (assets/omni-process-element-dr-extract.json, assets/omni-process-element-set-values.json templates) — OmniProcessElement records for each action step with PropertySetConfig wired
• Validation report — 110-point score across 6 categories with deploy/review/block threshold result
• Deployment checklist — confirms prerequisite DataRaptors are active, IP is activated, and consuming OmniScript or FlexCard can invoke it

---

Notes

API: Latest (check current Salesforce release notes; was 66.0 at time of authoring) | Mode: Strict (warnings block) | Scoring: Block deployment if score < 67

Dependencies (optional): deploying-metadata, building-omnistudio-datamapper, analyzing-omnistudio-dependencies

Creating IPs programmatically: Use REST API (sf api request rest --method POST --body @file.json). Required fields: Name, Type, SubType, Language, VersionNumber, IsIntegrationProcedure=true. Then create OmniProcessElement child records for each action step (also via REST API for JSON PropertySetConfig). Activate by setting IsActive=true after all elements are created.

---

Reference File Index

Credits & Acknowledgments

This skill was built upon the collective wisdom of the Salesforce OmniStudio community. We gratefully acknowledge the following resources whose ideas, patterns, and best practices have shaped this skill.

---

<!-- Parent: building-omnistudio-integration-procedure/SKILL.md -->

Integration Procedure Best Practices

Version: 1.0.0

Applies to: OmniStudio Integration Procedures (Core namespace and Vlocity managed package)

This guide consolidates best practices for building maintainable, performant, and reliable Integration Procedures.

---

Table of Contents

Strategy & Planning 1. When to Use an Integration Procedure 2. IP vs Flow vs Apex: Decision Framework

Design & Structure 3. Element Ordering and Execution Flow 4. Naming Conventions 5. Input/Output Contract Design

Error Handling 6. Error Handling Patterns 7. Conditional Rollback

Data Operations 8. Response Mapping from Data Mappers 9. Bounded Extracts and Pagination

Performance 10. Caching Strategies 11. Batch vs Sequential Execution 12. Reducing Redundant Calls

Maintenance 13. Versioning with Type/SubType 14. Documentation Standards

---

1. When to Use an Integration Procedure

Integration Procedures are optimal when:

• You need declarative multi-step orchestration combining reads, writes, transforms, and callouts
• The process involves multiple data sources (Salesforce objects + external APIs)
• You need server-side execution without user interaction (unlike OmniScripts)
• The orchestration requires conditional branching or loop iteration over collections
• You want reusability — the same IP can be called by OmniScripts, FlexCards, Apex, or other IPs

Integration Procedures are NOT optimal when:

• A single DataRaptor can accomplish the task (no orchestration needed)
• The logic is purely computational with no data access (use Apex or a Formula)
• You need real-time user interaction during execution (use OmniScript with embedded IP calls)
• The process is a simple CRUD operation on one object (use a DataRaptor Load directly)

---

2. IP vs Flow vs Apex: Decision Framework

Rule of thumb: If the process serves OmniStudio components, use an IP. If it serves standard Salesforce UI automation, use a Flow. If it requires complex computation or fine-grained transaction control, use Apex.

---

3. Element Ordering and Execution Flow

Elements execute top-to-bottom in the order they appear in the procedure definition. Follow these ordering principles:

Recommended Order

1. Set Values — Initialize variables, set defaults, normalize input 2. Validation — Conditional Block to validate required inputs before proceeding 3. Data Retrieval — DataRaptor Extract or HTTP Action to fetch required data 4. Data Transformation — DataRaptor Transform to shape data for downstream use 5. Business Logic — Conditional Blocks, Remote Actions for decisions 6. Data Modification — DataRaptor Load to write records 7. Response Assembly — Set Values to build the output response

Ordering Rules

• Fetch before transform: Extract data before attempting to reshape it
• Validate before mutate: Check preconditions before performing DML
• Independent reads first: Group all DataRaptor Extracts at the top where possible
• Error-prone steps last: Place steps that might fail (HTTP, DML) after all preparatory work
• Response assembly at the end: Build the final output after all processing completes

---

4. Naming Conventions

Type/SubType

• Type: Business process name in PascalCase (e.g., AccountOnboarding, OrderProcessing)
• SubType: Version or variant identifier (e.g., Standard, v2, Retail)
• Combined format: Type_SubType (e.g., AccountOnboarding_Standard)

Element Names

• Use descriptive, action-oriented names: GetAccountDetails, ValidateAddress, CreateContactRecord
• Prefix with the action type for scannability: Extract_, Load_, Transform_, Check_, Call_
• Avoid generic names like Step1, Action2, Process

Variables

• Input variables: in_variableName
• Output variables: out_variableName
• Internal variables: var_variableName

---

5. Input/Output Contract Design

Define clear contracts for what the IP expects and returns:

Input Contract

{
  "accountId": "001XXXXXXXXXXXX",
  "includeContacts": true,
  "contactLimit": 10
}

• Document every expected input field with type and whether it is required
• Set default values in a Set Values element for optional inputs
• Validate required inputs with a Conditional Block before processing

Output Contract

{
  "success": true,
  "account": { "Name": "Acme Corp", "Industry": "Technology" },
  "contacts": [ { "Name": "John Doe", "Email": "john@acme.com" } ],
  "errors": []
}

• Return a consistent structure regardless of success or failure
• Include a success boolean and an errors array in every response
• Namespace outputs clearly so consumers know which element produced which data

---

6. Error Handling Patterns

Per-Element Error Handling

Every element that performs DML or makes an external call should have error handling:

1. DataRaptor Load Actions: Check the response for error indicators. Use a Conditional Block after the Load to inspect the result and branch to error handling if needed.

2. HTTP Actions: Check the HTTP status code in the response. Branch on non-2xx responses.

3. Remote Actions: Apex exceptions surface in the element response. Check for error keys in the output.

Try/Catch Pattern

Structure error handling as a three-step pattern:

1. Try: Execute the data-modifying element 2. Check: Conditional Block inspects the element's response for errors 3. Handle: Set Values element builds an error response or a Conditional Block routes to compensating actions

Error Response Structure

{
  "success": false,
  "errors": [
    {
      "element": "CreateOrderRecord",
      "code": "FIELD_CUSTOM_VALIDATION_EXCEPTION",
      "message": "Order amount exceeds credit limit"
    }
  ]
}

---

7. Conditional Rollback

When an IP performs multiple sequential DML operations and a later step fails:

Compensating Action Pattern

1. After each successful DML, store the created record IDs in variables 2. If a subsequent step fails, use stored IDs to execute compensating DataRaptor Load actions (delete/update) to undo prior changes 3. Return a clear error response indicating which steps succeeded and which failed

Design Considerations

• IPs do not have native transaction rollback across elements
• Each DataRaptor Load action may commit independently
• Plan for partial failure in multi-step write operations
• Consider whether the business process can tolerate partial completion
• For strict atomicity requirements, move the multi-DML logic to an Apex Remote Action where you control the transaction boundary

---

8. Response Mapping from Data Mappers

How Response Namespacing Works

Each element's output is stored under a key matching the element name. For example, if a DataRaptor Extract element named GetAccount returns { "Name": "Acme" }, the IP's response contains:

{
  "GetAccount": {
    "Name": "Acme"
  }
}

Referencing Upstream Outputs

In downstream elements, reference upstream data using the element namespace:

• In PropertySetConfig: %GetAccount:Name%
• In Set Values: Map from GetAccount.Name to the target variable

Common Mapping Issues

---

9. Bounded Extracts and Pagination

Setting Limits

Every DataRaptor Extract Action should have a reasonable LIMIT:

• Set the LIMIT in the DataRaptor definition itself, not in the IP
• For user-facing queries, limit to 50-200 records
• For batch processing, limit to 2000 records per iteration
• For count/existence checks, limit to 1

Pagination Pattern

For large datasets that exceed a single extract's limit:

1. First extract: fetch records with LIMIT and OFFSET 0 2. Check if result count equals LIMIT (more records may exist) 3. Loop: increment OFFSET by LIMIT, re-extract, append results 4. Exit when result count is less than LIMIT

Avoid this pattern for datasets exceeding 10,000 records — use Apex Batch or a scheduled process instead.

---

10. Caching Strategies

When to Cache

• Read-only IPs that serve reference data (picklist values, configuration)
• IPs called frequently by multiple OmniScripts or FlexCards
• IPs whose source data changes infrequently

When NOT to Cache

• IPs that perform DML (creates, updates, deletes)
• IPs whose output depends on the current user's permissions or context
• IPs that return time-sensitive data (real-time pricing, inventory)

Cache Configuration

Set caching properties in the IP's PropertySet:

• cacheType: Platform for org-level cache, Session for user-session cache
• cacheTTL: Time-to-live in seconds (e.g., 300 for 5 minutes, 3600 for 1 hour)

Cache Key Considerations

The cache key includes the IP's Type/SubType and the input JSON. Different inputs produce different cache entries. Normalize input data to maximize cache hit rates.

---

11. Batch vs Sequential Execution

Sequential (Default)

Elements execute one after another. Use when:

• Each step depends on the output of the previous step
• Strict ordering is required for business logic
• Error handling needs to stop execution on first failure

Batch / Parallel Opportunities

While IPs execute elements sequentially by default, you can optimize by:

• Grouping independent DataRaptor Extracts at the beginning of the procedure
• Using a single DataRaptor Extract with multiple output fields instead of multiple extracts
• Combining related DataRaptor Transforms into a single transform with multiple mappings
• Moving parallelizable logic into an Apex Remote Action that handles concurrent operations internally

Loop Block Performance

• Set appropriate batch sizes for Loop Blocks processing large collections
• Avoid nested loops — flatten data with a Transform first
• Minimize the number of elements inside a loop body
• Move invariant computations outside the loop

---

12. Reducing Redundant Calls

Common Redundancy Patterns

Data Passing vs Re-Fetching

Prefer passing data between elements over re-fetching:

• Use Set Values to copy data from one element's output to another element's input
• Pass context data to nested IP calls as input parameters
• Store intermediate results in variables for reuse

---

13. Versioning with Type/SubType

Versioning Strategy

• Use SubType to version IPs: Type=AccountOnboarding, SubType=v1 and SubType=v2
• Only one version of a Type/SubType pair can be active at a time
• Deploy and test the new version as inactive before deactivating the old version
• Update consumers (OmniScripts, FlexCards) to reference the new SubType after activation

Migration Checklist

1. Create the new IP with updated SubType 2. Deploy and test in sandbox with the new SubType 3. Update all consumers to reference the new SubType 4. Activate the new IP 5. Deactivate the old IP (do not delete until consumers are verified)

---

14. Documentation Standards

Procedure-Level Documentation

Every IP should have:

• A description field explaining the business purpose
• Input/output JSON contract documented in element descriptions or external documentation
• Dependency list (which DataRaptors, Apex classes, and nested IPs it requires)

Element-Level Documentation

Every element should have:

• A description explaining what it does and why
• Notes on expected input shape and output shape
• Error handling behavior documented

Maintenance Documentation

• Record the Type/SubType and the org(s) where the IP is deployed
• List all consumers (OmniScripts, FlexCards, Apex classes, other IPs) that call this IP
• Note any external API dependencies with endpoint URLs and authentication method

<!-- Parent: building-omnistudio-integration-procedure/SKILL.md -->

Integration Procedure Element Types Reference

Version: 1.0.0

Applies to: OmniStudio Integration Procedures (Core namespace and Vlocity managed package)

This reference documents every element type available in Integration Procedures, including PropertySetConfig JSON structures, input/output node mapping, and variable scoping rules.

---

Table of Contents

1. DataRaptor Extract Action 2. DataRaptor Load Action 3. DataRaptor Transform Action 4. Remote Action 5. Integration Procedure Action 6. HTTP Action 7. Conditional Block 8. Loop Block 9. Set Values 10. Variable Scoping and Data Passing 11. PropertySetConfig Common Properties

---

1. DataRaptor Extract Action

Reads data from Salesforce objects using a DataRaptor (Data Mapper) Extract definition.

PropertySetConfig

{
  "bundle": "DRExtract_AccountDetails",
  "disableFlushCacheForGet": false,
  "useQueueableApexRemoting": false,
  "additionalInput": {},
  "additionalOutput": {},
  "sendOnlyAdditionalInput": false,
  "responseJSONPath": "",
  "responseJSONNode": ""
}

Key Properties

Input Mapping

The element receives the IP's current data context. To pass specific values to the DataRaptor:

• Use additionalInput to map values from upstream elements:

  {
    "additionalInput": {
      "AccountId": "%PreviousElement:accountId%"
    }
  }

Output

The DataRaptor's output is stored under the element name in the IP response:

{
  "GetAccountDetails": {
    "Name": "Acme Corp",
    "Industry": "Technology",
    "BillingCity": "San Francisco"
  }
}

For multi-record results, the output is an array.

---

2. DataRaptor Load Action

Writes data to Salesforce objects using a DataRaptor (Data Mapper) Load definition.

PropertySetConfig

{
  "bundle": "DRLoad_CreateContact",
  "disableFlushCacheForGet": false,
  "useQueueableApexRemoting": false,
  "additionalInput": {},
  "additionalOutput": {},
  "sendOnlyAdditionalInput": false,
  "responseJSONPath": "",
  "responseJSONNode": ""
}

Key Properties

Input Mapping

Map upstream data into the fields the DataRaptor Load expects:

{
  "additionalInput": {
    "FirstName": "%SetInputValues:firstName%",
    "LastName": "%SetInputValues:lastName%",
    "AccountId": "%GetAccountDetails:Id%"
  }
}

Output

Returns the result of the DML operation:

{
  "CreateContact": {
    "Id": "003XXXXXXXXXXXX",
    "errors": [],
    "success": true
  }
}

Error Handling

Always follow a DataRaptor Load with error inspection. Check for:

• success field (boolean)
• errors array (contains error objects with statusCode and message)

---

3. DataRaptor Transform Action

Reshapes data without making any Salesforce queries or DML. Uses a DataRaptor Transform definition to map fields between JSON structures.

PropertySetConfig

{
  "bundle": "DRTransform_FlattenAddress",
  "additionalInput": {},
  "additionalOutput": {},
  "sendOnlyAdditionalInput": false,
  "responseJSONPath": "",
  "responseJSONNode": ""
}

Key Properties

Use Cases

• Flatten nested JSON structures for downstream processing
• Rename fields to match external API contracts
• Combine data from multiple upstream elements into a single structure
• Extract specific fields from a large response

Input/Output

Input: The full IP data context or specific values via additionalInput Output: The transformed JSON structure, stored under the element name

---

4. Remote Action

Calls an Apex class method. The Apex class must implement the vlocity_cmt.VlocityOpenInterface (managed package) or omnistudio.VlocityOpenInterface2 (Core namespace) interface.

PropertySetConfig

{
  "remoteClass": "AccountValidationService",
  "remoteMethod": "validateAccount",
  "additionalInput": {},
  "additionalOutput": {},
  "sendOnlyAdditionalInput": false,
  "responseJSONPath": "",
  "responseJSONNode": "",
  "useQueueableApexRemoting": false,
  "useFuture": false
}

Key Properties

Apex Interface

The Apex class must follow this pattern:

// Core namespace
global class AccountValidationService implements omnistudio.VlocityOpenInterface2 {
    global Object invokeMethod(
        String methodName,
        Map<String, Object> inputMap,
        Map<String, Object> outputMap,
        Map<String, Object> options
    ) {
        if (methodName == 'validateAccount') {
            // Business logic here
            String accountId = (String) inputMap.get('AccountId');
            // ... validation logic ...
            outputMap.put('isValid', true);
            outputMap.put('validationMessages', new List<String>());
        }
        return null;
    }
}

Input Mapping

The IP data context is passed as inputMap. Use additionalInput to add or override values:

{
  "additionalInput": {
    "AccountId": "%GetAccountDetails:Id%",
    "validationType": "full"
  }
}

Output

The outputMap contents are stored under the element name:

{
  "ValidateAccount": {
    "isValid": true,
    "validationMessages": []
  }
}

---

5. Integration Procedure Action

Calls another Integration Procedure. Enables composition and reuse of IP logic.

PropertySetConfig

{
  "ipMethod": "SharedLookup_Standard",
  "additionalInput": {},
  "additionalOutput": {},
  "sendOnlyAdditionalInput": false,
  "responseJSONPath": "",
  "responseJSONNode": "",
  "chainable": false
}

Key Properties

Input Mapping

By default, the entire IP data context is passed to the nested IP. Use sendOnlyAdditionalInput: true with additionalInput to send only specific data:

{
  "ipMethod": "ContactLookup_Standard",
  "sendOnlyAdditionalInput": true,
  "additionalInput": {
    "accountId": "%GetAccountDetails:Id%"
  }
}

Output

The nested IP's full response is stored under the calling element's name:

{
  "LookupContacts": {
    "contacts": [...],
    "totalCount": 5
  }
}

Circular Dependency Prevention

Before configuring an IP Action, verify that the target IP does not call back to the current IP (directly or through intermediaries). Circular calls cause stack overflow errors at runtime.

---

6. HTTP Action

Makes an HTTP callout to an external API endpoint.

PropertySetConfig

{
  "path": "https://api.example.com/v1/accounts",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer %GetToken:accessToken%"
  },
  "body": {},
  "additionalInput": {},
  "additionalOutput": {},
  "sendOnlyAdditionalInput": false,
  "responseJSONPath": "",
  "responseJSONNode": "",
  "namedCredential": "",
  "timeout": 30000
}

Key Properties

Security Best Practices

• Use Named Credentials for API authentication instead of hardcoded tokens
• Reference tokens from upstream elements (e.g., OAuth token retrieval) using %elementName:key% syntax
• Never store API keys in PropertySetConfig — use Custom Settings or Custom Metadata

Input Mapping

Use additionalInput to build dynamic request bodies:

{
  "body": {
    "accountName": "%GetAccountDetails:Name%",
    "externalId": "%InputData:externalId%"
  }
}

Output

The HTTP response is stored under the element name:

{
  "CallExternalAPI": {
    "statusCode": 200,
    "body": {
      "result": "success",
      "externalRecordId": "EXT-12345"
    }
  }
}

Error Handling

Check statusCode in a downstream Conditional Block:

• 2xx: Success, proceed
• 4xx: Client error, log and return error response
• 5xx: Server error, consider retry or graceful degradation

---

7. Conditional Block

Evaluates conditions and branches execution based on the result. Contains child elements that execute only when the condition evaluates to true.

Configuration

Conditional Blocks do not use PropertySetConfig in the same way as action elements. Instead, conditions are defined in the element's condition configuration:

Condition Types

Nested Elements

Elements inside a Conditional Block execute only when the condition is true. They follow the same ordering principles as top-level elements.

If/Else Pattern

Use two Conditional Blocks with complementary conditions:

1. Conditional Block A: condition = %check:value% EQUALS true -> contains success path elements 2. Conditional Block B: condition = %check:value% NOT EQUALS true -> contains error/alternate path elements

---

8. Loop Block

Iterates over a collection (array) and executes child elements for each item.

Configuration

Child Elements

Elements inside a Loop Block execute once per iteration. The current item is accessible via the loop element variable.

Performance Considerations

• Minimize the number of elements inside the loop body
• Avoid DataRaptor Extract/Load inside loops (N+1 pattern)
• Prefer bulk operations: collect data in the loop, perform a single DML after the loop
• Set appropriate batch sizes for large collections
• If loop body requires DML, consider using a single DataRaptor Load with a collection input instead

Example Pattern: Collect and Bulk Process

Instead of:

Loop -> DataRaptor Load (per item)  // BAD: N DML operations

Use:

Loop -> Set Values (collect items into array)
DataRaptor Load (entire array)  // GOOD: 1 DML operation

---

9. Set Values

Assigns values to variables within the IP context. Used for initialization, response assembly, and data transformation.

Configuration

Set Values elements define key-value mappings:

Common Uses

1. Initialize defaults: Set default values at the beginning of the procedure 2. Build output response: Assemble the final response JSON at the end 3. Intermediate variables: Store computed values for use in downstream conditions 4. Error response: Build standardized error response objects

Example: Response Assembly

Set Values: "BuildResponse"
  out_success = true
  out_accountId = %GetAccount:Id%
  out_contactCount = %GetContacts:totalSize%
  out_status = "Complete"

---

10. Variable Scoping and Data Passing

Scope Rules

Data Context

The IP maintains a cumulative data context. Each element's output is added to this context under the element's name. Downstream elements can reference any upstream element's output.

Reference Syntax

Data Passing to Nested IPs

When calling a nested IP via Integration Procedure Action:

• Default: The entire data context is passed as input
• Selective: Use sendOnlyAdditionalInput: true + additionalInput to pass specific values
• Output: The nested IP's response is namespaced under the calling element's name

Data Passing Best Practices

• Use sendOnlyAdditionalInput: true for nested IP calls to avoid leaking unnecessary data
• Keep variable names consistent across elements for readability
• Document the expected data shape at each stage of the procedure
• Use Set Values to explicitly name and scope intermediate results rather than relying on implicit context merging

---

11. PropertySetConfig Common Properties

These properties are available on most action elements:

responseJSONPath vs responseJSONNode

• responseJSONPath: Extracts a subset of the response. For example, $.records extracts only the records array from the response.
• responseJSONNode: Wraps the response under a named key. For example, setting responseJSONNode to accountData wraps the entire response under {"accountData": {...}}.

These can be combined: first extract via path, then wrap under a node name.

additionalInput Merge Behavior

When sendOnlyAdditionalInput is false (default): 1. The IP's current data context is used as the base input 2. additionalInput key-value pairs are merged into this context 3. If a key exists in both, additionalInput takes precedence (override)

When sendOnlyAdditionalInput is true: 1. The data context is ignored 2. Only additionalInput key-value pairs are sent as input 3. Use this for nested IP calls where you want a clean input boundary