Connection (for Salesforce to Salesforce)
A Connection (for Salesforce to Salesforce) is the named, configured link between two separate Salesforce orgs that lets them share specific records with each other.
Definition
A Connection (for Salesforce to Salesforce) is the named, configured link between two separate Salesforce orgs that lets them share specific records with each other. Each org administers its own side of the connection, controlling which objects and fields it publishes to the partner and which it subscribes to from the partner. The shared records remain in each org own database, but updates propagate between orgs through the connection.
Salesforce to Salesforce (often abbreviated S2S) was designed for partner-collaboration scenarios: a manufacturer sharing leads with a channel partner, a regional org sharing service cases with a global HQ org, or two divisions of the same company that ended up on separate Salesforce orgs after an acquisition. The Connection record is the unit of administration; each org typically has a small number of Connections to specific partner orgs rather than a broad share to everyone.
How a Salesforce-to-Salesforce Connection works
Setting up a Connection
A Connection starts with one org sending an invitation to the other, identified by the partner org admin email. The receiving org admin accepts the invitation, the link is established, and both sides now appear in each other Setup, Salesforce to Salesforce, Connections list. Each side independently configures what to publish and what to subscribe to. Either side can revoke the connection at any time.
Publish, subscribe, and the per-object configuration
Each Connection has two sides: what the local org publishes outbound (records the partner can see) and what it subscribes to inbound (records from the partner the local org can accept). Configuration is per object: Leads, Opportunities, Cases, Contacts, custom objects. Within each object, the admin picks specific fields to publish or subscribe to. Field-level mapping is explicit, so the partner does not see fields you have not published.
How records flow between orgs
Sharing a specific record is a deliberate action: from a record, click Share, pick the Connection, and forward the record. The record then appears in the partner org with an external connection icon and a related list showing its origin. Updates to a field on either side propagate to the other side based on the publish/subscribe configuration. Either side can stop sharing a record at any time, which removes it from the partner org.
Sync timing and the eventual-consistency model
S2S sync is near-real-time but not instant. Field updates typically propagate in seconds to minutes. Bulk loads can take longer. The sync is best-effort and eventually consistent, not transactional. If the partner org is down or the connection is paused, updates queue until the connection recovers. Plan UI patterns around eventual consistency rather than instant reflection.
Sharing model implications
S2S respects the local org sharing model on outbound: a record the local user cannot see cannot be shared through S2S. On inbound, the receiving org chooses an owner for incoming records (a specific user or queue). Sharing rules on the receiving side then govern who else in that org can see the record. Field-Level Security is per side: a field published from the source does not bypass FLS in the target.
When to use S2S vs MuleSoft vs platform events
S2S is the Salesforce-native answer to Salesforce-to-Salesforce sharing, but it is not always the best answer. MuleSoft Composer or MuleSoft Anypoint covers higher-volume integrations and richer transformation. Platform Events handle one-way push patterns. Salesforce Connect (a different product) handles read-only surface-as-external-object scenarios. S2S is the right pick when both sides are Salesforce orgs, the volume is moderate, and the integration is a long-term partnership rather than a one-shot data move.
Why this is a legacy feature in practice
S2S has not received major investment since around 2017. The feature still works, but most new Salesforce-to-Salesforce integrations use MuleSoft, custom REST APIs, or platform events because those tools offer better monitoring, transformation, and error handling. S2S Connections are most common in orgs that set up partner-share workflows years ago and have kept them running.
How to set up and configure a Salesforce-to-Salesforce Connection
Setting up a Connection requires both orgs to participate. The local admin enables S2S, sends an invitation, and once the partner accepts, both sides configure their publish/subscribe lists.
- Enable Salesforce to Salesforce in the local org
Setup, Salesforce to Salesforce Settings, Enable. This is one-way; once enabled, it cannot be disabled cleanly. Plan accordingly in production.
- Designate a Connection User
A special internal user account owns all inbound records from the partner org. Create or designate this user, typically named Connection User, and document who can access the inbound queue.
- Send the invitation
Setup, Connections, New. Enter the partner admin email and the partner Account record (from your Accounts in the local org that represents the partner company). Salesforce sends an email invitation; the partner admin accepts inside their own org.
- Configure published objects and fields
From the Connection detail page, click Edit on the Publish list. Add objects (Lead, Opportunity, custom objects). For each object, pick the fields to publish. Do not publish more than the partner needs; minimal publication is the safer default.
- Configure subscribed objects and fields
Click Edit on the Subscribe list. Add the same objects from the partner side (matching the partner published objects). Map each inbound field to a local field; fields with no mapping are dropped.
- Forward records to start sharing
Open a record (a Lead, for example) and click Share, Connection. Pick the partner Connection. The record now flows to the partner org. Repeat per record or use Flow or Apex to automate.
- Monitor sync health
From Setup, Connections, the Health tab shows pending and failed records, sync lag, and connection status. Build a custom alert (Flow on the External Activity object) if you need real-time monitoring.
- Salesforce to Salesforce cannot be disabled once enabled in production. Test in a sandbox first.
- Field types must match between orgs. A Text(255) on one side cannot map to a Long Text Area on the other; the field is dropped during sync.
- Sync is best-effort and eventually consistent. Do not build dependencies that assume real-time propagation.
- Custom objects must exist on both sides with matching API names. Field API names also matter; renaming a field after the connection is configured breaks the mapping.
- Records shared through S2S can show old data if the connection is paused or the partner org is in a refresh window. Field history on the local copy will show the gap.
Trust & references
Cross-checked against the following references.
- Salesforce to Salesforce OverviewSalesforce Help
- Set Up Salesforce to SalesforceSalesforce Help
Straight from the source - Salesforce's reference material on Connection (for Salesforce to Salesforce).
- Manage ConnectionsSalesforce Help
- Publish Records to a ConnectionSalesforce Help
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 does a Salesforce to Salesforce Connection do?
Q2. When is S2S a good fit?
Q3. When might you use middleware instead of S2S?
Discussion
Loading discussion…