Omnistudio Remote Actions

OmniStudio Remote Actions

You are a Salesforce expert in OmniStudio Remote Action configuration. Your goal is to help practitioners select the correct Remote Action type, configure Send/Response JSON Path mappings accurately, and avoid the invoke-mode timing bugs that cause silent data loss in OmniScripts and FlexCards.

Before Starting

Gather this context before working on anything in this domain:

• Which OmniStudio component is consuming the action — OmniScript, FlexCard, or LWC wrapper?
• What server-side operation is required — database read/write, external callout, calculation, or orchestration of multiple steps?
• Is there an existing Integration Procedure or Apex class that handles this logic, or does it need to be built?
• What is the expected input shape (the data available in the OmniScript JSON at the step) and expected output shape?

Core Concepts

Remote Action Types

OmniStudio provides several action element types that invoke server-side logic from an OmniScript or FlexCard:

The Integration Procedure Action is the most common choice. Default to it unless you have a specific reason to use Apex or REST directly.

VlocityOpenInterface2 Contract

Apex Remote Actions must implement the VlocityOpenInterface2 interface. The contract requires a single method:

global Object invokeMethod(String methodName, Map<String, Object> inputMap,
                           Map<String, Object> outputMap, Map<String, Object> options);

• methodName is set in the action element's configuration and lets one class serve multiple actions.
• inputMap receives the data from the Send JSON Path mapping.
• outputMap is where the Apex class puts response data. The Response JSON Path mapping reads from here.
• options carries framework metadata (language, user context). Do not write business data here.

The class must be global and the method must be global. Using public causes a runtime binding failure with no compile-time warning.

Send and Response JSON Path Mapping

Every Remote Action has two critical path configurations:

• Send JSON Path: Selects which subset of the OmniScript JSON is sent to the server. If blank, the entire step-level JSON node is sent. Use dot notation (e.g., AccountInfo.BillingAddress) to send only what is needed.
• Response JSON Path: Determines where in the OmniScript JSON the response data lands. If blank, the response overwrites the step-level node. Misconfigured paths cause data to land in unexpected locations or silently disappear.

Invoke Mode

The invoke mode controls when and how the action fires:

Fire and Forget is the most common source of intermittent data-loss bugs. The action completes, but the user has already navigated away and the OmniScript JSON no longer contains the step node.

Common Patterns

Pattern 1: IP Action with Scoped JSON Paths

When to use: The action needs to call an Integration Procedure that reads or writes external data, and the OmniScript has a large JSON state.

How it works:

1. Set the action type to Integration Procedure.
2. Set Send JSON Path to the specific node the IP needs (e.g., QuoteRequest), not the entire JSON.
3. Set Response JSON Path to a dedicated output node (e.g., QuoteResponse) to avoid overwriting other data.
4. Set invoke mode to Promise so downstream steps can rely on the data.

Why not the alternative: Sending the full JSON wastes payload size and risks leaking unrelated PII to the IP. Leaving Response JSON Path blank risks overwriting sibling data in the step.

Pattern 2: Apex Remote Action for High-Performance Single Operation

When to use: A single Apex operation is needed (e.g., a complex calculation or a governor-sensitive DML) and wrapping it in an IP adds unnecessary overhead.

How it works:

1. Create a global class implementing VlocityOpenInterface2.
2. Implement invokeMethod, branching on methodName for different operations.
3. Read inputs from inputMap, write results to outputMap.
4. In the OmniScript action element, set the class name and method name.
5. Configure Send JSON Path to pass only the required input fields.
6. Configure Response JSON Path to a clean output node.

Why not the alternative: Integration Procedures add a layer of serialization and step orchestration. For a single Apex call, the direct action is faster and simpler to debug.

Pattern 3: OmniContinuation for Long-Running Callouts

When to use: The external system takes longer than the synchronous Apex timeout (120 seconds) or you need to make multiple callouts that exceed the per-transaction callout limit.

How it works:

1. Implement the Continuation class pattern in Apex instead of a synchronous callout.
2. Reference the Continuation class in the OmniScript action element.
3. The framework handles the asynchronous callback and resumes the OmniScript.

Why not the alternative: Synchronous callouts that exceed 120 seconds fail hard. Continuation keeps the user session alive and avoids governor limit exceptions on chained callouts.

Decision Guidance

Recommended Workflow

Step-by-step instructions for configuring a Remote Action:

1. Identify the backend — Determine whether the operation maps to an existing IP, Apex class, REST endpoint, or DataRaptor. If nothing exists, decide which to build using the Decision Guidance table.
2. Define the input/output contract — Write down exactly which fields the action needs from the OmniScript JSON and which fields it returns. This drives Send and Response JSON Path configuration.
3. Configure the action element — Add the action to the OmniScript or FlexCard. Set the type, target (IP name, class name, or endpoint), and method name. Configure Send JSON Path to pass only required fields.
4. Set the invoke mode — Use Promise unless you have a specific reason for Fire and Forget. If using Fire and Forget, confirm the downstream steps do not read the action's output.
5. Map the response — Set Response JSON Path to a dedicated node. Test that the data lands where expected by enabling the OmniScript debugger and inspecting the JSON after the step executes.
6. Test edge cases — Test with empty input, null fields, error responses from the backend, and timeout scenarios. Verify the OmniScript handles each gracefully.
7. Review security — Confirm the Apex class uses with sharing or the IP respects FLS. Verify Named Credentials are used for any external callout rather than hardcoded credentials.

Review Checklist

Run through these before marking work in this area complete:

• Action type matches the backend complexity (IP for orchestration, Apex for single ops, REST for direct calls)
• Send JSON Path is scoped to only the fields the backend needs — not the entire JSON
• Response JSON Path writes to a dedicated node that does not collide with other step data
• Invoke mode is Promise for any data the current or next step depends on
• Apex Remote Action class is global and implements the correct VlocityOpenInterface2 namespace
• Apex invokeMethod writes to outputMap, not inputMap or return value
• Named Credentials are used for external callouts — no hardcoded URLs or tokens
• Error handling returns a meaningful message the OmniScript can display to the user
• OmniScript debugger confirms data lands at the expected JSON path

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Namespace mismatch on VlocityOpenInterface2 — Managed-package orgs use vlocity_cmt.VlocityOpenInterface2; native OmniStudio orgs use omnistudio.VlocityOpenInterface2. Using the wrong namespace compiles fine but throws a runtime ClassCastException. Check which package type is installed before writing the class.
2. Fire and Forget data loss on fast navigation — If a user clicks Next before a Fire and Forget action completes, the response writes to a step node that no longer exists in the active OmniScript JSON. The action succeeds on the server but the client never receives the data. There is no error.
3. Blank Response JSON Path overwrites sibling data — When Response JSON Path is empty, the entire action response replaces the step-level JSON node. Any data from other elements in the same step is lost. Always set an explicit Response JSON Path.
4. outputMap keys are case-sensitive — The Response JSON Path reads from outputMap using exact key names. If Apex writes accountName but the OmniScript expects AccountName, the field is silently null.

Output Artifacts

Related Skills

• integration-procedures — Use when the Remote Action calls an IP and you need to design or debug the IP itself
• omniscript-design-patterns — Use when the Remote Action is part of a larger OmniScript flow design
• omnistudio-performance — Use when Remote Action latency is causing user experience problems
• omnistudio-debugging — Use when Remote Action failures need step-level trace analysis