Summary
In Planhat, planned (future) activities are Tasks, and logged (past) activities are Conversations. When a Task is completed, the default behaviour is to "log a note" (create a Conversation)
In Salesforce, both planned and logged activities are Tasks
You can sync Tasks between Salesforce and Planhat
It's possible to sync Task types between the two
The integration can automatically create a Conversation in Planhat when a completed Task is synced from Salesforce
The "Note" part of the integration can sync Conversations from Planhat to Salesforce, and either "Legacy Notes" (Note object) or "Content Notes" (ContentNote object) from Salesforce to Planhat
Not all Notes, or all changes to Notes, are included in the sync - if you'd like to learn more, read on!
Who is this article for?
It's mainly for Planhat builders (e.g. CS Ops) setting up the Salesforce integration ...
... but it can be useful for any Planhat user who'd like to learn more about syncing Tasks and Notes via the Salesforce integration
Series
We have a series of articles on the Salesforce integration:
Tasks and Notes in the Salesforce integration ⬅️ You are here
Article contents
Introduction
This is a technical deep-dive article
Read on if you'd like to explore the details of Notes and Tasks in the Salesforce integration.
If you'd just like an overview of the Salesforce integration, please refer to our main article.
Planhat's Salesforce integration includes standard sections for syncing Tasks and Notes.
This article takes a deeper dive into these topics, looking at the relationship between Tasks and Notes in Planhat, the differences in data structure between Planhat and Salesforce, the different objects/models involved, Task types, which Notes are synced and when, and more!
Ready to become an expert in syncing Tasks and Notes? Let's get started!
Planned and logged activities in Planhat
In the Salesforce integration, you'll see separate sections for syncing Tasks and Notes. But in Planhat, these models are actually connected, rather than independent as you might expect. It's important you understand the relationship between the two.
In Planhat, data on activities (such as calls and meetings) is saved on two different data models.
"Planned activities" - activities due to happen in the future (e.g. a QBR scheduled for a week's time)
The Planhat model for this is the Task model
Tasks have a "mainType" property, which is either "task" or "event"
The default when you create tasks in Planhat is that these are of type "task"
"Events" are most commonly synced in from other integrations (e.g. Google Calendar), although you can also create them manually within Planhat
Tasks also have a "type" property, which corresponds to an optional custom "Conversation Type" (e.g. "Training Session") that you can apply to a Task, and can be associated with a Salesforce subtype/type (more on this later)
The outcome of a completed Task can either be "Done" or "Ignored", and when set to either of these, the Task will automatically be archived (which generally means it's hidden from the UI in Planhat, although you can still see it in Workflows)
"Logged activities" - activities that have already happened (e.g. an account set-up Task you completed today)
The Planhat model for this is the Conversation model (although this is sometimes referred to as Note)
Conversations have a single "type" property
There are some standard types - "note" (the default type), "ticket", "chat", "email" and "call" (all lower case) - other than "note", these standard types represent Conversations associated with integrations, e.g. Intercom chats
Alternatively, they can be associated with a custom Conversation Type (which may be a Salesforce subtype), such as "Call" (upper case) or "Success Alignment"
In Planhat, when you manually mark a Task - a planned activity - as "Done":
as well as that Task record being updated and archived,
you can "log a note", which actually means create a Conversation record associated with that Task, which could either be a "note" (if no custom Conversation Type is specified), or otherwise it could be a custom Conversation Type
Although you can choose to not "Log a note" / create a Conversation, the default behaviour is that this happens
Information from the original Task is automatically included in the new Conversation, although you can edit this
If a custom Conversation Type was set in the Task, it will come through to the respective Conversation
For more information, you can refer to this article about Task management in Planhat (including the difference between Tasks and Notes), and this article about Task status (including the options for logging or not "logging a note" on Task completion).
Tasks in Salesforce
In contrast to what you've just learned about Planhat, in Salesforce ...
Both planned (open) and logged (completed) activities are associated with the Task object in Salesforce
The only difference between them is the part of the UI where they are shown
The Task object has two standard fields related to type: "TaskSubtype" and "Type"
"TaskSubtype" provides standard categories for your Tasks. The main picklist values are:
"Task" - a standard Task (a to-do)
"Email" - in Salesforce, you can send emails from the Account, which are saved on the Task object as completed Tasks with this subtype
"Call" - you can manually log calls in Salesforce, which are saved on the Task object as completed Tasks with this subtype
📌 Important to note - events
It should be noted that there is also a separate Event object in Salesforce. The standard "Task" section of the Planhat Salesforce integration does not sync records of the Event object, only the Task object
It is possible to set up a custom section of the integration if you would like to sync with the Salesforce Event object
When it comes to Planhat Tasks with "mainType: event", these are still saved on the Task object in Planhat
For those created manually in Planhat, these would be included in the standard Task sync, and sync to the Task object in Salesforce
Events in Planhat created from third-party integrations (Google Calendar or Outlook), are not be included in the sync
Introduction to the Task sync
In the Salesforce integration, there is a default section that links the Task model in Planhat to the Task object in Salesforce. This can sync new Tasks, and Task updates, in both directions. Note that Tasks are only included in the sync if they are associated with an Account/Company being synced.
One of the really cool features of the Task default section is that it has the built-in functionality to automatically create a new Conversation (also known as a Note or a logged activity) when a completed Task is synced from Salesforce to Planhat (whether that Task is new to Planhat or is a Task update being synced into Planhat). The new Conversation is populated with details of the Task. This Conversation creation mimics the default action of manually completing a Task in Planhat. The completed Task is also archived in Planhat as usual.
Once this Conversation (logged activity) is created in Planhat, any update on the Salesforce Task will not affect it. Also, any update on the Planhat Conversation will not be synced to Salesforce (either to the associated Task or as a new Note). More on syncing Notes later in this article.
Be aware that if you were to set up a Task sync using one of the extended mapping sections at the bottom of the integration rather than the default Task section, the extra built-in functionality to create the Conversation (logged activity) would not be included.
Task types
Let's take a deep dive into Task types, and how the type of a Task can sync.
Planhat custom Conversation Types
The integration has an special feature to sync Planhat custom Conversation Types, which as we mentioned earlier, are saved in the "type" property of the Planhat Task model. You can create your own selection of custom Conversation types in Planhat, such as "QBR", "Training Session", "Executive Alignment", "Kick-off Call", "Sales Handover" and so on.
When a Task in Planhat with a custom Conversation Type is synced to Salesforce, the name of the custom Conversation Type is automatically added at the beginning of the subject in Salesforce - for example, "[QBR] Subject of the Task". Then, when the Task is synced back to Planhat, the integration will recognise the Conversation Type from the "[QBR]" (or equivalent) string.
If you create the Task in Salesforce, you can manually add the "[QBR]" etc. to the subject, so the Task is created with the correct Conversation Type when synced to Planhat. (You should create the Conversation Type in Planhat yourself first, as the integration does not create Conversation Types.)
As discussed earlier in this article, when a Task completion is synced into Planhat, the default Task part of the integration will archive the Task and create an associated Conversation (i.e. logged activity / Note), using details from the Task. This includes any custom Conversation Type on the Task, which will be inherited by the associated Conversation (as long as the Conversation Type has already been manually created in Planhat).
Salesforce Task types
As we mentioned earlier, there are actually two properties on the Salesforce Task object related to type: "TaskSubtype" and "Type".
As default, the Planhat Salesforce integration looks at the "TaskSubtype" property. There are 3 main default picklist values for this: "Task", "Email" and "Call". These types can be synced into Planhat via the integration.
When considering these Salesforce Task subtypes, it's important to note that Salesforce Tasks are planned activities ("to do"), whereas Emails and Calls are logged activities ("have done"). This affects what happens to them once they are synced into Planhat.
Let's take a look at what happens when Tasks with each of these Salesforce subtypes is synced into Planhat:
Task with "Task" Salesforce subtype
The Task is created in Planhat as an open/unarchived Task, type "Task"
Task with "Email" or "Call" Salesforce subtype
The Task is created in Planhat as completed/archived, AND given type "Email" or "Call" as appropriate
This type will only be visible if you have added it (capitalised correctly) as a custom Conversation Type in Planhat
ALSO, as usual with completed Tasks, an associated Conversation (logged activity) is automatically created in Planhat
If you have added the type ("Email" or "Call") as a custom Conversation Type in Planhat, this type will be applied to the Conversation (logged activity)
However, if you haven't added the type as a custom Conversation Type, when the Conversation (logged activity) is created, it will be given the default Conversation Type of "note"
📌 Important to note - creating Conversation Types for Salesforce subtypes
In Planhat, you should create custom Conversation Types for the Salesforce subtypes "Email" and "Call" (both uppercase, as the lowercase equivalents are counted as different Conversation Types), if you will be syncing these completed Tasks into Planhat.
This is so the type is shown on the Task in the UI in Planhat, and so it is brought through to the associated Conversation (logged activity).
📌 Important to note - syncing emails
When considering whether emails will be synced between Salesforce and Planhat, it's important to note that emails must meet particular properties to be synced.
If emails in Salesforce are stored on the Task object (with subtype "Email" as described above), they can be synced into Planhat as a completed Task, with an associate Conversation (Note) record being automatically created as previously described.
You may hear these emails referred to as "default emails"; they can be sent in Salesforce without another integration.
Occasionally, it may be that a third-party integration connected to Salesforce imports emails into Salesforce on the Task object as this default "Email" subtype, and in that case, they would also be synced into Planhat as completed Tasks (and then Conversations) as described above.
However, most of the time when a third-party integration syncs emails into Salesforce, the setup is different and they are saved on a different object etc.; in which case, they would not be synced into Planhat as a Task.
Considering the other sync direction, emails saved in Planhat (which are Conversations with type "email", associated with the Gmail or Outlook integrations) are not synced to Salesforce.
Syncing types from Salesforce
Okay, so let's bring that knowledge together and confirm what type a Task synced into Planhat will have.
You may be wondering, is it possible for a Task in Planhat to have both a Planhat custom Conversation Type (e.g. "Training") and also a Salesforce subtype (e.g. "Call")? The answer is no, because there is only one "type" field on the Task model in Planhat, and it can only take one value.
This is the automatic process assigning the "type" property when a Task is synced from Salesforce to Planhat:
Is there a type in the subject (e.g. "[QBR]")?
If yes, that is the "type" of the Planhat Task
If no, continue to next step ...
Is there a value in the "TaskSubtype" field (e.g. "Email")?
If yes, use that as the "type" of the Task
If you've added this as a custom Conversation Type in Planhat, it will show in the UI; if not, it won't display in the UI, but will be saved "behind the scenes" in the Planhat database
If no, then assign the default type "Task"
Optionally, you can set up custom field mapping in the Task section of the integration, which would overwrite this default behaviour. This means you can map the "Type" field (attribute) on the Planhat side to your choice of field on the Salesforce side, such as "Type" (rather than "Task Subtype"). If a Task is then synced from Salesforce to Planhat and the selected Salesforce field (e.g. "Type") is blank/null, the Task in Planhat will be assigned the default "Task" type.
Syncing types to Salesforce
When syncing a Task from Planhat to Salesforce, you've already learned about how a custom Conversation Type would be added to the subject in square brackets.
In addition to this, the "TaskSubtype" field in Salesforce can be populated by the Planhat integration. It looks to see whether the "type" in Planhat is "Email" or "Call" (case sensitive), and if it is, this value is sent to Salesforce. If it's a different type, then it's given the TaskSubtype of "Task" as default.
Optionally, you can potentially set up custom field mapping in the Task section of the integration, as an alternative to this default behaviour.
Note sync
There are two main points to be aware of when considering what's synced in the Note part of the integration: which model/object/types are included in the sync, and what updates are (or aren't) synced.
Model/object/type synced
Planhat to Salesforce
On the Planhat side, although the Note section of the integration has "Note" selected, it actually syncs the Conversation model ("logged activities"), and not just Conversations of type "note" - it can potentially be any type, such as "QBR" or "Training" or "Sales Handover" etc. custom Conversation Types.
However, Conversations with standard types other than "note" ("ticket", "chat", "email" or "call") are not included in the Salesforce sync, because they are associated with other integrations (e.g. Zendesk, Intercom or Gmail).
Also, Conversations created automatically by the Task part of the integration (as discussed above), which could potentially be type "note", "Email" or "Call", would not be included in the sync - see the next section below.
Salesforce to Planhat
On the Salesforce side, in the integration you choose to select either "Legacy Notes" or "Note Taking Tool". They are different than the Planhat concept of notes as typically "logged activities".
Legacy Notes:
These are "old notes"; this is the Note object in Salesforce
They are displayed in the Section "Notes & Attachments" in Salesforce
They are simple text
These notes do not have a "Text Preview" field
Note Taking Tool
These are "new notes"; this is the ContentNote object in Salesforce
They are displayed in the "Note" section in Salesforce
They support HTML format
They have the "Text Preview" field
Whichever you pick, when these Notes are synced into Planhat, they will become Conversations of type "note". The title of the Note in Salesforce is automatically synced to the subject of the corresponding Conversation in Planhat.
Only Notes associated with Accounts can be synced from Salesforce to Planhat in the Note part of the integration - this is so they are associated with Companies in Planhat (which is at the top of the Planhat data model structure).
Are created or updated Notes/Conversations synced?
Compared to other model/object pairs (sections) in the integration, Notes are a special case, in that not all updates are included in the sync.
Notes created in Salesforce
For Notes created in Salesforce, created and updated Notes will be synced into Planhat (as Conversations of type "note").
However, any updates made in Planhat on those Notes are not synced to Salesforce.
Conversations/Notes created in Planhat outside of the integration
For Conversations/Notes ("logged activities") created in Planhat - this is manually created in Planhat rather than created by the integration:
Only new Notes will be synced into Salesforce, and "[PLANHAT]" will be added to the subject in Salesforce
After they have been synced to Salesforce, there will be no updates synced in either direction
Updates to these Notes in Planhat will not be synced to Salesforce
Updates to these Notes in Salesforce will also not be synced to Planhat
Conversations/Notes created in Planhat by the integration (after syncing in a completed Task)
Conversations (logged activities) created in Planhat automatically by the Salesforce integration (in response to a completed Task being synced in from Salesforce) are not included in the sync:
Updates made on the associated Task in Salesforce will not update the Conversation (logged activity) in Planhat
Updates made to the Conversation (logged activity) in Planhat won't sync to the associated Task in Salesforce or a create a new Note in Salesforce
It's by design that a new Note is not created in Salesforce for the Conversation, because the completed Task is still visible in Salesforce, so this would just duplicate the information. It's a different situation than in Planhat, where completed Tasks are archived (and so hidden), so generally only the Conversation would be visible