Connecting orgs

Both promotion paths — the Map & promote workbench and Deploy to Sandbox — push configuration into another org. Before either can reach a destination, an admin connects the two orgs once. This page walks through that setup end to end.

A connection has two parts, and they live in two different places:

  1. A Salesforce Named Credential — a standard platform feature that holds where the target org is (its secure HTTPS address) and how to authenticate. This is created in Salesforce Setup. All of the sensitive material lives here.
  2. A Config Promotion Target — a small Pinion record that gives the connection a friendly label and points at that Named Credential by name. This is what the promotion pickers list. It holds no secrets.

Once both exist, the target appears in the promotion pickers by its label, and you choose it like any dropdown.

Before you start: which direction, and same family

A promotion is only accepted by the receiving org when it’s allowed by direction and family. Confirm these before you wire anything up:

  • Allowed directions. Pinion allows sandbox → sandbox, sandbox → production (deploy up), and production → sandbox (seed a sandbox). The one blocked direction is production → production — refused by design as a conservative default.
  • Same promotion family. The target only accepts promotions from orgs in its own promotion family. A production org and the sandboxes refreshed from it share a family automatically; two unrelated orgs do not. A cross-family promotion is blocked even when the direction would otherwise be allowed.

These guardrails live on the target side and surface as a clear blocked message in preview — see Troubleshooting for the exact reasons. They’re worth confirming up front because a connection that’s wired perfectly will still refuse a promotion that points the wrong way.

Step 1 — Create the Named Credential (Salesforce Setup)

This is the part that carries the real connection. Do it once per target org, in the source org’s Setup.

  1. In the target org, note its My Domain login URL (Setup → My Domain), e.g. https://acme--uat.sandbox.my.salesforce.com. This is the address the credential will point at.
  2. In the source org, go to Setup → Named Credentials.
  3. Create an External Credential that carries the authentication to the target (for example an OAuth or JWT-based principal that authenticates as a promotion user in the target). The External Credential is where the token/identity lives.
  4. Create a Named Credential whose URL is the target org’s My Domain and whose authentication references the External Credential from the previous step. Give it a clear developer name you’ll recognize, e.g. Pinion_UAT_NC.
  5. Make sure the running admin user is granted access to the External Credential’s principal (via a permission set), so the callout can authenticate.

Step 2 — Register the target in Pinion

Now pair that Named Credential with a friendly label by creating a Config Promotion Target record. This is the record the promotion pickers read.

Create a new Config Promotion Target record and fill in:

  • Label (required) — the friendly name you’ll pick the target by, e.g. “UAT Sandbox” or “Customer ACME”. This is all you ever see in the promotion screens.
  • Named Credential (required) — the developer name of the Named Credential you created in Step 1, e.g. Pinion_UAT_NC. This is a name only, never a secret.
  • Description (optional) — a note for your own reference (its purpose, owner, or refresh cadence).

Step 3 — Verify the target appears in the picker

Once the record exists, confirm the connection is wired up: open a promotion path and check the target shows up by its label.

  • In the Map & promote workbench, the Target org dropdown lists your registered targets by label.
  • In Deploy to Sandbox, the Target connection dropdown lists the same targets.
A target picker in a Config Promotion tab, showing registered connected targets listed by their friendly labels
Registered targets appear in the promotion pickers by their friendly label — you never handle the underlying credential.

Pick your target and run a preview. A preview is read-only — it writes nothing — but it exercises the live connection: it calls the target through the Named Credential and returns what the promotion would do, plus an allow/blocked verdict. A preview that returns counts (and isn’t blocked) confirms the connection authenticates and the direction is allowed. A preview that returns a blocked message means the connection reached the target but a guardrail refused the direction or family — see Troubleshooting.

Common failure modes

Most connection problems explain themselves inline. The usual ones:

  • Empty picker — no target registered, or missing the Pinion Administrator permission set. Register a target (Steps 1–2) or get the permission set assigned.
  • Callout fails immediately — the Named Credential is missing, misnamed on the target record, or its authentication has lapsed. Confirm the Named Credential field on the Config Promotion Target matches a real Named Credential developer name, and that the External Credential’s authentication is still valid (tokens expire).
  • Promotion blocked — the connection reached the target, but the target refused the direction (e.g. production → production) or the orgs aren’t in the same family. This is a guardrail, not a connection fault.

For the exact messages and how to resolve each, see Troubleshooting.