Config Promotion

Pinion configuration lives as records — products, bundles, pricing and product rules and their conditions/actions, attributes and their values, price dimensions, discount schedules, block pricing. Config Promotion is how you move that configuration from one org to another — sandbox → production, or a template org → a customer org — idempotently: re-running a promotion never duplicates a record it already moved, and never clobbers a record the target already has.

You’ll find it in the Pinion admin app under the Config Promotion page.

The Config Promotion page in the Pinion admin app, showing the tab bar: Map & promote, Export, Import, Deploy to Sandbox, History
The Config Promotion page — the admin surface for moving catalog and pricing configuration across orgs. Map & promote and Deploy to Sandbox are the two paths this guide covers.

The problem it solves

A Salesforce record’s 18-character Id is org-local — the same product has a different Id in your sandbox than in production. So the Id can’t be the key that says “this record over here is the same record as that one over there.” Config Promotion needs a record identity that is stable across orgs, and that’s the SyncKey.

A SyncKey is a unique, durable, per-record identity (a UUID) stamped on every promotable config record. Once stamped it’s immutable — Pinion won’t let it change. The promotion tooling keys everything on it: the idempotent upsert into the target, the remapping of lookups (so a child points at the right parent in the target org), and the source ↔ target diff. The Cross-org identity & install order page covers the SyncKey in full, including the install sequence that makes orgs share keys automatically.

Two ways to promote

Config Promotion gives you two paths, for two different jobs:

  • Map & promote workbench — the granular path. Pick a connected target org and a parent object; the workbench lists that object’s records in your org and the target org side by side, joined by SyncKey. You map each parent by hand (connect it to an existing target record, or mark it to create new), inspect the field-by-field differential, opt specific children out, then promote just the records you checked. This is the precise, record-by-record tool.

  • Deploy to Sandbox — the bulk path. One click pushes your entire promotable catalog into a connected sandbox: existing records are updated, missing ones are created carrying your keys, unchanged ones are left untouched. There’s no manual mapping — everything is auto-matched by SyncKey. This is the reliable way to seed a sandbox after a refresh.

A promotion is self-contained

When you promote a record, Pinion assembles a self-contained bundle — you don’t have to promote dependencies separately or in any particular order. The engine walks two relationships and carries everything the record needs along with it:

  • Owned children travel (walk down). A pricing rule travels with its conditions and actions; a product travels with its bundle options, attributes, dimensions, discount schedules, and block pricing.
  • Referenced records travel too (walk up). Records the promoted record merely points at — the product a rule references, the attribute a value belongs to — are pulled into the bundle so the import has no dangling reference. And because a pulled-in record brings its own owned children, the whole referenced subtree rides along: promoting a pricing rule that references a product pulls in that product and its dimensions, bundle options, block prices, and prices.

The result is that the target ends up complete, and the promotion is idempotent — anything that already matches in the target is a no-op. You map the records you care about; Pinion carries the rest. (In the rare case a reference genuinely can’t be resolved — a non-promotable target, or a record that can’t be auto-provisioned — that surfaces as an actionable error; see Troubleshooting.)

What can and can’t be promoted

Config Promotion moves your catalog and pricing configuration. It’s built to carry the parts of your setup that are meant to look the same in every org — and, by design, to leave behind the parts that belong to one specific org.

Configuration that promotes

These config areas travel:

  • Products and bundles — products, their bundle features and options, and option constraints.
  • Pricing and product rules — both rule types, with their conditions, actions, and bundle scopes.
  • Attributes — attribute definitions, their values, and number bands.
  • Price dimensions and segment templates — the multi-dimensional pricing setup.
  • Discount schedules and block pricing — volume tiers, block-price bands, and the product / pricebook links that apply them.
  • Lookup tables — lookup queries, their match criteria, and their data rows.
  • Quote templates — templates, their versions, translations, merge tokens, and summary variables.
  • Pricing waterfalls — waterfall definitions with their ordered pricing steps and applicability rules. Each version of a waterfall promotes as its own record, so a waterfall’s version history travels intact.
  • Promo codes — the reusable discount codes (with their discount unit, value, and effective dates) that a deal can apply.
  • Usage & metered pricing — the metered dimensions on a product, their rate cards, and each card’s tier bands. If a rate card applies to a specific pricebook, that pricebook link travels too (matched by name in the target, or created there if it doesn’t exist yet).
  • Catalog prices — the list prices attached to your products.

Not currently supported

Some things you might think of as “configuration” don’t promote. Don’t expect these to travel with a promotion — set them up directly in each org:

  • Approvals — approval rules, chains, and approver assignments. Approval rules reference specific users, groups, queues, and roles, and those identities are different in every org, so a rule moved across would point at people and teams that don’t exist in the target. Recreate your approval setup in each org.
  • Template routing — the rules that pick a quote template based on the account on a quote. Routing is tied to specific accounts, which are org-specific records, so it isn’t portable. (The quote templates themselves do promote — see the list above; only the account-based routing does not.)

The general rule

Config Promotion carries configuration that has a stable identity across orgs. It does not carry:

  • Org-specific people and records — users, accounts, public groups, queues, roles, and profiles. Any configuration that points at one of these stays behind, because the same identity doesn’t exist in another org.
  • Everyday business data — opportunities, quotes, subscriptions, generated documents, approval requests and decisions, and logs. Config Promotion moves your setup, not your day-to-day transactions.

A note on the other tabs

The Config Promotion page also carries Export and Import tabs — the older file-based promotion flows that predate the workbench. They still work, but Map & promote is the primary surface and supersedes them for day-to-day promotion; this guide focuses on Map & promote and Deploy to Sandbox. History shows the audit log of every promotion run.