SfSkills Domains Docs GitHub

Home / integration / mulesoft-salesforce-connector

mulesoft-salesforce-connector

Designing and configuring MuleSoft Anypoint Salesforce Connector flows: API selection (SOAP/REST/Bulk/Streaming), OAuth 2.0 JWT Bearer auth, watermark-based incremental sync with Object Store, batch processing with record-level error isolation. NOT for native Salesforce-to-Salesforce integration without MuleSoft — use integration/platform-events-integration or integration/change-data-capture-integration. NOT for generic REST callouts from Apex — use integration/rest-api-patterns.

Open the skill folder on GitHub

MuleSoft Salesforce Connector

This skill activates when a practitioner is building, configuring, or troubleshooting MuleSoft Anypoint Platform flows that integrate with Salesforce. It covers connector API selection, authentication setup, watermark-based incremental synchronization, batch scope error handling, and streaming/replay topic subscriptions. It does not cover native Salesforce platform integration mechanisms (Platform Events consumed in Apex, Change Data Capture triggers) or generic Apex HTTP callout patterns.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Connector API Selection — Four APIs, One Connector

The Salesforce Connector (version 11.x) exposes operations backed by four distinct Salesforce APIs. Choosing the wrong one causes limit exhaustion, timeouts, or data loss:

APIWhen to useLimit posture
SOAP APIDefault for single-record CRUD; real-time request-reply with < 200 records.One daily API call per operation invocation.
REST APIComposite and SObject Tree operations; up to 200 records in a single API call via Composite.Reduces daily-API-call consumption vs. SOAP.
Bulk API 2.0High-volume loads (> 10,000 records); asynchronous via jobs.Does not count against the standard API call limit; has its own daily rolling limit (150M records or 15K batches, whichever is hit first).
Streaming API / Pub/Sub APISubscribe Topic and Replay Topic operations; CometD long-polling or gRPC streams.Requires Push Topic or Platform Event configuration in Salesforce.

Watermark-Based Incremental Sync (Mule 4 + Object Store)

In Mule 4, the legacy <watermark> element is removed. Incremental sync is implemented manually using Mule's Object Store to persist the last-processed timestamp or record Id between flow executions. The pattern is:

  1. On flow start, read the stored watermark value from Object Store (default to epoch if absent).
  2. Query Salesforce with a WHERE LastModifiedDate > :watermark filter.
  3. Process results.
  4. After successful processing, update the Object Store with the maximum LastModifiedDate from the result set.

If the flow fails mid-batch, the watermark is not advanced, so the next execution re-processes the failed window. This provides at-least-once delivery semantics.

Batch Scope and Record-Level Error Isolation

MuleSoft's <batch:job> scope processes records individually within each batch step. A failure on one record does not abort the entire batch. Instead, the failing record is routed to the <batch:on-complete> phase with a FAILED status while successful records continue. This is critical for Salesforce integrations where partial-success is common (e.g., validation rule failures on specific records). Always configure maxFailedRecords to a sensible threshold rather than the default of 0 (which aborts the batch on the first failure).

Common Patterns

Pattern 1: JWT Bearer Server-to-Server Authentication

When to use: Automated scheduled syncs, daemon integrations, or any flow without an interactive Salesforce user session.

How it works:

  1. Create a Connected App in Salesforce with "Enable OAuth Settings" and "Use digital signatures" checked. Upload the X.509 certificate.
  2. Pre-authorize the Connected App for the integration user's profile (Setup > Connected Apps > Manage > Edit Policies > Permitted Users = "Admin approved users are pre-authorized").
  3. In the Mule Salesforce Connector configuration, select "OAuth 2.0 JWT Bearer" and supply the consumer key, the integration user's username, the keystore path, and keystore password.
  4. The connector exchanges a signed JWT assertion for an access token with no browser redirect. Token refresh is handled automatically by the connector.

Why not the alternative: Username-password auth embeds credentials in the Mule app properties and breaks when the user's password changes or MFA is enforced. OAuth 2.0 Web Server flow requires an interactive browser session, which is not possible in headless runtime environments.

Pattern 2: High-Volume Sync via Bulk API with Watermark

When to use: Nightly or scheduled syncs moving 10,000+ records between Salesforce and an external system.

How it works:

  1. Read watermark from Object Store.
  2. Use the connector's query operation with fetchSize set and Bulk API enabled in the connector config (useBulkApi="true").
  3. Pipe results through a <batch:job> with blockSize tuned to 200 (matching Salesforce DML batch size).
  4. In the <batch:on-complete> phase, update the Object Store watermark only if the batch success rate exceeds the configured threshold.

Why not the alternative: Using SOAP API for high-volume loads burns through the org's daily API limit and may hit the 2,000-record query-more loop, causing timeouts in flows with transformation logic.

Decision Guidance

SituationRecommended ApproachReason
< 200 records, real-time, request-replySOAP or REST API (Composite)Low latency, single API call, synchronous response
200 - 10,000 records, near-real-timeREST API Composite with chunkingReduces API calls by 200x vs single-record SOAP
> 10,000 records, scheduled batchBulk API 2.0Async processing, does not count against standard API limit
Real-time event-driven (CDC, Platform Events)Streaming API / Pub/Sub subscriberPush-based, no polling, durable replay with replay ID
Server-to-server auth, no interactive userOAuth 2.0 JWT BearerNo password rotation risk, MFA-compatible, certificate-based
Interactive user context requiredOAuth 2.0 Authorization Code (Web Server)Maintains user identity for row-level sharing enforcement

Step-by-step instructions for an AI agent or practitioner configuring a MuleSoft Salesforce integration:

  1. Identify the integration pattern. Determine whether the use case is request-reply, batch/bulk, event-driven, or bidirectional sync. This drives API and connector operation selection.
  2. Configure authentication. For server-to-server: set up a Connected App with JWT Bearer, upload the certificate, pre-authorize the integration user's profile. For user-context: configure OAuth 2.0 Authorization Code with callback URL.
  3. Select the correct connector API. Map the pattern from Step 1 to the API decision table above. Configure the connector's global element with the chosen API mode (e.g., useBulkApi, useRestApi).
  4. Implement watermark if incremental. For any polling-based sync, use Object Store to persist watermark. Query with LastModifiedDate > :watermark. Advance watermark only after successful processing.
  5. Configure batch error handling. Wrap Salesforce write operations in a <batch:job> with maxFailedRecords set to an acceptable threshold. Log failed records to a dead-letter queue or error topic for retry.
  6. Test with realistic volume. Run the flow against a full sandbox with production-scale data. Verify API limit consumption, batch throughput, and watermark advancement after partial failures.
  7. Validate security and monitoring. Confirm the Connected App has minimum required scopes, IP restrictions are applied if feasible, and Anypoint Monitoring dashboards track error rates and API consumption.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Bulk API daily rolling limit is separate from standard API limit — Bulk API 2.0 has its own 24-hour rolling window limit (150M records processed or 15,000 batches). Teams that assume Bulk API is "free" and run frequent intraday bulk syncs hit this limit and get EXCEEDED_ID_LIMIT errors with no warning until the job fails.
  2. Query-more pagination and session timeout — SOAP API queries returning > 2,000 records use query-more with a server-side cursor. If the Mule flow takes too long processing between pages (> 15 minutes), the cursor expires and the query fails. Bulk API avoids this entirely by writing results to a retrievable file.
  3. JWT Bearer token caching and clock skew — The connector caches the access token. If the Mule runtime's clock drifts > 5 minutes from Salesforce's servers, JWT assertion validation fails silently with an "invalid_grant" error that does not indicate clock skew. Use NTP sync on all Mule runtime hosts.

Output Artifacts

ArtifactDescription
Mule 4 flow XML snippetConnector configuration with selected API mode, auth, and watermark logic
Connected App setup checklistStep-by-step JWT Bearer Connected App configuration for the Salesforce org
Batch error handling design<batch:job> configuration with maxFailedRecords, dead-letter logging, and retry strategy
Object Store watermark designKey naming, default values, and advancement-only-on-success guard logic

Dependencies

Package files