Flow External Services

Flow External Services

This skill activates when a practitioner needs to call an external REST API directly from Salesforce Flow — either by registering an OpenAPI spec via External Services or using Flow's built-in HTTP Callout action — without writing Apex. It covers registration, action configuration, Named Credential selection, input/output mapping, response parsing, fault handling, and governor limit constraints.

Before Starting

Gather this context before working on anything in this domain:

• Authentication first: Every outbound HTTP callout from Flow requires a Named Credential. There is no way to supply a raw URL with hard-coded credentials directly in a Flow HTTP Callout action or External Service action. Confirm a Named Credential (enhanced model recommended) exists or create one first — see the named-credentials-setup skill.
• Spec availability: External Services registration requires an OpenAPI 2.0 (Swagger) or OpenAPI 3.0 spec. If the external provider does not publish a machine-readable spec, the HTTP Callout action (Flow's built-in declarative callout, GA in Spring '24) is the correct alternative — it does not require a spec file.
• Flow type matters for callouts: Autolaunched flows and screen flows can make synchronous callouts. Record-triggered flows (before-save and after-save) cannot make callouts in the same transaction as the triggering DML. Attempting a callout in a record-triggered context without async handling causes a runtime error.
• Governor limits: Flows share the same governor limit pool as Apex in the same transaction. Each HTTP callout in a Flow consumes one of the 100 callouts-per-transaction limit (same as Apex callouts). Callout timeout is max 120 seconds. These constraints apply regardless of which mechanism (External Services or HTTP Callout action) is used.

Core Concepts

External Services: Spec-Driven Invocable Actions

External Services is a Salesforce platform feature under Setup > Integrations > External Services. It ingests an OpenAPI 2.0 or 3.0 spec, validates it against Salesforce's supported subset, and generates strongly-typed invocable actions — one per operation defined in the spec. These actions appear in Flow Builder's Action palette under the external service's label.

Registration requirements:

• The spec must be accessible via URL (Salesforce fetches it) or uploaded as a JSON/YAML file.
• Only a subset of OpenAPI features are supported. Polymorphic schemas (oneOf, anyOf), recursive references ($ref cycles), and certain header-defined parameters may fail schema validation or be silently ignored.
• A Named Credential is selected during registration. This determines the base URL and authentication. The spec's host or servers entry is overridden by the Named Credential URL at runtime.
• Changes to the spec require re-importing or updating the External Service registration. Generated action signatures change when the spec changes — existing Flow references to those actions will break if input/output parameter names change.

Versioning: External Services supports multiple spec versions under one registration. When you import an updated spec, Salesforce can maintain the previous version so existing Flow actions continue to work while you migrate.

Flow's Built-in HTTP Callout Action (Spring '24+ GA)

For situations where an OpenAPI spec is not available or the integration is simple enough not to warrant full External Services registration, Flow Builder (Spring '24 GA) offers a built-in HTTP Callout core action. You configure it declaratively:

• Named Credential: required — selects the authentication and base URL.
• Resource path: relative path appended to the Named Credential URL (e.g., /v1/customers).
• HTTP method: GET, POST, PUT, PATCH, DELETE.
• Headers and request body: set directly in the action configuration.
• Response handling: Salesforce provides the raw response body as a text variable. You must parse it using Flow's Transform element or Apex if the response is complex JSON.

The HTTP Callout action is simpler to configure than a full External Services registration but gives less type safety — response fields are not schema-validated and must be manually mapped.

Named Credentials: Authentication Gateway for Flow Callouts

All Flow callouts — whether via External Service actions or HTTP Callout actions — must reference a Named Credential. The Named Credential:

1. Supplies the base URL (so no hardcoded endpoints in Flow).
2. Handles authentication transparently (OAuth token injection, JWT signing, basic auth headers).
3. Controls which users can call out via External Credential principal and Permission Set assignment.

If the Named Credential's External Credential principal does not have the running user's Permission Set assigned, the callout fails at runtime with a generic authentication error. This is the most common first-run failure.

Error Handling: Fault Paths Are Mandatory

External Service actions and HTTP Callout actions are fallible elements. Any network failure, timeout, non-2xx HTTP response (for External Services), or malformed response can cause the action to route to its fault path.

In Flow Builder, every External Service action and HTTP Callout action exposes a fault connector. If this connector is not wired, a failure terminates the Flow interview and throws a generic platform error — which for screen flows shows a poor user experience, and for autolaunched flows causes the caller to receive an unhandled exception.

Minimum fault pattern:

1. Wire the fault connector to a dedicated fault path.
2. Capture $Flow.FaultMessage in a Text variable.
3. Route to a user-safe screen (screen flows) or log/notify (autolaunched flows).
4. Consider whether the failure should be retried, escalated, or silently swallowed based on business requirements.

Common Patterns

Pattern 1: Register an OpenAPI Spec and Use the Generated Action in Flow

When to use: The external API publishes a machine-readable OpenAPI spec and you want typed, auto-generated actions with named input/output fields.

How it works:

1. Confirm Named Credential exists for the target service (see named-credentials-setup).
2. Navigate to Setup > Integrations > External Services > Add an External Service.
3. Provide the spec URL or upload the file. Select the Named Credential. Click Save.
4. Salesforce validates the spec. Review any warnings — unsupported schema features are flagged here.
5. Open Flow Builder and add an Action element. Search for the external service name. Select the operation.
6. Map required input fields (scalar types, text, number, boolean). For body objects, use a Flow record variable typed to a matching Apex class if one was generated, or individual field assignments.
7. Store output fields in Flow variables of the correct type.
8. Wire the fault connector. Capture $Flow.FaultMessage.
9. Test using Flow's debug mode — mock response is not available, so a real endpoint (or a sandbox of the external service) is required.

Why not the HTTP Callout action: If the spec is available and the API has multiple operations, External Services gives compile-time field validation, auto-complete in Flow Builder, and easier maintenance when the API contract changes.

Pattern 2: Declarative HTTP Callout Without a Spec

When to use: No OpenAPI spec exists, the API has a single simple operation, or you want the fastest path to a working callout without spec maintenance overhead.

How it works:

1. Confirm Named Credential exists.
2. In Flow Builder, add a Core Action element. Select HTTP Callout from the action list.
3. Configure:
   • Named Credential: select from dropdown.
   • Invocable Action Name: a label used to identify this step.
   • Method: GET / POST / etc.
   • Path: resource path relative to Named Credential URL.
   • Headers: add Content-Type: application/json for POST/PUT requests.
   • Request Body: paste the JSON template or build it with a Text formula variable.
4. The action outputs: Response_Body (Text), Response_Status_Code (Number), Response_Headers (Text).
5. Parse Response_Body using a Transform element or a lightweight Apex method if the JSON is deeply nested.
6. Check Response_Status_Code in a Decision element — route non-2xx codes to an error path independently of the fault connector (the HTTP Callout action only faults on network/timeout errors, not 4xx/5xx responses).
7. Wire the fault connector for network-level failures.

Why not External Services: Speed and simplicity when spec is unavailable, the API surface is small, or the integration is short-lived.

Pattern 3: Parsing Complex JSON Responses

When to use: The external service returns a nested JSON object or an array, and you need to extract specific fields into Flow variables.

How it works:

External Service invocable actions return output as typed variables that match the spec schema — scalars are directly assignable to Flow variables, and objects/arrays are accessible as Apex-typed variables or Flow sObject-compatible records if they match a custom object structure.

For HTTP Callout action responses (raw text), use:

1. Flow Transform element (available in flows alongside HTTP Callout): maps JSON path expressions to Flow variables. Useful for flat or moderately nested responses.
2. Apex Invocable method: if the response is deeply nested, polymorphic, or requires conditional extraction, pass Response_Body to a lightweight @InvocableMethod that parses and returns structured output. Keep the Apex logic minimal — the goal is parsing, not business logic.
3. Collection variables: for array responses (e.g., a list of records), use Loop elements over a collection variable populated by the External Service action's list output.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the external API endpoint, authentication type, whether a spec file exists, and the Flow type (screen, autolaunched, record-triggered). If record-triggered, identify an async dispatch pattern before proceeding.
2. Set up Named Credential — verify or create a Named Credential and External Credential following the named-credentials-setup skill. Confirm Permission Set is assigned to the External Credential principal before testing.
3. Choose registration method — if an OpenAPI spec is available, register via External Services (Setup > Integrations > External Services). If not, proceed with the HTTP Callout core action in Flow Builder.
4. Build the Flow — add the External Service action or HTTP Callout action, map all required inputs, and wire output variables to correctly typed Flow variables. Add a Decision element to check HTTP status code for non-2xx handling (HTTP Callout only).
5. Wire fault connectors — connect every External Service or HTTP Callout element's fault path to a dedicated error handling branch. Capture $Flow.FaultMessage. For screen flows, display a friendly message. For autolaunched flows, log or notify.
6. Test end-to-end — run Flow debug with real credentials against the target environment. Confirm successful response, then deliberately test a failure scenario (wrong path, revoked token) to verify the fault path.
7. Review checklist — complete the checklist below before promoting to production.

Review Checklist

Run through these before marking a callout Flow complete:

• Named Credential exists and has Permission Set assigned to the External Credential principal
• Flow type is not record-triggered (or an async dispatch pattern is in place if it is)
• Every External Service action and HTTP Callout action has a fault connector wired
• $Flow.FaultMessage is captured in a Text variable on the fault path
• HTTP Callout action responses include a Decision element checking Response_Status_Code for 4xx/5xx
• No raw JSON or API error text is displayed directly to end users in screen flows
• Collection variables used for array responses are initialized before loop elements
• Callout volume is within the 100-callout-per-transaction limit when invoked in batch contexts
• External Service spec version is recorded; team knows update procedure if API contract changes
• Test covers both success and failure paths with real credentials

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Record-triggered flows cannot make synchronous callouts — Attempting a direct HTTP callout (via External Services action or HTTP Callout action) inside a record-triggered before-save or after-save flow throws a System.CalloutException: You have uncommitted work pending error at runtime. The fix is to dispatch work asynchronously via a Platform Event, a scheduled path, or a Queueable Apex job invoked from the flow.

2. HTTP Callout action does not fault on 4xx/5xx responses — Unlike External Services invocable actions (which route to the fault path on non-2xx responses depending on the spec configuration), the built-in HTTP Callout action only faults on network errors and timeouts. A 404 Not Found or 500 Internal Server Error response is returned with a status code variable and does not automatically trigger the fault connector. You must add an explicit Decision element checking Response_Status_Code >= 400 to route these to an error path.

3. External Services does not support all OpenAPI features — Salesforce validates specs against a supported subset. Schemas using oneOf, anyOf, allOf composition, recursive $ref chains, or enum arrays on request body parameters may fail to import or produce incomplete action signatures. Always test the spec import in a sandbox before committing an integration design that depends on full spec coverage.

4. Named Credential URL and path double-slash — If the Named Credential base URL ends with a trailing slash and the resource path in the HTTP Callout action or spec starts with a /, the concatenated URL contains //. Some APIs reject this. Always strip the trailing slash from the Named Credential URL and ensure paths start with /.

5. External Service action outputs are Apex-typed, not natively sObject — Output variables from External Service invocable actions are typed as Apex wrapper classes generated from the spec. They cannot be directly assigned to standard Flow record (sObject) variables unless the field names match exactly. Explicitly map each output field to the target sObject variable's field in a separate Assignment element.

Output Artifacts

Related Skills

• named-credentials-setup (integration) — prerequisite for any Flow callout; covers External Credential configuration, principal types, and permission set assignment
• callouts-and-http-integrations (apex) — Apex-based HTTP callouts when Flow External Services is insufficient (complex logic, bulk context, full error control)
• fault-handling (flow) — comprehensive fault connector design for all Flow element types, including external service actions
• auto-launched-flow-patterns (flow) — async dispatch patterns for triggering callout flows from record-triggered contexts