Integration Definitions
An Integration Definition in Salesforce is a reusable configuration record that describes how the org connects to a specific external system, what operations are available, and how data flows between the two.
Definition
An Integration Definition in Salesforce is a reusable configuration record that describes how the org connects to a specific external system, what operations are available, and how data flows between the two. It sits in Setup under Integrations and serves as the central registry for declarative connections used by Flow, Apex, Agentforce, and Data Cloud.
Rather than scattering connection details, authentication, and schema across multiple Apex classes or Flow elements, an Integration Definition bundles them into a single addressable artifact. Each definition holds a named connection, one or more operations (often imported from an OpenAPI specification), and optional mapping rules. Once defined, the same integration can be referenced by any number of automations without duplicating the underlying configuration.
What an Integration Definition actually contains
Connection and credentials
Every Integration Definition points to a Named Credential or, in some configurations, an External Credential plus Permission Set Group. The credential carries the endpoint base URL, authentication protocol (OAuth, JWT, API key, mTLS), and the rotation policy. By referencing a credential rather than embedding URL and tokens in the definition itself, the same integration can be promoted across sandbox, UAT, and production with no code change, simply by repointing the credential at a different environment. This separation is what lets architects ship integrations through change sets or DevOps Center without exposing secrets in version control.
Operations and schemas
The operations section is what makes an Integration Definition useful in declarative tools. When you import an OpenAPI 3.x specification (or a SOAP WSDL on older paths), Salesforce parses every endpoint into a callable operation with strongly typed request and response shapes. Each operation becomes available as a Flow action, an invocable Apex method, or an Agentforce tool. The schema also drives autocomplete inside the Flow Builder so admins can map fields without consulting the API docs. Updating the spec re-syncs the operations, and Salesforce flags breaking changes (removed fields, type changes) so consumers know before runtime.
Mapping rules and Data Cloud bridges
For data-oriented integrations, an Integration Definition can include mapping rules that translate between the external schema and Salesforce objects or Data Cloud Data Lake Objects. The mapping engine handles type coercion (string-to-datetime, numeric scale), field renames, and conditional logic. In Data Cloud scenarios, the same definition can feed a streaming ingestion pipeline, a batch sync, and an outbound activation, with the mapping defined once and reused by every consumer. This is the part of Integration Definitions that replaces what used to require a small ETL tool or a dedicated middleware layer for simple flows.
Usage contexts
When you create an Integration Definition, you declare which usage contexts it supports: Flow, Apex, Agentforce, Data Cloud, or any combination. The context affects what runtime treats the operations: a Flow context exposes operations as invocable actions with screen-friendly parameter labels, while an Agentforce context wraps each operation as a tool with natural language descriptions for the LLM to reason about. The same definition can serve all three with no duplication. Removing a context disables that surface without affecting the others, which is the right way to retire a usage path while leaving the rest of the integration intact.
Versioning and change management
Integration Definitions support versioning, where each saved version captures the schema, operations, and mappings as they stood at that moment. Consumers (Flows, Apex classes, Agentforce agents) reference a specific version, which means promoting a new version of the external API does not silently break running automations. Admins explicitly migrate each consumer to the new version. The Setup page lists every version with timestamps, the user who created it, and a diff summary against the prior version. This sounds heavy until you have a third-party vendor change a field type on you mid-quarter, at which point versioning is what keeps the org running.
Monitoring and limits
Every callout made through an Integration Definition is logged to the Integration Monitoring console with status, latency, and request/response payloads (subject to retention settings). The same callout counts against the org's callout limits: per-transaction synchronous limits for Apex, and the higher per-day limits for asynchronous integrations. Integration Definitions surface those metrics in a dashboard so architects can identify hot integrations before they hit limits. The page also exposes circuit breaker controls that automatically pause calls to an endpoint that has returned errors for a configurable number of consecutive attempts.
How this replaces the old toolkit
Before Integration Definitions consolidated the surface, the same job required External Services (for REST), Named Credentials (for auth), Custom Metadata Types (for config), and bespoke Apex (for mapping). Each piece was its own setup page with its own permissions and its own lifecycle. Integration Definitions roll the configuration of those pieces into one record while still using them under the hood. Existing External Services and Named Credentials are not deleted; they appear inside the new definition as referenced sub-components. The wrapper is what changed, not the underlying connectivity primitives.
When not to wrap an integration in a Definition
Integration Definitions are not the right home for every callout. One-shot Apex callouts in batch jobs, internal-only webhook receivers, and platform events do not benefit from the declarative wrapper. The overhead of authoring and versioning a definition is worth it when the integration is reused by multiple consumers, when business admins need to reference it from Flow, or when Agentforce needs to discover it as a tool. For a one-off ETL nightly that runs in Apex Scheduled, a raw callout with Named Credentials is simpler and easier to maintain. The rule is reuse and discoverability: high reuse plus broad audience justifies the definition wrapper, while narrow, code-only usage usually does not.
Set up a working Integration Definition
Creating an Integration Definition is a four-stage flow: connect, define operations, map data, and assign usage. Each stage builds on the prior one. Plan to pair with the team that owns the external API so you can validate the OpenAPI spec and the auth flow before you start wiring consumers.
- Create the Named Credential first
From Setup, navigate to Named Credentials and create a new entry pointing at the external system's base URL. Choose the authentication protocol (OAuth 2.0 Client Credentials, JWT, API key) that the vendor supports. Test the credential with a simple ping call from the Workbench REST Explorer before moving on. A working credential is the foundation. Skipping this step makes every downstream error look like a definition problem when the real issue is auth.
- Create the Integration Definition and import the spec
From Setup, open Integration Definitions and click New. Name the definition after the external system (Stripe, Twilio, your-internal-ESB), reference the Named Credential, and upload or paste the OpenAPI 3.x specification. Salesforce parses the spec and lists every operation. Review the list, deselect operations the org does not need, and save. Importing only what you need keeps the operation surface manageable and reduces the cognitive load for Flow Builders later.
- Define mappings for data-shaped integrations
Open each operation and map its input and output schemas to the corresponding Salesforce or Data Cloud fields. For simple field-to-field mappings, the auto-map button handles most of the work; for transformations (concatenating first and last name, converting cents to dollars), use the expression builder. Save the mapping inside the definition so every consumer inherits the same transformation logic. Document any non-obvious mapping (a vendor field named "amt" that means cents, not dollars) in the operation's description field.
- Assign usage contexts and test
On the Usage tab, enable the contexts where the definition will be referenced: Flow, Apex, Agentforce, or Data Cloud. Create a small test Flow that invokes one operation with hardcoded values, run it, and inspect the Integration Monitoring log to confirm the request and response landed correctly. Repeat for one operation per context. Once those pass, hand the definition off to the team building the consumer automations and stay available for the first end-to-end test in their sandbox.
- Importing an OpenAPI spec with hundreds of operations creates a definition that is hard to navigate. Trim the spec to the operations your org actually needs before importing.
- Schema drift on the vendor side does not auto-update consumers. The definition holds the version that was imported. Re-import to pick up changes, then migrate consumers explicitly.
- Named Credentials with per-user OAuth need every user who triggers the integration to authorize the connection at least once. Plan a rollout that includes this step.
- Operations that return very large payloads can blow past Apex heap limits when consumed synchronously. Use the async invocation pattern or paginate at the source for those operations.
- Integration Monitoring retention is shorter than Setup Audit Trail. Export critical callout logs to your SIEM or data warehouse if your audit policy requires longer retention than 30 days.
Trust & references
Cross-checked against the following references.
- Integration DefinitionsSalesforce Help
- Named CredentialsSalesforce Help
Straight from the source - Salesforce's reference material on Integration Definitions.
- Integration DefinitionsSalesforce Help
- External ServicesSalesforce Help
- Apex System NamespaceSalesforce Developer Docs
Hands-on resources to go deeper on Integration Definitions.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What skill set is typically needed to work with Integration Definitions?
Q2. What is a Governor Limit in the context of Integration Definitions?
Q3. Where would a developer typically work with Integration Definitions?
Discussion
Loading discussion…