Open

The HubSpot for Sugar integration creates a bidirectional sync that offers the flexibility to produce and analyze your most dynamic campaigns and keep your records clean and up-to-date. By having access to all the advantages that both systems have to offer, you’ll gain insight into specific campaigns within HubSpot, as well as access to a contact or lead’s HubSpot activity within their record in Sugar.

About this guide

This guide covers all areas of the Faye Sugar-Hubspot integration that relate to set up and general administration of the integration. It is intended to be used by the CRM or Hubspot admin responsible for setting up or managing the integration between the two systems.

You may also be interested in our Sugar-Hubspot User Guide for information on how Sales and Marketing users within your organisation can leverage the benefits of the integration while working within Sugar.

Before you get started

In order to complete the set up of your Sugar-Hubspot integration you’ll need to have the following:

• Admin level login info for the target SugarCRM

• A login for the target Hubspot account

• An admin level login for the Faye Hubspot Bridge

• Hubspot integration plugin for Sugar (zip file)

Configuration of your integration will require changes in both your target SugarCRM instance and the Faye Hubspot Bridge. We will cover exactly what needs to be done in each in the following sections.

SugarCRM Configuration

This section covers the changes that need to be made in the target SugarCRM instance prior to enabling the sync with Hubspot.

1. Install Hubspot integration plugin for Sugar

Before enabling the sync with Hubspot it is necessary to install the Hubspot integration plugin for Sugar. This module loadable package will add new fields, custom hubspot dashlets and jobs that are necessary for the sync to function with Sugar.

Follow these steps to install the Zip package to Sugar

1. Login to SugarCRM with an “admin” level user

2. Open the Administration area and find the Developer Tools section

3. Select the Module Loader

4. Press the Choose File button and select the .zip file provided to you by Faye. After you have selected the file, press the Upload button.

5. In the list of available modules to be loaded, find the item that you just uploaded. Press the Install button.

6. You will be presented information about the End User License and Readme file. After reading the License, press the Accept option followed by pressing the Commit button.

7. The installation may take up to 5 mins to complete, once you see the confirmation message return to the Administration area and find the System section

8. Here choose the Repair option and on the list of repairs that loads click the Quick Repair and Rebuild option.

9. Once the repair completes scroll to the bottom of the screen where you will see a SQL query that Sugar needs to execute.

10. Click the Execute button to execute the script and be delivered with a “complete” message

     

2. Configure Scheduled Jobs

The zip package adds 4 job routines, these need to be set up individually in the Sugar Scheduler so that they run regularly. We cover each jobs and its recommended run intervals below:

2.1. Hubspot: Add events to the Hubspot tracking table

• From the top navigation bar choose “Create Scheduler” from the Sugar Scheduler module dropdown menu

• Enter details of the scheduled job as below:

  • Name: Hubspot: Add events to the Hubspot tracking table

  • Status: Active

  • Job: All all syncing related contact from saved account to Hubspot tracking table

  • Interval: Every 1 mins (as often as possible)

• Click Save

2.2. Hubspot: Sync records related to synced Target Lists

• From the top navigation bar choose “Create Scheduler” from the Sugar Scheduler module dropdown menu

• Enter details of the scheduled job as below:

  • Name: Hubspot: Sync records related to synced Target Lists

  • Status: Active

  • Job: Mark all records related to Prospect List to Sync to Hubspot

  • Interval: Every 1 mins (as often as possible)

• Click Save

2.3. Hubspot: Mass Update Sync To Hubspot Field

• From the top navigation bar choose “Create Scheduler” from the Sugar Scheduler module dropdown menu

• Enter details of the scheduled job as below:

  • Name: Hubspot: Mass Update Sync To Hubspot Field

  • Status: Active

  • Job: Mass Update Sync To Hubspot Field

  • Interval: Every 1 mins (as often as possible)

• Click Save

2.4. Hubspot: Clean Old Synced Events from Tracking Table

• From the top navigation bar choose “Create Scheduler” from the Sugar Scheduler module dropdown menu

• Enter details of the scheduled job as below:

  • Name: Hubspot: Clean Old Synced Events from Tracking Table

  • Status: Active

  • Job: Clean Old Synced Tracked Events for Hubspot Integration form Hubspot Tracking Events Table

  • Interval: Every 1 mins (as often as possible)

• Click Save

3. Add Hubspot fields to module layouts (optional)

The Hubspot plugin adds a number of fields to the Accounts, Contacts, Leads and Target list modules. Some of those fields are only required for storing background information for the sync however you may wish to display some of the fields on record, list or search layouts.

Accounts:

Consider adding the following fields to Account layouts:

• Sync to Hubspot ← This field will confirm if the record has been synced with Hubspot or not. Checking the box will flag the record to be synced to Hubspot on the next sync run.

Contacts and/or Leads:

Consider adding the following fields to Contact or Lead layouts:

• Sync to Hubspot ← This field will confirm if the record has been synced with Hubspot or not. Checking the box will flag the record to be synced to Hubspot on the next sync run.

• Hubspot Score ← this field will display the Hubspot score for records that have been synced. Consider adding this to the Record, List and Search layouts.

• User must be logged into Hubspot to view iFrame below ← this iFrame field will allows users who are logged into Hubspot to access the corresponding Hubspot contact from the Sugar Contact layout. Add this to the Contact Record layout.

Target Lists:

If you plan on syncing Sugar Target lists to Hubspot we recommend adding the following field to Target List layouts:

• Sync to Hubspot ← This field will confirm if the Target List has been synced with Hubspot or not. Checking the box will flag the Target List to be synced to Hubspot on the next sync run. Doing this will automatically flag all Contacts, Leads and Accounts associated to the Target list to sync to Hubspot also.

For now All configuration steps required in SugarCRM are complete so you can move on to configuring the Hubspot Bridge.

Hubspot Bridge

This section covers the everything you need to know about working within the Faye Hubspot bridge. We begin by covering general navigation of the Bridge and then explore each section of the platform separately.

What is the Hubspot Bridge?

The Faye Hubspot-Sugar integration is the application that manages the synchronization of data between SugarCRM and Hubspot.

Open

When setting up the synchronization between Hubspot and SugarCRM all of the configuration and management is handled within the Hubspot Bridge including.

• Authentication to Sugar and Hubspot

• Sync direction

• Contact & account resolution

• Field mapping

• Statistics & logging

Naturally then as an administrator it is important you have an understanding of the configuration options available for the integration, how to monitor the sync and how to address issues should they arise.

Navigating the Bridge

Once logged into the Hubspot bridge you’ll arrive on the Dashboard screen. Below we’ll introduce some of major sections of the application.

1. Links: The expandable Links section of the left side menu provides you with shortcuts to login directly to the SugarCRM or Hubspot instances that are configured.

2. Menu Options: Here you can switch between different areas of the Hubspot Bridge accessing the Dashboard, Field Mapping, Integration Logs and other useful information. Menu options may differ between Super and Regular admin user accounts.

3. Main Panel: The main panel will change to provide a contextual workspace depending on the area of the bridge are accessing, the screenshot above shows a section of the dashboard. Each section will be covered in detail later in this guide.

Dashboard

The dashboard provides you with a visual overview of sync activity across the past 30 days in either direction in addition to daily sync stats for the past 15 days. It allows you to quickly see the current state of the integration and identify any issues that might require your attention. It also provides shortcuts to mark Sugar records to sync on mass to Hubspot.

Last 30 Days

These graphics allow you to see at a glance how many records have synchronized in either direction in the past 30 days. The red sections of the graphic represent records that have not yet successfully synced to the CRM or Hubspot. These might represent an issue that needs your attention or simply that records are currently in the process of syncing.

Mass Flag Sugar records to Sync

In order for a Sugar record to sync downstream to Hubspot it must have its “Sync to Hubspot” field checked off. This allows administrators and users to be selective in which Contacts, Leads and Accounts find their way into Hubspot.

The buttons provided on the dashboard allow you to check the “Sync to Hubspot” checkbox on all records of that kind from within the bridge so you don’t have to update those manually in Sugar.

Integration Stats For Last 15 days

Daily statistics for the past 15 days are also displayed on the dashboard allowing you to see, by day, how many records or each kind have synced in each direction. Any high level errors will also appear here also.

Integrations

The Integrations section is where the high level synchronization settings like sync direction configured for the sync, it is also where admins set up and authenticate the connections into SugarCRM and Hubspot.

The Integrations section is typically configured for you by your implementation partner who will work with you to gather the necessary details.

1. Connection Settings:

   1. License Key: This key is provided by a member of the Faye team.

   2. License Information: Displays information relating to the License key you currently have listed.

   3. Hubspot API Key: This needs to be provided from the target Hubspot account that will be integrated with SugarCRM. Needed for the integration to connect to and authentication with Hubspot.

   4. SugarCRM Instance URL: The web address of the target SugarCRM instance that will be integrated with Hubspot.

   5. SugarCRM Username: Username of an admin level user in the target SugarCRM

   6. SugarCRM Password: Password of that same admin level user in the target SugarCRM

   7. Synchronization Frequency: Set here the frequency that the Hubspot bridge should attempt to synchronize for changes. We recommend every 10 or 30 mins, the option of “every minute” should be reserved for testing purposes.

   8. Last Synchronized At: Shows the date and timestamp of the time the Hubspot bridge attempted to run the synchronization.

2. Synchronization Settings:

   1. Synchronize Accounts: Check this box if you wish to synchronise accounts (companies) between the two systems. Checking this option will provide additional selection choices:

      1. Sync Direction: Choose your sync preference for Accounts/Companies records.

         1. Bi-directional

         2. SugarCRM To Hubspot Only

         3. Hubspot To SugarCRM Only

      2. Master System:

         1. Hubspot

         2. SugarCRM

   2. Synchronize Leads and Contacts: Check this box if you wish to synchronise Leads and Contacts between the two systems. Checking this option will provide additional selection choices:

      1. Sync Direction: Choose your sync preference for Accounts/Companies records.

         1. Bi-directional

         2. SugarCRM To Hubspot Only

         3. Hubspot To SugarCRM Only

      2. Master System:

         1. Hubspot

         2. SugarCRM

      3. Sync Hubspot Contacts to Sugar: When hubspot contacts are synced to Sugar the bridge will attempt to match them to existing records in the Leads or Contacts module in Sugar depending on your selection here. If no match is found it will create a record of that type.

         1. Leads

         2. Contacts

      4. Hubspot Contact Lists: Check this if you plan to synchronize Sugar Target lists one way to Hubspot.

3. User Settings:

   1. User Timezone: Select here your time zone preference for when looking at timestamps int he Hubspot Bridge dashboard and logs.

At the bottom of the Integrations screen you’ll find the Connection Status buttons. These allow you to check the status of the connection with SugarCRM and Hubspot.

• SugarCRM Button - Clicking this will verify that the Hubspot bridge is able to connect and authenticate with the target SugarCRM instance using the CRM details entered.

• Hubspot Button - Clicking this will verify that the Hubspot bridge is able to connect and authenticate with the target Hubspot instance using the Hubspot API key.

Save the Configuration

Once you are done configuring the settings in the Integrations area remember to click SAVE to apply the changes.

IMPORTANT: Saving the integration settings with the connections and synchronization settings enables will start the sync between the two systems immediately.

What happens when the sync starts?

Which records sync? The Hubspot Bridge will begin to synchronise records in the configured directions the next time eligible records are modified, i.e.

• Sugar Contact records flagged to “Sync to Hubspot” that are modified in Sugar after the settings were saved.

• Any Hubspot Contact modified in Hubspot after the settings were saved.

If you choose to

New Properties added in Hubspot. When the synchronisation begins for the first time some new properties are added to Contacts and Company records in Hubspot. These properties are used to store information about the Hubspot records corresponding Sugar record pairing. You will typically see these new fields when selecting the “View all properties” option on records in Hubspot toward the bottom of the list.

Field Mapping

The Faye Integration Bridge comes with a number of Predefined field mappings covering the standard fields needed to synchronize the two systems. However you can also configure your own Custom mappings between Sugar and Hubspot objects keeping in sync anything from contacts favorite football teams to Company tier ratings. Custom mappings allow you to build meaningful segments for laser focused marketing and sales efforts.

Predefined Field Mapping

The predefined field mappings cannot be modified, however you can view these to understand better which fields map as standard between Sugar and Hubspot.

• Module: The Sugar module name where the field is held

• SugarCRM Name: The name of the Sugar field considered in the mapping

• Hubspot Name: The name of the Hubspot property considered in the mapping

• Field Type: The type of field/property

• Sync To SugarCRM: Allows changes in Hubspot to update this field in Sugar

• Sync To Hubspot: Allows changes in Sugar to update this field in Hubspot

Custom Field Mapping

Custom mappings allow you to synchronise your own data points back and forth between SugarCRM and Hubspot. Once you identify the data point you wish to sync make sure there is a corresponding field on the other system.

Once you are ready to set up your custom mapping click on the + icon to create a custom mapping

• Module: Choose the Sugar module containing the field

• Field Type: Select the correct type for that field

• SugarCRM Field Name: Select the field from the list returned by Sugar.

• Hubspot Field Name: Select the property from the list returned by Hubspot.

• Sync Direction: Choose if the mapping should changes to Hubspot and/or Sugar.

  • Sync to SugarCRM

  • Sync to Hubspot

Once you have made your choices click the CREATE button to add your custom field mapping

Custom field mapping tips!

The most common reason for errors with the Sugar-Hubspot integration is misaligned custom field mappings. The Hubspot Bridge will alert users of errors and provides logs to identify and correct such issues easily but the understanding the rules below is the key to avoiding such problems in the first place.

Tip #1: Field types should match in Sugar and Hubspot:

When setting up a custom mapping the following statements should almost always be true:

1. The field exists in both SugarCRM and Hubspot

2. The field is of the same type in both systems

If however the field types differ between Sugar and Hubspot you may run into issues. As an example let's say you plan to sync the “Number of Employees” field bidirectionally, you have the following fields:

• SugarCRM: Employees_c (text)

• Hubspot: Number_of_employees (integer)

In this example a user the Sugar field will accept a text value like “over 500” however this would be rejected by Hubspot where the integer field only accepts numeric values resulting in an error in the Hubspot Bridge and a record that cannot sync.

Tip #2: Dropdown field values must match in Sugar and Hubspot:

If you plan to sync a dropdown field between the systems it is important that the values in the picklists match exactly, if they do not then you may receive errors resulting in records not syncing.

As an example lets say you have an “Industry” dropdown field in both Sugar and hubspot that you plan to sync bidirectionally with values like those in the table below:

Highlighted in the table above are are some mismatches between the two dropdown type fields that would result in errors. Let's consider some of those a little closer:

1. Transport-Logistics: in this case the picklist values are clearly different and while these may mean the same thing they will be considered invalid by the sync and result in an error.

2. Non-Profit-Non Profit: While these two values look the same there is a subtle difference between the two. Again since no exact match is found in the corresponding systems picklist the record will error.

3. Software: Here there simply is no corresponding value for “Software” in the hubspot picklist and records with this industry value will not be able to sync to Hubspot.

Logs

While the Dashboard will keep you informed of sync activity at a high level the Logs area allows you to drill down to further to inspect activity of each individual sync run and the individual records the Hubspot bridge attempted to sync.

There are three areas to explore within the Hubspot Bridge logs, we’ll cover each of those below so you can understand the information they serve up and how that information might help you identify and troubleshoot any issues.

Recent Sync Runs

The Dashboard will show you high level sync information by day but it is likely your Hubspot Bridge is configured to synchronise records various times through the day. The Recent Sync Run logs allow you to review the sync activity for the last 10 individual sync cycles.

Sync cycles are shown in chronological order with breakdowns for how many records were synced in either direction and the sync status. Let's take a look at each section of the sync run info:

Image: Shows recent sync runs for a one way sync from Hubspot to SugarCRM

• Job started at: Displays the date and time the sync cycle began

• Steps progress: Shows the steps that the sync cycle needs to process in order to complete each sync cycle. The Steps listed here may vary depending on your integrations configuration. Completed processes are indicated with a check mark symbol.

• Records statistics: The looking glass icon next to each entry allows you to drill into the specific Sync Log entries for the events processed in that section of the sync run. For example, if you see that 120 accounts were synced from Hubspot → Bridge → SugarCRM then you can drill in to see the individual sync logs for each of the 120 company records that were processed.

• Importing to bridge: Shows the number of records that were imported into the Hubspot bridge to be processed.

• Exporting from bridge: Shows the number of records the Hubspot bridge successfully exported (created or updated) in the target instance (Hubspot or Sugar)

• Status: Displays the status of the sync run. this will indicate if it Finished, Completed with errors or is in the process of Running. An info tooltip icon may provide additional info as necessary.

Sync Logs

This area provides access to the full sync logs for all records that the Hubspot bridge has processed. Here you can search within the logs for a specific record based on its Model ID or export the full sync log to csv. Let's take a look at some of the options available here and the information that is displayed.

Filter Options:

• Export all to CSV: Allows you to download the filtered list of errors (or all errors) from the Hubspot sync logs in CSV format.

• Search: the search box can be used with other filter options to further refine your search, try searching by:

  • Model ID: the Hubspot ID of a specific record, i.e. 7298

  • Module: a specific module, i.e. “Accounts” or “Contacts”

• Filters: Additionally you can select one of the available filters:

  • All modules: returns all log entries

  • Only synced: returns only those entries that were confirmed to have synced

  • Only unsynced: returns only those entries have not yet synced

  • Only failed: returns only those entries that failed to sync after various attempts

Columns:

• ID: unique ID of the sync log entry within the Hubspot Bridge

• Direction: shows the intended direction of the specific sync log entry to Sugar or to Hubspot

• Module: SugarCRM module associated with the sync log entry, i.e. Accounts, Contacts, Leads

• Model ID: Unique id of the Hubspot record associated to the sync log entry

• Synced: Status of the sync entry, i.e. Synced, Not synced

• Number of tries: Displays the number of times the Hubspot Bridge has attempted to sync the record

• Created at: Timestamp of when the hubspot bridge received the record for processing

• Updated at: Timestamp of when the hubspot bridge last processed the sync request for that record

• Errors: Displays details of why the sync event could not conclude

Integration Logs

The integration logs go deeper again than the individual sync log, these provide greater detail on the steps the Hubspot bridge is executing, be that the synchronization of individual records, authenticating with Hubspot and Sugar and/or the starting and stopping of internal processes.

Where errors exposed in the sync logs are unclear it may be useful to review the integration logs for further detail. The integration logs might also be referred to if there are issues with the general function of the integration not specific to individual records.

Support

Support for the FayeBSG Hubspot integration and Hubspot Bridge is provided by the FayeBSG support team. The FayeBSG Support team can be contacted via email at support@fayebsg.com.

Should you contact the support team with an issue or question please also include the following information that will allow us to better address your enquiry:

• Your company name

• Your Hubspot Bridge URL

• Explanation of your issue or question

For more information about FayeBSG visit our website at https://fayebsg.com

Additional Useful Information

FAQs

Q. When does the sync start running?

A. There are a few prerequisites that need to be in place before the integration can begin syncing records (below), assuming these are all in place and then the sync will begin as soon as you save the Integration settings in the Hubspot Bridge with at least Sync Setting enabled.

• SugarCRM: Hubspot integration plugin installed to SugarCRM

• Hubspot Bridge:

  • License Key set

  • Hubspot API key set

  • Sugar authentication details set

Q. What version of the Bridge I am using?

A. Once logged into the Hubspot Bridge it should be possible to see the version number at the bottom of any page.

Q. I don’t see the “Integration” option in the Hubspot Bridge menu?

A. Only super admins currently have access to the Integrations area within the Hubspot bridge, it is possible you are accessing the bridge with a regular user. If you need to check or make changes to your Integration config please contact the FayeBSG support team at support@fayebsg.com.

Q. How can I change our Integration configuration?

A. Only super admins currently have access to the Integrations area within the Hubspot bridge. If you need to check or make changes to your Integration config please contact the FayeBSG support team at support@fayebsg.com.

Q. How can I sync Opportunities between Hubspot and SugarCRM?

A. The Sugar-Hubspot integration only supports the synchronisation of Accounts, Leads, Contacts and Target lists. Synchronising other records may be possible with customisation of the Hubspot bridge, please contact your Faye Account executive or sales@fayebsg.com if you are interested in a estimate for custom work.

Q. I’m seeing “Parent account not found” errors when syncing Contacts, what does that mean?

A. When syncing a new Contact from Sugar to Hubspot information including the Contacts related Account name is passed. If you get this error it is likely because the contacts related account does not exist in Hubspot for some reason, i.e.

• The corresponding Company record may have been deleted in Hubspot

• The Contacts Account may have attempted to sync to Hubspot but failed to create there due to some error.

Q. An account is not syncing because of a “domain: "parkerindustries.net[unset]" is an invalid domain” error

A. When synchronising Sugar Account records to Hubspot the website value is passed to the Companies “domain” field. Unlike the website field in Sugar that will accept almost any text string the domain field in Hubspot expects well formatted values. In this case a “domain is invalid” error is returned because the website value being passed includes some invalid formatting on the end “parkerindustries.net[unset]".

In this example if the Sugar records website value is corrected to parkerindustries.net then it should synchronize fine the next time it tries.

Q. What happens if I delete a synced record in Hubspot?

A. The integration does not sync deletions of records so deleting a record in Hubspot will not cause the corresponding record in Sugar to be deleted however it may provoke some changes in previously paired Sugar record.

When a record is synced and paired between sugar and hubspot the Sugar record will have its “Sync to Hubspot” field checked and will also have a “hubspot ID” value for the paired record in Hubspot. If that hubspot record is deleted then the next time the Sugar record attempts to sync it will not be able to find the paired record, should this happen the Sugar records “Sync to hubspot” field will be automatically unchecked and the “Hubspot ID” value reset to null. Effectively this will prevent the record from attempting to sync again unless it is later checked to sync again.

Q. What happens if I delete a synced record in Sugar?

A. The integration does not sync deletions of records so deleting a record in SugarCRM will not cause the corresponding record in Hubspot to be deleted however it may provoke some changes in previously paired Hubspot record.

When a record is synced and paired between sugar and hubspot the Hubspot record’s “SugarCRM ID” property will contain the ID value of its paired Sugar record. If that sugar record is deleted then the next time the Hubspot record attempts to sync it will not be able to find the paired record. Should this happen the the Hubspot records “Sugar ID” value will be updated to the value of DELETED and will be ignored for future sync cycles so that the record is not recreated in Sugar.