Skip to main content

Salesforce-controlled field options

For eligible field pairs in the Salesforce integration, you can automatically set the Planhat field's value options from the value options in the Salesforce field

Written by Alexander Käll

Summary

  • You can enable a "fetch options from Salesforce" feature on field mappings, allowing Salesforce to be the single source of truth for list/multipicklist field options in Planhat. On syncing from Salesforce to Planhat, new field value options are automatically created, deleted options are removed. Field value option editing is locked in Planhat

  • You toggle this on per field pair in the Salesforce mapping, and it requires you to sync records with the field data for it to work

  • This isn't available for Planhat system fields as these have some preset options used for native capabilities (e.g. "Closed Won" Deals)

  • This functionality eliminates manual syncing work and avoids sync errors

Who is this article for?

  • Planhat users who are admins/builders configuring the Salesforce integration for their organization

Series

We have a series of articles on the Salesforce integration:

Article contents

Introduction

In the Planhat Salesforce integration, you map Salesforce objects (e.g. Account) to Planhat models (e.g. Company). Within this, you can map individual fields between these object/model pairs. You also choose sync directions for objects/models and fields.

You can read more about custom field mapping here in our main Salesforce integration article.

When you are mapping list/multipicklist fields, it's important that the values (possible options) in those fields are identical in both systems. For this, Planhat's values need to match the internal Salesforce API names (rather than the label names).

Historically, you would need to manually ensure that the field values set up in the two systems match - e.g. set up a custom field in Planhat to receive data fetched from a Salesforce field, and give it field value options that exactly match those in Salesforce. If you have discrepancies between the two systems, this could cause issues with the sync.

However, with this new (released in Q3 2026) ability to have Salesforce-controlled field options, the list field values in Planhat are automatically created/updated/deleted to match those of the corresponding field in Salesforce, automatically ensuring consistency.

This keeps Planhat data aligned with Salesforce without someone needing to update list value options by hand, and prevents the frustration of stale or conflicting field values.

What are Salesforce-controlled field options, and how is this functionality enabled?

📌 Summary

  • You can set a Salesforce picklist to "own" the option list of a Planhat list or multipicklist field

  • You enable it for a field mapping pair in the Salesforce integration by selecting the checkbox on the right

When you're setting up field mapping in the Salesforce integration, for eligible field rows, you will see a checkbox on the right-hand side (the Salesforce side) that you can select, which then enables the field values in Planhat to be automatically populated from the field values in Salesforce. (We discuss in detail what makes field rows eligible below.)

Mousing over the checkbox, you'll see an explanatory tooltip, summarizing the actions if this is enabled.

With it on, the mapped Planhat field stops being manually editable (shown in the screenshot below), and its list value options are taken from the Salesforce picklist instead.

  • List value options present in Salesforce are created on the associated field in Planhat

  • List value options not present in Salesforce are removed from the associated field in Planhat, and cleared from every Planhat record with that list value option selected

  • List value options not present in Salesforce are also removed from other places they are referenced in Planhat - e.g. Automations, filters, Pages, metrics (time-series data), Success Units, Company Profile Templates, Role permissions, and access tokens

As we mentioned, once enabled, this feature locks the list value options for the field in Planhat - if you navigate to the field in the "Data Model" Global Tool, you will see a padlock symbol next to the list values, and if you mouse over this, a tooltip will inform you that "This field is controlled by the Salesforce integration".

Which field mapping rows are eligible

The checkbox for Salesforce-controlled field value options isn't present for every field mapping row - it's only visible for eligible field rows.

There are 3 conditions that need to be met for this feature to be available:

  • The Planhat field is a custom field of type list or multipicklist. Custom fields on system models, and fields on custom models, both qualify. System fields (also called default/standard fields) never do

  • The Salesforce field is of type picklist, multipicklist or combobox

  • The field mapping and its object/model sync section both fetch records from Salesforce - i.e. the sync direction is "Receive from Salesforce" or "Both Directions"

Example of an eligible field mapping row, and the actions/results

  • Salesforce:

    • Industry__c field on the Account object

    • which is a picklist

    • with field values Fintech, Healthcare, Retail

  • Planhat:

    • Custom Industry field on the Company model

    • with the field type list

    • with field values Fintech, Retail, Media

  • Sync direction:

    • Receive from Salesforce on both the main Company/Account model/object section and the field mapping

When records are fetched from Salesforce:

  • Healthcare is created as a list value option on the Planhat field

  • Media is deleted as a list value option from the field, and cleared as a field value from every Company record with it selected for the field

  • Fintech and Retail are untouched

  • The stored list value options of the Planhat field are sorted alphabetically: Fintech, Healthcare, Retail

📌 Further details

Selecting the checkbox to turn the feature on, in cases where the Planhat field has value options that do not exist in Salesforce, brings up a confirmation message naming them, to warn you that they will be deleted from the field and cleared from records on the next fetch. For the example above: "This option does not exist in Salesforce and will be deleted from the field, and cleared from records holding them, on the next fetch: Media."

Example of an ineligible field mapping row, and the actions/results

  • Salesforce:

    • StageName field on the Opportunity object

    • which is a picklist

  • Planhat:

    • System Stage field (API name: stage) on the Deal model

    • with the field type list

In this case, because the Planhat field is a system field (default/standard field), the option is not available - no checkbox appears in the integration for this field mapping row.

Workarounds for ineligible fields

If you want to sync from a Salesforce field to a Planhat field that is not eligible for this functionality (such as Task Status or Deal Stage) then your options are as follows:

  • Simply do regular field mapping, manually ensuring that the field value options in Planhat and those in Salesforce match up

  • Alternatively, you can create a custom list field in Planhat to use alongside the system field, which you enable Salesforce-controlled field options for, and then use a Planhat Custom Automation to update the Planhat system field from the Planhat custom field

Planhat system fields excluded

Every built-in Planhat system field (default/standard field) is excluded, whatever its input looks like in the Planhat UI.

This rule is simple, but can be easy to miss, because some system fields have dropdowns and may be mistaken for custom list fields. Their list value options come from one of two places, neither of which the integration can take over - we detail these below.

Hardcoded

The field values cannot be changed by anyone, in any tenant.

This includes the following Planhat fields (with API field names listed):

  • Company status

  • Conversation category

  • Conversation sentiment

  • Invoice invoiceCycle

  • Invoice status

  • License invoiceCycle

  • Licence noticeUnit

  • License renewalStatus

  • Line Item noticeUnit

  • Line Item productType

  • Line Item status

  • NPS scoreType

  • Opportunity status

  • Product noticeUnit

  • Product type

  • Task mainType

  • Task repeat

  • Task state

  • Workflow status

  • Workflow type

Configured elsewhere in Planhat

The values are tenant-specific and editable, but they live in a Planhat setting or in another model's records rather than on a custom field.

This includes the following Planhat fields (with API field names listed):

  • Company hProfile

  • Company phase

  • Churn currency

  • Churn reasons

  • Conversation activityTags

  • Conversation marketingEmailCategory

  • Conversation type

  • Deal currency

  • Deal stage

  • End User marketingEmailUnsubscribedCategories

  • Invoice currency

  • Issue status

  • License _currency

  • License product

  • Line Item currency

  • Line Item package

  • NPS campaignId

  • Opportunity _currency

  • Opportunity salesStage

  • Product currency

  • Product packages

  • Project currency

  • Sale _currency

  • Sale product

  • Sprint status

  • Task activityTags

  • Task status

  • Task type

  • Task workflowTemplateId

  • Workflow outcome

  • Workflow targetModel

  • Workflow templateId

Further details

When it runs

The process of automatically aligning the field list value options runs at the start of every scheduled and full record sync, and on the object/model sync section's own "Fetch data from Salesforce" button. On scheduled runs, a sync section fetched within the last hour is skipped.

Pausing

Setting a mapping's direction to "Not Syncing" or "Send to Salesforce" (i.e. stopping the fetch of data from Salesforce to Planhat) disables this feature: the Planhat field becomes manually editable again, and its list value options stop syncing. You will see this stated in the UI: "Fetching options is paused because this field's data isn't fetched from Salesforce." Changing the sync back (so records are fetched from Salesforce) will reactivate the functionality.

Inactive values

A field value option that is present in Salesforce but marked inactive, is neither added as a new option in Planhat nor treated as a deletion (i.e. a value to be removed from Planhat). Only a value that is entirely absent from the Salesforce picklist is counted as a deletion.

Ordering and size

The list fetched from Salesforce is sorted alphabetically with numeric-aware comparison. A picklist with over the maximum of 500 values is skipped and reported.

One controlling Salesforce field per Planhat field

You cannot simultaneously map list options to one Planhat field from multiple different Salesforce fields; if you try to save this configuration, it will be rejected with the message "A Planhat field can only take options from one Salesforce field."

Permissions

To be able to turn the checkbox on or off to activate/deactivate the feature for a mapped field pair, your Planhat Role needs to have the "CustomField" update data model permission enabled (as it updates the Planhat custom field by locking or unlocking its available values).

Outbound syncing

Planhat keeps note of the Salesforce list values, and uses this when sending data to Salesforce, to ensure that Planhat will not send a value to Salesforce that it will not accept.

Did this answer your question?