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.