Home / architect / multi-org-strategy
multi-org-strategy
Use when deciding whether to use multiple Salesforce production orgs, designing a hub-and-spoke integration topology, reviewing an existing multi-org architecture for risk, or troubleshooting cross-org integration failures.
Open the skill folder on GitHub
Use this skill when evaluating whether to use multiple Salesforce production orgs, designing how those orgs will exchange data, reviewing an existing multi-org architecture for hidden risks, or troubleshooting cross-org integration failures. This skill addresses the structural decision layer — it does not replace role-specific skills for building individual integrations, configuring Named Credentials, or setting up SSO providers.
Before Starting
- What is the actual driver? Regulatory data residency, M&A, distinct business unit with no data overlap, or has "we should have separate orgs" become an assumption without a justification? The answer shapes everything.
- Is this really a sandbox question? Development, QA, and UAT isolation is handled by sandboxes — not by separate production orgs. If the conversation is about dev/prod separation, use the sandbox-strategy skill instead.
- What data needs to cross org boundaries? If the answer is "most of it," that is a signal that multiple orgs may be the wrong call.
- Who manages user access across the orgs? Deactivation, permission changes, and onboarding must be replicated independently in each org unless an external IdP handles provisioning.
Questions to Ask Before Configuring
Each question traces to a gotcha in references/gotchas.md.
| Question | Why it matters | What a good answer adds | What proper configuration adds over just doing it |
|---|---|---|---|
| "What written requirement can one org not satisfy?" | Without one, every extra org buys duplicated users, licences, releases, and API budgets for nothing | A named regulation, contract clause, or divestiture date in the decision record | The org count is defended by a requirement, and the record says when to revisit it |
| "Which data must cross org boundaries, in which direction, and how many records per day?" | The receiving org's inbound API allocation comes from its own licences, and small spokes run out first (Gotcha 3) | A per-pair volume table and the receiving org's allocation from the Limits Quick Reference formula | Bulk API 2.0 or batched calls chosen up front instead of after a 24-hour lockout |
| "Must the other org's data drive automation, formulas, or roll-ups, or only be displayed?" | External objects take no triggers, formulas, roll-ups, or master-detail (Gotchas 2, 5) | A split between display-only reads (cross-org adapter) and replicated data (sync jobs) | Automation runs in the owning org, so nothing waits on a trigger that cannot exist |
| "Which identity provider owns users, and how is a leaver deactivated in every org?" | SSO stops new sessions but deactivates nothing; JIT acts only at login (Gotchas 4, 9) | A provisioning and deprovisioning design per org, with one SAML registration per org | Leavers lose access everywhere on the same day, and MFA is enforced at the IdP for every org |
| "Is Salesforce to Salesforce enabled anywhere, and which connections are accepted today?" | S2S connections have their own lifecycle and no supported growth path (Gotcha 1) | The PartnerNetworkConnection inventory with a replacement per connection | A dated retirement plan instead of a fragile connection nobody owns |
| "Which integration user in each target org serves each cross-org connection?" | A named-principal connection fails for everyone when that one user changes (Gotcha 8) | A dedicated user per data source, excluded from automated leaver jobs | Cross-org reads survive offboarding sweeps and credential rotations |
What proper configuration adds over "just connecting the orgs": each org has a stated reason to exist, each data flow has an owner and an API budget, and identity lifecycle covers every org rather than the first one.
Recommended Workflow
- Record the driver. Write the requirement that a single org cannot satisfy and test it against "When Multiple Production Orgs Are Justified" below. No written requirement means a single-org recommendation.
- Inventory what exists. For each org, capture licences by type, the 24-hour inbound API allocation, active S2S connections (
SELECT ConnectionName, ConnectionStatus, ConnectionType FROM PartnerNetworkConnection), named credentials, external data sources, and integration users. - Choose the topology (single org, hub-and-spoke, or peer-to-peer) with Mode 1 Step 2, and name the system of record for every shared object.
- Pick a mechanism per org pair from the Integration Pattern Decision Matrix, and check its daily volume against the receiving org's allocation (Gotcha 3).
- Design identity per org: one SAML registration each, Federation ID mapping, and an explicit deprovisioning path (Gotchas 4, 9).
- Write the decision record and release manifest (worked example in
references/examples.md, Example 4), then runpython3 scripts/check_multi_org.py --project-dir <force-app>to catch S2S use, hard-coded org Ids, and literal callout endpoints. - Set the review trigger: contract renewal, a Hyperforce region becoming available, or the end of an M&A transition, with an owner for consolidation.
Core Concepts
Single Org Is the Default Recommendation
Salesforce architects strongly recommend single-org architecture unless a specific, documented requirement justifies multiple orgs. A single org eliminates:
- Cross-org data synchronization overhead (no API calls, no sync jobs, no eventual consistency risk)
- User management duplication (one user record, one deactivation action, one permission set assignment)
- Licensing complexity (licenses belong to one org; none are shared across orgs)
- Governor limit exposure from cross-org callouts (each callout consumes limits on both sides)
- Deployment coordination across two or more separate release pipelines
When requirements can be satisfied inside a single org using standard multi-tenancy features (Sharing Rules, Record Types, Permission Sets, Business Units in Marketing Cloud), a single org is always the lower-risk, lower-cost path.
When Multiple Production Orgs Are Justified
Multiple production orgs are justified only when a single org structurally cannot satisfy the requirement:
| Scenario | Justification | Notes |
|---|---|---|
| Regulatory data residency | EU GDPR or similar law requires that personal data remain in a specific geographic region and Salesforce's Hyperforce region selection in a single org does not satisfy the regulator | Verify with Salesforce Account team whether Hyperforce resolves the requirement before committing to a second org |
| Distinct business units with zero data overlap | Two fully independent companies or brands that happen to share a Salesforce contract, but share no customers, users, or processes | Rare in practice; most BU separation is handled with Sharing Rules and Permission Sets |
| M&A integration (transitional state) | An acquired company runs a separate Salesforce org and migration into the acquiring org has not yet been completed | Treat this as a temporary state with a migration plan; do not design permanent multi-org architectures around M&A without a clear end state |
| Independent ISV product with tenant isolation | A product sold to external customers requires strict data isolation per customer (not just Sharing Rules) | ISV-specific pattern; consult Salesforce ISV architect guidance |
What Multiple Orgs Do NOT Solve
- Development vs. production isolation: That is sandboxes. Use sandboxes.
- Performance problems in a single org: Multiple orgs do not redistribute governor limits in a meaningful way; they duplicate them.
- Large data volume concerns: LDV strategies (indexes, archival, Big Objects, skinny tables) are the correct approach inside a single org.
Mode 1: Design a Multi-Org Strategy from Scratch
Use this mode when a new org topology is being designed before any build begins.
Step 1 — Confirm the multi-org justification
Ask the client or stakeholder to provide a written requirement that a single org cannot satisfy. If they cannot articulate one, default to single-org architecture. Document the justification in the architecture decision record.
Step 2 — Select an org topology
Option A: Single Hub Org All business processes live in one production org. Cross-system data exchange is handled via Salesforce APIs to external systems (non-Salesforce). This is the preferred end state.
Option B: Hub-and-Spoke One "hub" org aggregates and coordinates data from multiple "spoke" orgs. The hub holds canonical records or reporting aggregates. Spoke orgs hold domain-specific data.
- Hub-to-spoke and spoke-to-hub data flow uses REST API or Bulk API 2.0 — not Salesforce-to-Salesforce.
- Salesforce Connect (External Objects) in the hub org can surface spoke data as virtual records without full replication.
- The hub org's integration user must have a Connected App in each spoke org with appropriate OAuth scopes.
Option C: Peer-to-Peer Two or more orgs exchange data directly with no central coordinator. This topology has the highest complexity and is the hardest to govern. Avoid it unless the orgs have truly independent data domains with only occasional cross-org lookups.
Step 3 — Design cross-org data exchange
For each org pair that must exchange data:
- Choose the integration mechanism:
- REST API: preferred for record-by-record or small-batch synchronous exchange
- Bulk API 2.0: preferred for large-volume nightly or periodic sync jobs (millions of records)
- Salesforce Connect (External Objects): preferred for near-real-time cross-org lookup without full replication; data is queried on-demand via OData 2.0/4.0 adapter or a custom adapter
- For another Salesforce org specifically, use the cross-org adapter (
ExternalDataSourcetypeSfdcOrg), not OData (see Gotcha 7)
- Authenticate with Named Credentials:
- Create a Connected App in the target org (the org being called).
- Create a Named Credential in the calling org that stores the OAuth 2.0 JWT Bearer credentials for that Connected App.
- Never store client secrets, access tokens, or refresh tokens in Custom Settings, Custom Metadata, or Apex code.
- Use the JWT Bearer flow (server-to-server, no user interaction) for scheduled or automated cross-org calls.
- Define data ownership:
- Each record has exactly one system of record. The owning org creates and updates it. Other orgs read or receive copies.
- Avoid bidirectional sync unless absolutely required; bidirectional sync requires conflict resolution logic and has no native Salesforce support.
Step 4 — Design identity and SSO
- Use an external IdP (Okta, Azure AD, Ping) as the SSO provider for all orgs.
- Configure each Salesforce org as a separate Service Provider (SP) registered with the same IdP.
- Users authenticate once against the IdP and receive a SAML assertion for the target org.
- User provisioning (SCIM) from the IdP to each org automates account creation and deactivation.
- Do not rely on manual admin processes to deactivate users across orgs — deactivation in one org does not deactivate in another.
Step 5 — Account for licensing
- Each Salesforce production org requires its own license allocation.
- Licenses are not shared across orgs. A user who needs access to two orgs requires two license seats.
- Validate the license implications with the Salesforce Account team before finalizing the topology.
Mode 2: Review an Existing Multi-Org Architecture
Use this mode when reviewing an inherited or in-flight multi-org design for risks and improvement opportunities. Run the inventory in Recommended Workflow step 2, then score the estate against the checklist below.
Review Checklist
- [ ] Justification is documented: Each production org has a written requirement that a single org cannot satisfy. If not, consolidation should be evaluated.
- [ ] No Salesforce-to-Salesforce (S2S) in active use for new integrations: S2S is a legacy feature. Any active S2S connections should have a migration plan to REST API + Named Credentials.
- [ ] Named Credentials used for all cross-org callouts: No hard-coded org IDs, client secrets, or access tokens in Apex, Custom Settings, or Custom Metadata.
- [ ] Connected Apps scoped correctly: Each Connected App grants the minimum required OAuth scopes. Avoid
fullscope. - [ ] Data ownership is defined: Each record type has exactly one system of record. Bidirectional sync is explicitly documented and has conflict resolution logic.
- [ ] User deactivation process spans all orgs: When a user is offboarded, the process covers every org they have access to (or the IdP SCIM push handles it automatically).
- [ ] Governor limit budget is understood: Cross-org callouts consume Apex callout limits (100 callouts per transaction), HTTP limits, and SOQL limits on both sides. The design should account for peak load.
- [ ] External Objects are used for read-only cross-org lookup: If an org only needs to display data from another org without owning it, Salesforce Connect is lower overhead than full record replication.
- [ ] Bulk API 2.0 used for high-volume sync: Nightly or periodic sync of more than a few thousand records should use Bulk API 2.0, not REST API row-by-row.
Mode 3: Troubleshoot Multi-Org Integration Problems
Use this mode when cross-org integrations are failing, hitting limits, or behaving inconsistently.
Diagnostic Table
| Symptom | Likely cause | Where to look |
|---|---|---|
| Cross-org callout hitting API limit | Both orgs consuming callout limits simultaneously; or S2S hitting SOAP API limits on both ends | Debug logs on calling org (check CALLOUT_REQUEST/CALLOUT_RESPONSE); API Usage in target org Setup |
| Named Credential OAuth token expired or invalid | JWT certificate rotation or Connected App scope change | Named Credential config in calling org; Connected App session policies in target org |
| External Object query returning no rows | Cross-org (SfdcOrg) data source endpoint or apiVersion changed; integration user deactivated or permission revoked in the target org | Salesforce Connect external data source setup; Check integration user profile and permission set in target org |
| Hard-coded org ID causing failures in new environment | Org ID embedded in Apex, Custom Settings, or Flow | Search Apex source for 18-char Salesforce org ID pattern; check Custom Settings and Flow variable defaults |
| Salesforce-to-Salesforce connection broken after org refresh | S2S connections are environment-specific; sandbox refresh resets them | Migrate off S2S; use Named Credentials + REST API instead |
| Users can SSO into one org but not the other | SP configuration mismatch in IdP; Entity ID or ACS URL wrong for second org | SAML settings in both orgs; IdP application configuration |
| Sync job creates duplicates | No deduplication key defined; bidirectional sync without conflict resolution | Upsert key selection on target org; review sync job logic for idempotency |
| Bulk API 2.0 job failing for cross-org data load | Integration user lacks bulk API permission; field-level security on target org blocking fields | Integration user profile in target org; Bulk API permission set assignment |
Integration Pattern Decision Matrix
| Scenario | Recommended Pattern |
|---|---|
| Read another org's record on-demand (low volume) | Salesforce Connect cross-org adapter: ExternalDataSource type SfdcOrg (corrected from "OData adapter"; see Gotcha 7) |
| Sync a small number of records in near-real-time | REST API callout from Apex or Flow → Named Credential + Connected App |
| Nightly full sync of hundreds of thousands of records | Bulk API 2.0 job from scheduled Apex or MuleSoft/external ETL |
| New multi-org integration replacing Salesforce-to-Salesforce | REST API + Named Credentials (JWT Bearer) — deprecate S2S immediately |
| Report across data in multiple orgs | CRM Analytics with multi-org data connectors, or replicate to a dedicated analytics org |
Salesforce-to-Salesforce (S2S) — Legacy Feature Notice
Salesforce-to-Salesforce is a native Salesforce feature that allows records to be published from one org and subscribed in another. It exists and continues to function, but Salesforce considers it a legacy integration approach.
Do not use S2S for new integrations. Reasons (UNVERIFIED (2026-10-03): the four reasons below come from Salesforce Help and field experience, which this revision could not fetch; the grounded facts are the PartnerNetworkConnection lifecycle and availability rules in references/gotchas.md Gotcha 1):
- S2S uses SOAP API under the hood, consuming API call limits on both orgs for every record exchange.
- It does not scale to high record volumes — each record publication is a separate API transaction.
- It offers no support for modern OAuth patterns, Named Credentials, or JWT Bearer flows.
- It creates tight coupling between orgs with no abstraction layer for error handling or retry logic.
Migration path from S2S: Replace with a REST API integration authenticated via Named Credentials (JWT Bearer flow) in the calling org, with a Connected App in the target org. For high volume, use Bulk API 2.0.
Related Skills
integration/named-credentials-setupandapex/apex-named-credentials-patterns: Named Credential and External Credential configuration (the earlierintegration/named-credentials-and-calloutspath does not exist)integration/salesforce-to-salesforce-integration: building the S2S replacement or cross-org sync once this skill has chosen the patternsecurity/sso-configurationandsecurity/scim-provisioning-integration: SAML registration per org and deprovisioningarchitect/architecture-decision-records: the record format used in Example 4architect/solution-design-patterns— for broader automation layer decisionssecurity/skills — for OAuth scope design and IP range restrictions on Connected Appsdata/skills — for LDV design within a single org (an alternative to multi-org for data volume concerns)