Summary
You can sync a Salesforce object into a custom model, the same way you sync Salesforce into Planhat's system models.
A custom model needs a custom keyable to sync: a field you create to hold the Salesforce record Id that records are matched on. Custom models have no built-in
sourceIdthe way system models do, so you always create this keyable yourself. (On system modelssourceIdstays the default identifier; custom keyables bring the same matching to custom models, they do not replacesourceId.)Associations are mapped in the field-mapping section, one mapping per association field. Each mapping can point at the specific keyable on the associated model that holds its Salesforce Id.
You can sync several Salesforce objects into one custom model (extended mapping), and control whether a mapping creates records or only updates existing ones.
Who is this Article for?
Planhat builders and admins who manage the Salesforce integration and want to sync a Salesforce object into a custom model (for example, RevOps or CS Ops).
Series
This article is part of a series on Custom Models:
Creating and managing custom models · create a model, add fields, set permissions, previews, and profiles
Custom associations · associate records across models, *primary* associations, and many-to-many (junction models)
Salesforce integration for custom models · mirror a Salesforce object into a model ⬅️ You are here
Joined tables · show an associated model's field as a column
Custom Models FAQ · common questions
Article Contents
Click below to jump to the relevant section:
Introduction
Custom models behave as first-class data in Planhat, so a Salesforce object that does not correspond to a system model, a custom object, or a standard object like Order or Asset, can be synced directly into a custom model that mirrors it, rather than routed through a warehouse first.
The integration treats a custom model like any other model: you pick the Salesforce object to sync, choose the keyable that matches records between the two systems, and map fields. Associations to other models, and additional source objects, are set up as ordinary field mappings, so a single model can sync from more than one Salesforce object and keep its relationships in sync.
This article covers setting up that sync. For creating the model and its keyable first, see [Creating and managing custom models] and [Custom keyables].
Before you start
Create the custom model and grant role access. A new custom model is hidden until a role is given access to it, so grant access before you try to map it. See [Creating and managing custom models].
Create the custom keyable you will sync on. A custom model cannot sync with Salesforce without a keyable to hold the Salesforce record Id. See [Custom keyables].
Check the Salesforce connection is active. The Planhat to Salesforce connection can disconnect quietly; reconnect it before you start mapping.
Sync a Salesforce Object into a Custom Model
On the mapping screen, a model's main keyable (the field records are matched on) is shown separately from its associations to other models, so it is clear which mapping matches records and which builds relationships.
Select the Planhat model and the Salesforce object to sync.
Select the Planhat model's keyable, the custom keyable you created to hold the Salesforce record Id. This is the field records are matched (upserted) on. (Unlike a system model, a custom model has no
sourceId, so you match on a keyable you defined.)Set up field mappings for the associations you want to sync (see Mapping associations).
Set up field mappings for the model's normal fields.
Screenshot: the mapping screen, with the main keyable selected and field mappings below.
Mapping Associations
An association is mapped like any other field, in the field-mapping section. You add one mapping per association field, so a model can sync as many associations as it has association fields.
For each association, you specify which field on the associated model stores its Salesforce Id. For system models this defaults to sourceId, but you can point it at a different keyable. This is what lets Salesforce relationships resolve to the right Planhat records on both sides.
Screenshot: an association field mapping, showing the associated model and the keyable that holds its Salesforce Id.
Syncing Multiple Salesforce Objects into one Planhat Model
You can sync more than one Salesforce object into a single custom model. For example, sync a Salesforce Task into a Planhat Tasks model, and also sync Task Feed records into the same model so they add data to Tasks that already exist.
Each source object is set up as its own set of field mappings:
Sync the main object (
Task) usingsourceIdas the keyable.Sync the additional object (
Task Feed) on a keyable such asTask_feed_id, and map Planhat'ssourceIdto the additional object's parent Id (the Salesforce Task record it belongs to). The Task Feed record then adds its data to the existing Task rather than creating a new record.
Controlling Whether a Mapping Creates or only Updates Records
Require the parent to exist. Turn this on so a mapping is accepted only when a Planhat record with that Id already exists. The additional object can then update existing records but not create new ones.
Prevent creating records back in Salesforce. Add a sending filter that only sends when the keyable (for example
Task_feed_id) has a value, so Planhat does not create records in Salesforce from this mapping.
Screenshot: two source objects mapped into one model, with the "require parent to exist" toggle.
How the Association Keyable is Chosen
When you set up an association mapping, Planhat suggests the keyable to sync on, in this order. You rarely need to change it:
The keyable already used for that associated model elsewhere in the mapping, if there is one.
sourceId, if the associated model has it.An existing custom keyable on the associated model.
Keyables and Associations
These two do related but different jobs, and the mapping screen keeps them separate:
A keyable stores an external (Salesforce) Id and is used to match records during sync.
An association stores a Planhat Id and records a relationship between two models.
You map an association on a keyable: the keyable resolves the Salesforce Id to a Planhat record, and the association then holds the relationship to it. See [Custom keyables] and [Custom associations].
Using Formula Fields in Mappings
Formula fields can be used in Salesforce mappings, which can simplify a mapping by deriving the value to send or match on rather than storing it in a separate field. See [Formula fields].