Design and build Salesforce integrations for Spring '26 — the canonical patterns, inbound REST/Composite/Bulk API 2.0 and Apex REST, outbound callouts through Named and External Credentials, HTTP Callout actions in Flow, Platform Events, Change Data Capture, Pub/Sub API with managed subscriptions, Event Relay, Salesforce Connect, External Client Apps and OAuth flows, API limits, idempotency and retries.
When agents use itUse this whenever the user connects Salesforce to another system, writes an Apex callout or `@RestResource` class, upserts on an external Id, hits `UNABLE_TO_LOCK_ROW`, `REQUEST_LIMIT_EXCEEDED` or "You have uncommitted work pending", asks about Connected Apps vs External Client Apps, JWT vs client credentials, `/composite` vs `/composite/graph`, replay Ids, `EventUuid` or Bulk API jobs. Also apply it when a nightly data load or a duplicate-record problem turns out to be an integration contract problem.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill salesforce-integration -a github-copilot
# or with the org installer (adds .github/skills/salesforce-integration):
npx -y github:AGCO-Global/org-skills add skill salesforce-integration
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the salesforce-integration-skills plugin, which bundles all Salesforce / Integration skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install salesforce-integration-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill salesforce-integration -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill salesforce-integration -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill salesforce-integration -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill salesforce-integration -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the salesforce-integration folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Integrations fail at the edges: tokens that expire, limits nobody counted, retries that duplicate records, events nobody handled twice. Design the failure path first — idempotent writes, bounded retries, a dead letter and a correlation Id — and the happy path costs an afternoon.
1. Decide first
Question
Default
Change when
Which pattern?
Fire-and-forget with a Platform Event when Salesforce is the source; remote call-in with upsert on an external Id when the other system is
A user is waiting for the answer → request-reply callout; > 100 k records → batch sync with Bulk API 2.0; the data should not be copied → Salesforce Connect
Who initiates?
The other system pulls/pushes through the standard API
Salesforce must push → Platform Event + Pub/Sub subscriber, or Event Relay to AWS EventBridge with no subscriber to run
App identity for a new integration
External Client App — Connected App creation is disabled in Spring '26 orgs
Only an existing Connected App keeps working; plan its migration
Server-to-server auth
OAuth 2.0 Client Credentials on the ECA, bound to a dedicated integration user
High assurance or no client secret storage → JWT Bearer with a rotated certificate
Salesforce calling out
Named Credential + External Credential; endpoint as callout:Name/path
Where a Named Credential cannot carry it, the org's Credential__c — encrypted, FLS-restricted. Never a URL and a secret in code, custom settings or a static resource
Multi-object write in one shot
/composite with allOrNone=true (25 subrequests)
Deep parent-child graphs or > 25 operations → /composite/graph (500 subrequests, each graph transactional); ≤ 200 records of one type → /composite/sobjects
Callout from automation
Queueable Apex with Database.AllowsCallouts
Admin-owned, simple request-reply → HTTP Callout action in Flow; a documented OpenAPI provider → External Services
More than ~3 systems, transformation, orchestration
Middleware (MuleSoft/iPaaS) owns it
Salesforce is never the integration hub
2. Inbound — external systems writing Salesforce
Upsert on an external Id is the single most important decision: PATCH /services/data/v66.0/sobjects/Order__c/ERP_Id__c/A-1001. It makes retries harmless and removes duplicate hunting.
Transactionality: /composite (allOrNone=true), /composite/graph (per graph) and /composite/tree roll back as a unit. /composite/batch does not — each subrequest is its own transaction and haltOnError only stops the ones after it. Never promise atomicity with /composite/batch.
Bulk API 2.0 for ingest and for query jobs above ~100 k rows; it chunks and retries server-side, and its limits are separate from the REST allocation.
Apex REST (@RestResource) only when the standard API cannot express the contract: version the path (/services/apexrest/v1/orders), accept arrays, enforce USER_MODE, return a stable error body and an honest status code. Skeleton in references/inbound-apis.md.
Budget the API allocation. The 24-hour limit is per org, so one client can starve the rest. Read Sforce-Limit-Info on every response, alert at 70 %, and give each client its own integration user so usage is attributable.
Loads fire all automation. The org's switches are User.Ignore_Validation_Rules__c on the load user for validation rules and flows, plus the per-handler bypass each trigger wires through TriggerTemplateV2. Use them only for controlled migrations.
3. Outbound — Salesforce calling other systems
public with sharing class ErpClient {
public class ErpException extends Exception {}
public static ErpOrder fetchOrder(String erpId) {
HttpRequest req = new HttpRequest();
req.setEndpoint('callout:ERP_Api/orders/' + EncodingUtil.urlEncode(erpId, 'UTF-8'));
req.setMethod('GET');
req.setHeader('Accept', 'application/json');
req.setTimeout(20000); // ms; 120000 is the platform maximum
HttpResponse res;
try {
res = new Http().send(req);
} catch (CalloutException e) {
throw new ErpException('ERP unreachable: ' + e.getMessage(), e);
}
if (res.getStatusCode() == 200) {
return (ErpOrder) JSON.deserialize(res.getBody(), ErpOrder.class);
}
if (res.getStatusCode() == 404) {
return null;
}
throw new ErpException('ERP ' + res.getStatusCode() + ': ' + res.getStatus());
}
public class ErpOrder {
public String id;
public String status;
public Decimal total;
}
}
Never call out synchronously from a trigger, and never after DML in the same transaction ("You have uncommitted work pending") — enqueue a Queueable or publish an event.
Retry 5xx, timeouts and 429 (honour Retry-After) with backoff from a Queueable Finalizer; never retry other 4xx. Cap the attempts, then dead-letter the payload to a custom object for replay.
Send an idempotency key the receiver can dedupe on (record Id + change stamp) so your retries do not duplicate their records.
Limits: 100 callouts per transaction, 120 s cumulative timeout, response 6 MB synchronous / 12 MB asynchronous. Larger payloads paginate or let the other system pull via Bulk API.
4. Event-driven
Publish After Commit is a property of the platform event definition, not of the caller. EventBus.publish and a flow's Create Records element both honour whatever the definition says — do not tell people to "publish after commit in Flow".
Subscribers get at-least-once delivery, so every consumer dedupes on EventUuid or your own correlation Id and is safe to run twice. Ordering holds only within a partition.
External subscribers use the Pub/Sub API (gRPC). Prefer Managed Event Subscriptions, where the platform tracks the replay position server-side, over persisting replay Ids in your own client; the retention window is 72 hours either way.
Event Relay forwards platform events and CDC to AWS EventBridge with no subscriber process to operate — the cheapest fire-and-forget when the target is AWS.
Change Data Capture publishes record changes with no code; enable per object and watch the entity allocation.
In Apex event triggers, EventBus.RetryableException retries transient failures; anything else is logged and dropped. Details and the subscriber skeleton in references/events-and-streaming.md.
5. Auth and app identity
New integrations use an External Client App: Connected App creation is disabled in Spring '26 orgs (Support exception only) and existing Connected Apps are on a migration path. Pick Client Credentials for plain server-to-server, JWT Bearer when the client must not hold a secret, Authorization Code + PKCE when a real user is acting. One integration user per system, API-only, permission sets not profiles, rotation dates written down. Flows, setup steps and the External Credential principal model are in references/auth-and-named-credentials.md.
6. Deliverable format
## Pattern — the canonical pattern per flow of data and why
## Contracts — endpoints/events, payload schema, versioning, external Ids, system of record per field
## Auth — ECA, OAuth flow, integration user, permission set, rotation
## Volume & limits — records/day, peak, API budget, bulk vs real-time
## Failure handling — retries, idempotency key, dead letter, circuit breaker, alerts
## Observability — correlation Id, log object, dashboards
## Test plan — HttpCalloutMock cases, event delivery, contract tests, load test
## Rollout — sandbox sequence, bypass flags, backfill, rollback
Checklist
Every inbound write is an upsert on an external Id, or explains why not
Atomicity claims match the resource used (/composite/batch is not transactional)
New app identity is an External Client App; existing Connected Apps have a migration date
Secrets in Named/External Credentials or Credential__c (encrypted, FLS-restricted); one integration user per system
No callout from a trigger; no callout after DML; timeouts set explicitly
Retry policy bounded, with a dead letter and a circuit breaker
Event consumers dedupe on EventUuid; publish behaviour set on the event definition
API budget per client, Sforce-Limit-Info monitored, alert at 70 %
Correlation Id written to a log object on both sides
Callouts mocked with HttpCalloutMock; events asserted with Test.getEventBus().deliver()
Anti-patterns
Synchronous callout from a trigger → Queueable or Platform Event.
/composite/batch used for "all or nothing" → /composite with allOrNone=true, or /composite/graph.
Creating a Connected App for a new integration → External Client App.
Secrets in Apex, Custom Settings or a static resource → External Credential, or Credential__c where a Named Credential cannot carry the callout.
Client-side replay Id bookkeeping written from scratch → Managed Event Subscriptions.
"Publish After Commit" set in the flow → it is on the event definition.
Polling Salesforce every minute → CDC or Platform Events.
Retrying 4xx forever, no dead letter → bounded retries, dead-letter object, alert.
One shared integration user for every system → one per system, attributable and revocable.
Salesforce transforming payloads for five other systems → middleware owns transformation.
Go deeper
references/inbound-apis.md — composite family comparison, Apex REST skeleton, Bulk API 2.0 jobs, limit headers and error bodies.
references/events-and-streaming.md — event contract design, Pub/Sub API and managed subscriptions, Event Relay, CDC, Apex subscriber skeleton, dead-letter pattern.
Sibling skills: apex-development for Queueables and Finalizers, apex-testing for callout and event tests, salesforce-automation for HTTP Callout actions in Flow, salesforce-data-model for external Ids, salesforce-security for hardening, salesforce-code-review for pull requests, salesforce-org-conventions for the org's naming and mandated patterns.
---
name: salesforce-integration
description: >
Design and build Salesforce integrations for Spring '26 — the canonical patterns, inbound REST/Composite/Bulk API 2.0 and Apex REST, outbound callouts through Named and External Credentials, HTTP Callout actions in Flow, Platform Events, Change Data Capture, Pub/Sub API with managed subscriptions, Event Relay, Salesforce Connect, External Client Apps and OAuth flows, API limits, idempotency and retries. Use this whenever the user connects Salesforce to another system, writes an Apex callout or `@RestResource` class, upserts on an external Id, hits `UNABLE_TO_LOCK_ROW`, `REQUEST_LIMIT_EXCEEDED` or "You have uncommitted work pending", asks about Connected Apps vs External Client Apps, JWT vs client credentials, `/composite` vs `/composite/graph`, replay Ids, `EventUuid` or Bulk API jobs. Also apply it when a nightly data load or a duplicate-record problem turns out to be an integration contract problem.
metadata:
technology: Salesforce
type: architecture
---
# Salesforce Integration
> **Targets:** Salesforce Spring '26 (API 66.0) · **Verified:** 2026-09 against https://developer.salesforce.com (REST API, Apex, Pub/Sub API guides) and https://help.salesforce.com (External Client Apps, Named Credentials)
Integrations fail at the edges: tokens that expire, limits nobody counted, retries that duplicate records, events nobody handled twice. Design the failure path first — idempotent writes, bounded retries, a dead letter and a correlation Id — and the happy path costs an afternoon.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Which pattern? | **Fire-and-forget** with a Platform Event when Salesforce is the source; **remote call-in** with upsert on an external Id when the other system is | A user is waiting for the answer → request-reply callout; > 100 k records → batch sync with Bulk API 2.0; the data should not be copied → Salesforce Connect |
| Who initiates? | The **other system pulls/pushes** through the standard API | Salesforce must push → Platform Event + Pub/Sub subscriber, or **Event Relay** to AWS EventBridge with no subscriber to run |
| App identity for a new integration | **External Client App** — Connected App creation is disabled in Spring '26 orgs | Only an existing Connected App keeps working; plan its migration |
| Server-to-server auth | **OAuth 2.0 Client Credentials** on the ECA, bound to a dedicated integration user | High assurance or no client secret storage → **JWT Bearer** with a rotated certificate |
| Salesforce calling out | **Named Credential + External Credential**; endpoint as `callout:Name/path` | Where a Named Credential cannot carry it, the org's `Credential__c` — encrypted, FLS-restricted. Never a URL and a secret in code, custom settings or a static resource |
| Multi-object write in one shot | `/composite` with `allOrNone=true` (25 subrequests) | Deep parent-child graphs or > 25 operations → `/composite/graph` (500 subrequests, each graph transactional); ≤ 200 records of one type → `/composite/sobjects` |
| Callout from automation | Queueable Apex with `Database.AllowsCallouts` | Admin-owned, simple request-reply → **HTTP Callout action** in Flow; a documented OpenAPI provider → **External Services** |
| More than ~3 systems, transformation, orchestration | Middleware (MuleSoft/iPaaS) owns it | Salesforce is never the integration hub |
## 2. Inbound — external systems writing Salesforce
- **Upsert on an external Id** is the single most important decision: `PATCH /services/data/v66.0/sobjects/Order__c/ERP_Id__c/A-1001`. It makes retries harmless and removes duplicate hunting.
- Transactionality: `/composite` (`allOrNone=true`), `/composite/graph` (per graph) and `/composite/tree` roll back as a unit. **`/composite/batch` does not** — each subrequest is its own transaction and `haltOnError` only stops the ones after it. Never promise atomicity with `/composite/batch`.
- **Bulk API 2.0** for ingest and for query jobs above ~100 k rows; it chunks and retries server-side, and its limits are separate from the REST allocation.
- **Apex REST** (`@RestResource`) only when the standard API cannot express the contract: version the path (`/services/apexrest/v1/orders`), accept arrays, enforce `USER_MODE`, return a stable error body and an honest status code. Skeleton in `references/inbound-apis.md`.
- **Budget the API allocation.** The 24-hour limit is per org, so one client can starve the rest. Read `Sforce-Limit-Info` on every response, alert at 70 %, and give each client its own integration user so usage is attributable.
- Loads fire all automation. The org's switches are `User.Ignore_Validation_Rules__c` on the load user for validation rules and flows, plus the per-handler bypass each trigger wires through `TriggerTemplateV2`. Use them only for controlled migrations.
## 3. Outbound — Salesforce calling other systems
```apex
public with sharing class ErpClient {
public class ErpException extends Exception {}
public static ErpOrder fetchOrder(String erpId) {
HttpRequest req = new HttpRequest();
req.setEndpoint('callout:ERP_Api/orders/' + EncodingUtil.urlEncode(erpId, 'UTF-8'));
req.setMethod('GET');
req.setHeader('Accept', 'application/json');
req.setTimeout(20000); // ms; 120000 is the platform maximum
HttpResponse res;
try {
res = new Http().send(req);
} catch (CalloutException e) {
throw new ErpException('ERP unreachable: ' + e.getMessage(), e);
}
if (res.getStatusCode() == 200) {
return (ErpOrder) JSON.deserialize(res.getBody(), ErpOrder.class);
}
if (res.getStatusCode() == 404) {
return null;
}
throw new ErpException('ERP ' + res.getStatusCode() + ': ' + res.getStatus());
}
public class ErpOrder {
public String id;
public String status;
public Decimal total;
}
}
```
- Never call out synchronously from a trigger, and never after DML in the same transaction ("You have uncommitted work pending") — enqueue a Queueable or publish an event.
- Retry 5xx, timeouts and 429 (honour `Retry-After`) with backoff from a Queueable **Finalizer**; never retry other 4xx. Cap the attempts, then dead-letter the payload to a custom object for replay.
- Send an idempotency key the receiver can dedupe on (record Id + change stamp) so your retries do not duplicate their records.
- Limits: 100 callouts per transaction, 120 s cumulative timeout, response **6 MB synchronous / 12 MB asynchronous**. Larger payloads paginate or let the other system pull via Bulk API.
## 4. Event-driven
- **Publish After Commit is a property of the platform event definition**, not of the caller. `EventBus.publish` and a flow's Create Records element both honour whatever the definition says — do not tell people to "publish after commit in Flow".
- Subscribers get **at-least-once** delivery, so every consumer dedupes on `EventUuid` or your own correlation Id and is safe to run twice. Ordering holds only within a partition.
- External subscribers use the **Pub/Sub API** (gRPC). Prefer **Managed Event Subscriptions**, where the platform tracks the replay position server-side, over persisting replay Ids in your own client; the retention window is 72 hours either way.
- **Event Relay** forwards platform events and CDC to AWS EventBridge with no subscriber process to operate — the cheapest fire-and-forget when the target is AWS.
- **Change Data Capture** publishes record changes with no code; enable per object and watch the entity allocation.
- In Apex event triggers, `EventBus.RetryableException` retries transient failures; anything else is logged and dropped. Details and the subscriber skeleton in `references/events-and-streaming.md`.
## 5. Auth and app identity
New integrations use an **External Client App**: Connected App creation is disabled in Spring '26 orgs (Support exception only) and existing Connected Apps are on a migration path. Pick Client Credentials for plain server-to-server, JWT Bearer when the client must not hold a secret, Authorization Code + PKCE when a real user is acting. One integration user per system, API-only, permission sets not profiles, rotation dates written down. Flows, setup steps and the External Credential principal model are in `references/auth-and-named-credentials.md`.
## 6. Deliverable format
```
## Pattern — the canonical pattern per flow of data and why
## Contracts — endpoints/events, payload schema, versioning, external Ids, system of record per field
## Auth — ECA, OAuth flow, integration user, permission set, rotation
## Volume & limits — records/day, peak, API budget, bulk vs real-time
## Failure handling — retries, idempotency key, dead letter, circuit breaker, alerts
## Observability — correlation Id, log object, dashboards
## Test plan — HttpCalloutMock cases, event delivery, contract tests, load test
## Rollout — sandbox sequence, bypass flags, backfill, rollback
```
## Checklist
- [ ] Every inbound write is an upsert on an external Id, or explains why not
- [ ] Atomicity claims match the resource used (`/composite/batch` is not transactional)
- [ ] New app identity is an External Client App; existing Connected Apps have a migration date
- [ ] Secrets in Named/External Credentials or `Credential__c` (encrypted, FLS-restricted); one integration user per system
- [ ] No callout from a trigger; no callout after DML; timeouts set explicitly
- [ ] Retry policy bounded, with a dead letter and a circuit breaker
- [ ] Event consumers dedupe on `EventUuid`; publish behaviour set on the event definition
- [ ] API budget per client, `Sforce-Limit-Info` monitored, alert at 70 %
- [ ] Correlation Id written to a log object on both sides
- [ ] Callouts mocked with `HttpCalloutMock`; events asserted with `Test.getEventBus().deliver()`
## Anti-patterns
- **Synchronous callout from a trigger** → Queueable or Platform Event.
- **`/composite/batch` used for "all or nothing"** → `/composite` with `allOrNone=true`, or `/composite/graph`.
- **Creating a Connected App for a new integration** → External Client App.
- **Secrets in Apex, Custom Settings or a static resource** → External Credential, or `Credential__c` where a Named Credential cannot carry the callout.
- **Client-side replay Id bookkeeping written from scratch** → Managed Event Subscriptions.
- **"Publish After Commit" set in the flow** → it is on the event definition.
- **Polling Salesforce every minute** → CDC or Platform Events.
- **Retrying 4xx forever, no dead letter** → bounded retries, dead-letter object, alert.
- **One shared integration user for every system** → one per system, attributable and revocable.
- **Salesforce transforming payloads for five other systems** → middleware owns transformation.
## Go deeper
- `references/inbound-apis.md` — composite family comparison, Apex REST skeleton, Bulk API 2.0 jobs, limit headers and error bodies.
- `references/auth-and-named-credentials.md` — External Client Apps, OAuth flow chooser, External Credential principals, integration-user setup, rotation.
- `references/events-and-streaming.md` — event contract design, Pub/Sub API and managed subscriptions, Event Relay, CDC, Apex subscriber skeleton, dead-letter pattern.
- Sibling skills: `apex-development` for Queueables and Finalizers, `apex-testing` for callout and event tests, `salesforce-automation` for HTTP Callout actions in Flow, `salesforce-data-model` for external Ids, `salesforce-security` for hardening, `salesforce-code-review` for pull requests, `salesforce-org-conventions` for the org's naming and mandated patterns.