Purpose


This document will serve as a selection of guidelines and advice of which we'd like you to be aware before, during and after your integration is implemented.  It is based on industry standards and our own extensive experience in the field of systems integration, and discusses topics ranging from conceptual design to User Acceptance Testing.  We have condensed these topics into informational "bites" as much as possible, but we consider this to be critical reading for you to understand what can happen with your data (good or bad).



Baseline Sync Logic


The overall baseline logic for the CRM 2019 Solution is depicted in the following Flowchart.  Features added onto the Solution, including new record types, field mappings, or overall logic changes are considered custom development.



Dynamics CRM Solution file


We will provide you with a custom CRM Solution file (Zip format) which we ask that you install in the CRM environments where we will integrate.  We can provide this Solution as either "Managed" or "Unmanaged", depending on client needs.  We usually recommend Unmanaged so that further customization can be easily performed.


We recommend that you first install the Solution in a Development or Test environment to be certain of the results.  This Solution file does the following:

  1. Adds several Custom Entities, including these featured types:  HubSpot Profile, HubSpot Email Event, and HubSpot Form Submission
  2. Adds one new "Integration User" Security Role that contains the minimum permissions we require to integrate with your CRM system
  3. On Leads and Contacts, adds new Lookup fields, and adds new Sections to the default Lead and Contact Forms to showcase HubSpot IFRAMEs and relationship information
  4. Adds new tracking fields to User, Account and Opportunity entities


NOTE: In general our CRM Solution file has not been found to cause issues with most environments.  However, since our CRM Solution does include Core Entities, if you have a highly customized environment, you should consider the following steps:

  1. Create a new CRM Solution and include all of your existing customizations
  2. Export this file to a safe place
  3. Install our Unmanaged CRM Solution
  4. Re-import your saved CRM Solution file

Failure to do so may result in some settings or customizations being lost, such as Ribbon customizations, default Form changes, and possibly other General Settings such as Auditing.  We do all that we can to obviate these risks, but we are limited by how CRM processes imported customizations.



CRM Integration User and Required Privileges


To keep your integration secure and functional, we recommend creating and providing to us a single CRM User login which will be 100% dedicated to the integration.  This will also prevent any confusion when later reviewing record changes and their order of operations.


Included with the CRM Solution is a Security Role called "Integration User".  We recommend providing our CRM User with only this Security Role, which has been preconfigured to provide the minimum privileges to allow the default integration to process, and to allow for basic troubleshooting needs.  Please review this Security Role and contact your assigned developer with any questions.


Note that this Security Role may need to be given additional privileges in the case of custom sync logic requests.



Time Zones


We will need to set our CRM Integration User's Time Zone to match the Time Zone set in the client's HubSpot Org (or client will need to set, if our User will not have GUI access).  This is to ensure that any date transformations we do in the integration have the correct appearance.  In addition if these values do not match, there may be issues with timing in your synchronization, as we typically use the last date/time a record was modified to determine if it should sync again.  Ideally, your HubSpot default time zone and the time zone of the CRM integration User should match as well.



General CRM Privileges


We recommend strongly that all normal CRM Users other than Admins and our own Integration User only have "Read" permissions to the custom CRM entities.  These entities are meant to be one-way storage repositories for data syncing from HubSpot to CRM and may only cause confusion if they are able to be edited in CRM.



CRM Navigation


Our new custom entities in CRM (HubSpot Profile, Email Event and Form Submission) will not appear in the CRM Navigation menu by default.  We avoid attempting to set this as it can also overwrite client navigation settings.  If you would like these new record types to be generally visible in CRM, you will need to add them to the appropriate Navigation Area (i.e. Sales, Marketing, etc) under the entities' General Settings.  We recommend making them visible under Marketing.



CRM Auditing


Unless Auditing is enabled in CRM, and on all entities involved in the integration, our options to track record changes after the fact may be limited.  Also note that, if a field is mapped in the integration, it will necessarily always be written to with one value or another when that record is synced.  This means your CRM Audit logs may increase in size significantly over time depending on system activity.



Record Creation and Update in CRM


By default, new CRM Leads/Contacts are ONLY created when the "Create New CRM Record" checkbox is set in a HubSpot Contact.  After creating the Lead or Contact, that setting will be cleared, so only one will ever be created each time it is set in HubSpot.  We do not advocate any form of automatic CRM record creation beyond the custom entities we designed, as we consider CRM to be your System Of Record.  For the same reasons, existing CRM records are ONLY updated with HubSpot information when they are recently modified and placed on the Priority Sync Queue List, which is under your control.



Email Addresses


Any Contact or Lead in CRM that does not have a valid email address will not sync with HubSpot, and thus will not create its own CRM HubSpot Profile.  There is currently no workaround for this as HubSpot requires a unique and valid email address for each Contact that it maintains.



HubSpot Deletions


Normally, if an existing CRM HubSpot Profile for a Lead or Contact finds that it no longer matches to a HubSpot Contact, we mark the CRM HubSpot Profile as "Deleted from HubSpot", and we will not attempt to recreate the HubSpot Contact.  If the client wishes to have a new Contact created in this scenario, they will need to both detach a particular CRM Leads/Contact from the CRM HubSpot Profile, and then change the Lead/Contact's Email Address.  This will trigger a new HubSpot Contact to be created (or an existing one updated) and will also create a new CRM HubSpot Profile.



Looping and Cloning Risks


Clients should be aware that by adding fields or additional sync logic, they may create the potential for looping or cloning data.  For instance, if a City field is mapped to travel both from CRM Contact to HubSpot Contact and back, we have no way to guarantee from which direction the data will originate, as this will depend on when the field was changed and at what point the sync is processing.  Furthermore, if such a HubSpot Contact matched to multiple CRM Contacts by email, the HubSpot value could overwrite ALL City values for those CRM Contacts, depending on the logic involved.  For this and other reasons, we only allow CRM Lead and Contact data to be directly updated by HubSpot Contacts that use the Priority Sync Queue, which is placed under your control as the customer.



CRM Optionset Options


When considering deleting an existing CRM Optionset Option, please be aware of and avoid the following scenario:

1.  You created an Optionset Option

2.  At least one record was given this Option as a value

3.  You later deleted the Optionset Option before changing the field value for existing records to another value

Unfortunately this results in CRM removing the text value and the association through CRM's user interface, but the internal integer value actually remains on the record in the database.  Thus when we pull your data programmatically, this will cause an invalid match and a failed record sync.


To prevent the above happening, please be sure to update all records so that they have a new valid Option in any such field, BEFORE deleting the existing Option.  This is also good practice when working with HubSpot Dropdown data.  Even though this requires extra work and bulk changes, resolving after the damage has been done is much more challenging.



Sample UAT Guidelines


For clients who do not utilize a full UAT department or service, we can offer basic information and guidelines you may use to validate behavior of the integration.  After a Lyntonweb developer has mapped a field to copy over in a given circumstance, it will be the client's responsibility to ensure the mapping is operating as they intended (after which the client will mark the relevant fields "Tested" in the other sheets of this workbook).


Note that it is best practice to have more than one person in your organization perform the same set of tests with different data, in order to form a consensus.

Please reference our 2019 User Acceptance Testing Overview document