Installing Pinion

This page walks an administrator through installing the Pinion managed package end to end — what to set up before you install, what happens during the install, and the steps to finish setup after. It’s written for the person doing the install; the rest of the guide covers day-to-day use.

If you’ll use Config Promotion to move catalog and pricing config between a production org and its sandboxes, there’s one sequencing decision to get right up front — read Before you install carefully.

Before you install

Prerequisites

• A Salesforce admin. You install Pinion as a user with permission to install managed packages (System Administrator, or a profile with Download AppExchange Packages). The same admin assigns permission sets afterward.
• My Domain enabled. Pinion’s UI runs on Salesforce’s modern web-app surface, which requires My Domain to be turned on and deployed (Setup → My Domain). My Domain is already on in most modern orgs; if it isn’t, enable it before installing.
• React Development with Multi-Framework enabled. Pinion’s entire UI — the Product Configurator, Product Display, Product Manager, Approvals, the admin app, and RevOps — is delivered as Multi-Framework standalone-React apps, so this platform feature must be turned on for any Pinion screen to render. Enable it in Setup → React Development with Multi-Framework before installing. This is a hard prerequisite: it’s a Salesforce platform setting the admin enables, not something the package can turn on for you. Without it, the Pinion app pages won’t load.
• A supported edition. Pinion runs on editions that support managed packages, custom objects, and Apex — Enterprise, Unlimited, Performance, and Developer editions. (Group and Essentials editions don’t support the platform features Pinion relies on.)
• Quotes enabled. Pinion is object-agnostic — it drives line items on either Opportunities or Quotes — and ships metadata that references the standard Quote and QuoteLineItem objects (the QuoteLineItem configurator target). Because that metadata is part of the package, Salesforce Quotes must be turned on for Pinion to install and run. Enable it in Setup → Quotes Settings → Enable Quotes before installing. This is a required Setup toggle the admin enables — a standard Salesforce feature, not something the package turns on for you — even if your team configures deals on Opportunities.
• Multi-currency (only if you need it). Pinion supports multi-currency orgs, but multi-currency is an irreversible org setting you enable through Salesforce, independent of Pinion. Turn it on before installing if you need it.

The install-order decision (read this if you’ll use Config Promotion)

Config Promotion moves configuration between orgs by matching each record on a durable cross-org identity called a SyncKey. For two orgs to recognize “the same record,” that record must carry the same SyncKey in both orgs. The install sequence is what makes that happen automatically — so decide your order before you install anything.

The reliable order is production first, then refresh sandboxes from it:

1. Install Pinion in PRODUCTION first. The post-install step stamps a SyncKey on every existing promotable record. Production becomes the key-of-record source — the org whose keys everything else inherits.
2. Then refresh your sandbox(es) FROM that production. A sandbox refresh copies production’s data, including the SyncKey values, so each sandbox inherits production’s keys. The same record now carries the same SyncKey in both orgs, and Config Promotion auto-matches with no manual mapping.

For the full identity model and how to recover misaligned keys, see Cross-org identity & install order.

Installing the package

1. Open the Pinion install URL (from the AppExchange listing or supplied by Pinion) while logged in to the target org as your admin.
2. When prompted for who to install for, choose Install for Admins Only. This is the recommended choice: it installs the package without granting any end user access yet, so you can assign the right permission sets deliberately in the next step rather than exposing everything to everyone. (You can broaden access at any time afterward by assigning permission sets.)
3. Approve any third-party access prompts and start the install. A managed-package install of Pinion’s size runs to completion in a few minutes; Salesforce emails you when it finishes.

What the post-install script runs automatically

Pinion ships a post-install script (PostInstallScript) that runs automatically on every install and every upgrade. You don’t trigger it — Salesforce runs it as part of the install. It does four things, all idempotent and all failure-tolerant (a glitch in any one is logged to the Pinion error log and never aborts the install):

• Stamps SyncKeys across every promotable config record (the SyncKey backfill). On a fresh install this keys whatever config already exists in the org; on an upgrade it keys the existing records of any newly promotable objects the upgrade adds. The backfill runs as a background batch and only touches records that don’t already have a key, so it’s a safe no-op for already-keyed records.
• Seeds the licensing feature-gate matrix (FeatureTierMap__mdt) — the rows that decide which features belong to base vs. Pinion+. These can’t ship as packaged records, so the post-install seeds them.
• Seeds the license-tier ordering (LicenseTierOrdering__mdt) used to resolve a user’s effective tier.
• Re-establishes the approval-escalation schedule if any approval requests are already pending.

The seeding and backfill steps run asynchronously, so there’s a brief window right after install where they’re still completing in the background. That’s expected — the next section shows how to confirm they finished.

After you install

Assign permission sets

Pinion grants access through permission sets (assign these via Setup → Permission Sets → select the set → Manage Assignments). Assign each person the set that matches what they do. The two paid sets buy the configurator/QLE; the rest are free personas that grant moderate, role-specific access without a seat.

Verify the SyncKey backfill ran (and re-run it if needed)

The post-install SyncKey backfill runs as a background batch, so give it a moment after install, then confirm it completed (Setup → Apex Jobs shows the SyncKeyBackfillBatch run as Completed). Every promotable config record should now carry a SyncKey.

If you ever find records that can’t be promoted — they predate a feature, the org was set up from a source deploy rather than a package install, or an install run was incomplete — re-run the backfill on demand. It’s an admin maintenance action:

• In Pinion: the Backfill SyncKeys button on the Maintenance card of the Deploy to Sandbox tab. It enqueues the same idempotent batch and shows the job id. (This is a Pinion+ action, available to the Pinion Administrator permission set.)

Re-running is always safe: the batch only stamps records that don’t already have a key and leaves keyed records untouched, so a re-run that finds nothing is a no-op.

Connect orgs for Config Promotion (Pinion+)

If you’ll promote configuration between orgs, set up the connection once per target. There are two parts:

1. A Salesforce Named Credential (Setup → Named Credentials) that holds where the target org is and how to authenticate to it. All the sensitive material lives here — Pinion only ever references it by name and never stores a secret.
2. A Config Promotion Target record in Pinion that pairs a friendly label (e.g. “UAT Sandbox”) with that Named Credential’s developer name. This is what the promotion pickers list.

Connecting orgs is a Pinion Administrator task. For the full, step-by-step setup — creating the External Credential and Named Credential, registering the target, and verifying it appears in the pickers — see Connecting orgs.

Refresh sandboxes so they inherit the keys (prod → sandbox)

If you followed the production-first order from Before you install: now that production’s post-install backfill has stamped its SyncKeys, refresh your sandboxes from production. Each sandbox inherits production’s keys, the same record carries the same SyncKey in both orgs, and Config Promotion auto-matches with no manual mapping. If a sandbox was refreshed before production was stamped, re-key it after a deploy with the Deploy to Sandbox post-refresh seeding, or align records by hand in the workbench.

You’re ready — a quick verification

A few checks confirm setup is complete:

• Permission sets assigned. At least one admin has Pinion Administrator; reps who build deals have Pinion User.
• Post-install finished. SyncKeyBackfillBatch shows Completed in Apex Jobs, and promotable records carry SyncKeys.
• The configurator opens. A Pinion User can open the Product Configurator on an Opportunity (or Quote) and see Pinion price a line in real time.
• (If using Config Promotion) a target appears by its label in the promotion pickers and a preview returns counts without a blocked message.

With those green, your org is ready. The natural next step is the Setup Wizard — it finishes the configuration a managed package can’t do silently (permission sets, notifications, a Guest Site and Slack app for remote approvals, license activation) and doubles as an ongoing health check. Or head to Welcome to Pinion for the map of the guide, or jump straight to the configurator.

Related

• Setup Wizard — finish post-install configuration (permission sets, notifications, Guest Site, Slack, license) and re-validate org health any time.
• Welcome to Pinion — what Pinion is and the map of this guide.
• Licensing & Tiers — base vs. Pinion+, and how gating behaves.
• Cross-org identity & install order — the SyncKey model and the production-first install sequence in depth.
• Connecting orgs — the full Named Credential + Config Promotion Target setup.
• Deploy to Sandbox — bulk push and the Backfill SyncKeys maintenance button.