Salesforce Integration

The Salesforce integration keeps your Pryzm workspace aligned with a connected Salesforce org. You can pull Accounts, Contacts, and Opportunities into Pryzm as Organizations, People, and records in a pipeline entity, map custom attributes to Salesforce fields, and push individual records back to Salesforce when they change. This is a workspace-level integration: one Salesforce org per Pryzm workspace. It is not available on FedRAMP deployments.

​

What syncs

Standard mappings are Account → Organizations, Contact → People, and Opportunity → a pipeline entity you choose during setup.

​

Prerequisites

• Your workspace has the Salesforce Integration product module enabled.

​

Salesforce user

Who completes OAuth needs:

• API Enabled on their Salesforce profile.
• Permission to use the Pryzm connected app with at least Manage user data via APIs (api) and Perform requests at any time (refresh_token, offline_access). Approve all scopes on the consent screen.
• Read, Create, and Edit on Account, Contact, and Opportunity, including the fields you map. Sharing rules and field-level security must not block the records and fields you expect to sync.

​

Pryzm user

Whoever connects the integration, configures mapping, or syncs needs both integration rules and entity access: Custom roles can grant these rules in Settings → Security → Roles. They also need Editor access on each synced entity (Organizations, People, and the pipeline entity used for Opportunities). View-only entity access is not enough to configure mapping, pull, or push synced records. Install the Pryzm package and connect your org (Connecting below) before you configure mapping or sync.

​

Connecting

​

Install the Pryzm package

A Salesforce admin must install the Pryzm managed package in your production org before anyone connects the integration in Pryzm. Salesforce sandbox orgs are not supported yet.

1. Sign in to Salesforce as an admin.
2. Open the install link: Install Pryzm package.
3. Choose Install for Admins Only or Install for All Users, as your org policy requires.
4. Complete the installer and confirm the package appears under Setup → Installed Packages.

​

Connect your org

1. Open Settings → Integrations (or go to /integrations).
2. Under Workspace Integrations, click Salesforce.
3. On the Salesforce page, click Connect.
4. Sign in to Salesforce and approve the requested permissions.
5. When you return to Pryzm, the connection card should show Connected with your org name and username.

To disconnect, open the same page and click Disconnect. That revokes the workspace connection; existing Pryzm records are not deleted.

​

Configure mapping

Open Settings → Integrations → Salesforce, then Configure mapping. Mappings are directional: each object pair and each field pair defines which way data may flow. Salesforce fields that are read-only in your org (not createable and updateable) can only be mapped as Pull. Pryzm will not push to formula fields, roll-up summaries, or other read-only Salesforce columns — set those mappings to Pull (or leave them unmapped for push).

​

Add the Pryzm_ID field

Before you sync, a Salesforce admin should add a custom field on each object you will sync:

1. In Salesforce Setup, create a custom field on Account, Contact, and Opportunity:
   • Label: Pryzm_ID
   • Type: Text, length 36 or greater (Pryzm record IDs are UUIDs)
   • External ID: Enabled
   • Unique: Enabled

Pryzm writes its record ID into Pryzm_ID so every synced Account, Contact, and Opportunity stays linked across pulls and pushes. Without it, Pryzm cannot match records on later syncs and mapping validation will flag an error until the field is configured correctly. You can open the in-app checklist anytime from the Salesforce integration page: Field mapping → Setup.

​

Objects

• Account → Organizations and Contact → People use the standard object pairs.
• Opportunity → Pipeline entity: choose where Salesforce Opportunities should sync. You can pick an existing pipeline entity or create one from the dialog (for example, Create pipeline from Salesforce stages).
• Set an object direction for each pair (bidirectional, pull, or push). Object direction limits which sync operations are allowed for that Salesforce object.

Opportunity push and pull require a pipeline entity. Until one is selected, bulk sync stays disabled.

​

Fields

Map only the Salesforce fields your team actually uses in Pryzm. We do not recommend mapping every available Salesforce column — a smaller, intentional mapping keeps your Pryzm schema easier to maintain and avoids pulling unused or noisy data into records and reports. For Opportunities (pipeline entity), Organizations (Accounts), and Contacts (People), map each Pryzm attribute to a Salesforce field and set a field direction:

• Bidirectional — value can flow both ways when you pull or push.
• Pull — Salesforce updates Pryzm on import; the field is not sent on push.
• Push — Pryzm updates Salesforce on export; the field is not applied on pull.

The dialog shows default mappings plus your workspace attributes. Selections save as you go; errors block sync until resolved. Links in the mapping UI open the right attribute settings (the pipeline entity, org/people data models for the others).

​

Pull data from Salesforce

After mapping is valid:

1. On the Salesforce integration page, use Pull from Salesforce under Sync data.
2. Pryzm queues jobs in order: Accounts, Contacts, then Opportunities (shown as Organizations, People, and your pipeline entity in Pryzm). Progress appears per object type.
3. Use History (or /integrations/salesforce/jobs) to inspect past sync jobs and per-record results.

If records were synced before, Pryzm asks whether to Skip existing (only new/changed links) or Overwrite (refresh linked records from Salesforce). Resolve any mapping errors shown on the sync card before pulling again.

​

Push to Salesforce

Push updates a single Pryzm record to the linked Salesforce object.

1. Ensure the workspace is connected and mapping is complete (including a pipeline entity).
2. Open the record in Pryzm (Organization, Person, or a record in your pipeline entity).
3. Use Push to Salesforce in the record actions.

If the record was pushed before, Pryzm asks whether to Overwrite the Salesforce record with current Pryzm data. Failed pushes surface which fields did not write; fix mapping or Salesforce validation rules and try again.

​

Troubleshooting

​

Missing or skipped field values

Pryzm does not fail an entire record just because one attribute could not sync. Values are dropped or skipped when:

• The Pryzm attribute has no mapping to a Salesforce field.
• The mapping direction does not include the operation you ran (for example, a Push-only field is skipped on pull, and a Pull-only field is skipped on push).
• The mapping has a validation error (for example, incompatible types or a missing Salesforce field).
• The value cannot be coerced into the target type (picklist option mismatch, unsupported shape, blank where Salesforce requires a value).
• The Salesforce field is read-only but the mapping is set to Push or Bidirectional — change the direction to Pull or remove the mapping from push paths.

Mapped fields that pass validation for that direction are still written. Fix mapping in Configure mapping, then pull or push again.

​

Sync history and field results

Use Sync data → History on the Salesforce integration page (or /integrations/salesforce/jobs) to debug bulk pulls and pushes.

1. Open the job that ran (Accounts, Contacts, Opportunities).
2. Review per-record outcomes on the job detail page.
3. Expand a record row to see field results for which attributes synced and which were skipped.

When a value is missing after sync, check the field’s direction in Configure mapping first, then use field results on the job to see what Pryzm skipped and why.

​

Relationships on push

Pryzm does not auto-create related Salesforce records when you push. Lookup and relationship fields (for example, a Person’s organization or an Opportunity’s account) are only written when the related Pryzm record is already linked from a prior pull or push. If a relationship is missing in Salesforce after push, sync or push the parent record first, then push the child again.

​

Related guides

• Records — People, Organizations, and pipeline entities in the records UI
• Pipelines and Campaigns — older pipeline setup guide (pre–records revamp)
• Settings — workspace integrations overview