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 2018 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 three Custom Entities:  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 Required Privileges

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.

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 HubSpot 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 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.  This means your CRM Audit logs may increase in size significantly over time depending on system activity.

Record Creation 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 three custom entities we designed, as we consider CRM to be your System Of Record.

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 recommend having all HubSpot data that will sync to CRM be copied into one of our custom CRM entities.

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.  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 2018 User Acceptance Testing Overview document