In order to establish a successful sync between ClientSuccess and your external systems, it's important to understand how the technology powering the sync functions.

For the sake of understanding, the term "Push" will always refer to updates being made in ClientSuccess, and pushing out to an external system. Whereas "Pull" will refer to updates made in an external system, and being pulled into ClientSuccess.

While it is all housed under one integration, the push and pull operations differ in a few ways. In all cases, it's critical to understand how this process works, to prevent any potential data loss from the two systems overwriting each other in an unintended way.

This article covers the following topics:

1. ClientSuccess to External System - Push
2. External System to ClientSuccess - Pull
3. Data Parity
4. Maintaining your Integration

ClientSuccess to External System - "Push"

If you have fields that are mapped to sync either bi-directionally (<->) or ClientSuccess -> *external system*, then there is potential for data to be pushed out to external systems and overwrite whatever data is present. Let's talk about how this works.

• Not all changes made to a Client or Contact in ClientSuccess will trigger a data push. Only changes to fields that have been mapped <-> or ClientSuccess -> external system will trigger a push.
• Additionally, only fields that are mapped accordingly, and have been updated will push upon saving your updates.
  • For example, the screenshot above is looking at mappings for a Client object. All four of the address fields are set to sync <->, you make a change only to the "Address - City" field, and save your Client Record, what happens?
    • Only the "Address - City" field will push because it is both mapped <-> and a new value has been saved.
  • If I update more than one field, then save my record, will all of my updates push?
    • Any fields that are mapped <->, or ClientSuccess -> external system, and their values have been updated since the last record save, will push. You could change 15 Client fields, then save, and any that meet the above criteria will push to the external system.

External System to ClientSuccess - "Pull"

If you have fields that are mapped to sync either bi-directionally (<->) or external system -> ClientSuccess, then we can pull data in from your external systems, and overwrite the data in ClientSuccess.

Where the ClientSuccess -> external system push is based on triggers, i.e. changes made in ClientSuccess push over to the external system immediately after saving updates, the external system -> ClientSuccess pull data flow works differently.

Polling

Instead of constantly pinging your external system, looking for changes to be made (which results in excessive API call traffic), alternatively we've configured the external system -> ClientSuccess pull to work around a "Poll" process.

At regular intervals, the integration will scan your external system and look for any updates that have been made since the last poll ran. While most customers set their Poll Schedule to run every 15 minutes, you have control over your poll frequency.

For example, let's say your poll last ran at 11:30am, and your polling frequency is set to run every 15 minutes. You make an update in your external system to a field that is set to pull into ClientSuccess, your update will pull into ClientSuccess at 11:45am.

Next, let's look at visual of the external system -> ClientSuccess workflow, with an explanation of the workflow down below:

Key Difference Between The Push & Pull Functionalities

The ClientSuccess -> external system sync operates as a trigger based, field-to-field level sync (i.e. if you have 5 fields mapped to push from ClientSuccess to your external system, you update one of those fields, only the field that changed pushes to the external system).

The external system -> ClientSuccess pull is not considering which field in an external system record has been updated. ClientSuccess is simply going to note that an update to the record (Account, Contact etc.) has been made, and pull in ALL values for fields mapped <-> or external system -> ClientSuccess.

Let's use the image below as an example. We have 5 address fields that have been mapped. Three are <->, one is mapped external system (in this case, HubSpot) -> ClientSuccess, and one is ClientSuccess -> HubSpot.

If a change is made to the "Address - Street" field in ClientSuccess, because that field is mapped ClientSuccess -> HubSpot that change will push to HubSpot immediately, overwriting whatever value is in the HubSpot field named "Street Address".

If a change is made to any of the other 4 fields, then the next time the external system -> ClientSuccess poll runs, the values of all 4 fields will be pulled into ClientSuccess, overwriting the Address - City, Address - Country, Address - Postal Code and Address - State/Province values in ClientSuccess.

How are blank, or "null" values handled in the external system -> ClientSuccess sync?

Continuing on using the above example, let's say all 4 fields are blank in HubSpot, and then you add the value to just one of the fields, the "City" field. The next time the external system -> ClientSuccess poll runs, it will pull in the new City field value, and it will then pull in blank values for the other 3 fields. Even if there are values present in ClientSuccess already. 

This brings us to our next, equally critical topic, data parity.

Data Parity

Data parity refers to ensuring that the data in ClientSuccess, and the data in your external system matches up, prior to enabling your sync. It's not necessary in all cases, so let's talk about when this is important. This will not apply to new customers who are starting with a fresh instance of ClientSuccess.

The purpose behind data parity is to prevent the accidental overwriting of data in either system. Let's look at an example:

Let's say you have a mapping setup to sync bi-directionally, between your ClientSuccess Client Name, and your customer name in an external system. In ClientSuccess your Client is named "Google", and in the external system it's named "Google West".

One of these has to be correct, but which one is it? The sync doesn't have a magical way of knowing the answer to that. So what's going to happen is, whichever name is changed first, will push into the opposing system and overwrite the value there. Potentially overwriting the correct value, with the incorrect one, depending on which one is updated first.

To avoid this, it's important that the values are brought into parity before the sync is turned on. This can be done by either exporting your data from ClientSuccess > Importing into your external system, or doing the opposite, and importing external system data into ClientSuccess.

Alternatively, we also have a new "Sync Tool" that is available for use upon request. See this article (coming soon) for more details.

What if I don't use bi-directional sync, and only have one "source of truth" for my data?

This is the simplest type of sync to setup. If your sync direction is setup external system -> ClientSuccess, then you can use our Import functionality, which will simply pull in all of your external system values and overwrite your ClientSuccess fields for those fields that you've mapped.

If your sync is setup ClientSuccess -> external system, then you will want to export your data from ClientSuccess > Import it into your external system, then turn the sync on.

Is there a way to see what's going to happen before we turn the sync on?

We've built a tool we call the "Preview Report". This report will take the fields you have mapped and the Resource Filter you've set, show you what the values for these fields are in both ClientSuccess and your external system, and then show you which system would most likely be updated.

We strongly recommend utilizing the Preview Report before ever enabling a sync.

Maintaining your Integration

There are a number of proactive steps you can take to ensure the data integration continues to work as expected. These steps will help ensure that you prevent data syncing issues and can quickly resolve any issues that occur.

1. Regularly spot-check your data in ClientSuccess to ensure records are coming over from your external systems as expected.  This is the best way to discover any issues with your sync filter criteria within the external system.  
   This does not have to be a manual process.  Leverage ClientSuccess alerts, reports, and communication platform integrations to provide proactive notifications. 
2. Regularly review summary reports to ensure the data matches what you expect. For example, 
   1. Use the Overview report to ensure you have the right number of Clients with the correct client type. 
   2. Use the Revenue report to check on any overdue subscriptions. 
3.  Monitor the Integration settings and Integration history for any sync errors.  You will see a red "!" icon on the Integration settings screen if there have been any recent errors.  The Integration history will show you the relevant error message.
4. Share these integration knowledgebase articles with your Technical Integrations team.  Make sure they understand that future changes to your external system could impact your data in ClientSuccess.

Please reach out to your assigned CSM, or support@clientsuccess.com with any questions.