Mulesoft Salesforce Connector

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:

• Salesforce API entitlements and limits: The connector wraps four Salesforce APIs (SOAP, REST, Bulk, Streaming). Each has distinct governor limits. Confirm the org's API call allocation (visible in Setup > Company Information) and whether Bulk API is enabled.
• Connected App configuration: The connector authenticates via a Connected App. For server-to-server flows (no interactive user), OAuth 2.0 JWT Bearer is recommended. Verify that a Connected App with the correct certificate, scopes, and pre-authorized profile exists before building the flow.
• Mule runtime version: Mule 4 replaced the built-in watermark element with Object Store-backed watermark. Flows migrated from Mule 3 that still reference <watermark> will fail at deployment. Confirm the target runtime is Mule 4.x.

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:

• SOAP API — Default for single-record CRUD. Best for real-time request-reply with < 200 records. Counts against the org's daily API call limit (one call per operation invocation).
• REST API — Used for Composite and SObject Tree operations. Enables creating up to 200 records in a single API call via Composite, reducing limit consumption.
• Bulk API 2.0 — Required for high-volume loads (> 10,000 records). Operates asynchronously via jobs. Does not count against the standard API call limit but has its own daily rolling limit (150,000,000 records or 15,000 batches, whichever is hit first).
• Streaming API / Pub/Sub API — Used for Subscribe Topic and Replay Topic operations. Consumes 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

Recommended Workflow

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:

• Connected App uses JWT Bearer (not username-password) for server-to-server flows
• Connector global configuration specifies the correct API mode for the volume and pattern
• Watermark is stored in Object Store and only advanced after successful processing
• Batch scope has maxFailedRecords set to a non-zero threshold with dead-letter logging
• API call budget verified: daily limit headroom confirmed for SOAP/REST; Bulk API limits checked for bulk flows
• Integration user has a dedicated profile with minimum required object/field permissions
• Flow tested with partial-failure scenarios (validation rule rejects, duplicate rules) to confirm error isolation

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

Related Skills

• oauth-flows-and-connected-apps — Use when configuring the Salesforce Connected App that the connector authenticates against
• retry-and-backoff-patterns — Use when the Mule flow needs retry logic for transient Salesforce API errors (503, 429)
• rest-api-patterns — Use when comparing native Apex REST callout alternatives to the MuleSoft connector approach
• change-data-capture-integration — Use when evaluating CDC as an alternative to polling-based sync via the connector