SugarCRM Connector for Sugar Market

Overview

This guide describes the Sugar Market integration with SugarCRM, including installation, configuration, syncing, and data mappings. Please review Integration Overview: All CRM Types before proceeding with this page. 

Topics

This guide includes the following topics:

• Installing Sugar Market
• Configuring the SugarCRM Connector in Sugar Market
• Understanding the Sugar Market Integration with SugarCRM
• About the Buyer's Journey Integration
• SugarCRM Mappings (separate page)

For the current list of SugarCRM versions that Sugar Market supports, refer to the Sugar Market Supported Platforms page. 

Installing Sugar Market

There are three steps to the Sugar Market installation:

• Installing the Sugar Market Connector
• Configuring the Sugar Market Module in SugarCRM
• Running System Repairs

If you are upgrading from a previous version of Sugar Market, please uninstall the old version before performing the installation.

Installing the Sugar Market Connector

The Sugar Market Connector installs the following custom modules in your SugarCRM instance:

• Event Management
• Landing Pages
• Web Activity
• Web Activity Detail

Please refer to the Sugar Studio documentation for information on configuring modules.

To install the connector:

1. Download the correct Sugar Market connector installation file from the table shown below.
2. Log into SugarCRM and upload the Sugar Market module. Please refer to the SugarCRM Module Loader documentation for information on uploading modules.

¹ Please refer to the Sugar Market Supported Platforms page for the current list of SugarCRM versions that Sugar Market supports.

² Sugar Market only connects to SugarCRM when the backend database is MSSQL or MySQL; other databases are not supported (e.g., Oracle, DB2).

Configuring the Sugar Market Connector in SugarCRM

After installing Sugar Market, configure the Sugar Market connector in SugarCRM. Please refer to the SugarCRM Connector documentation for more information on configuring connectors.

1. In SugarCRM, navigate to Admin > System > Connectors.
   
2. Click the Set Connector Properties button.
   
3. Navigate to the Sugar Market tab and add the Unique ID generated on the Sugar Market Connector Settings page to the Organization Name field. Please refer to the Connecting Sugar Market to SugarCRM section of this guide for more details.
4. Click the Save button.
   
   
   
5. On the Connector Settings page, click the Enable Connectors button.
   
6. On the Sugar Market tab, drag Accounts, Contacts, and Leads to the Enabled list, and then click the Save button.
   

Running System Repairs

After installing Sugar Market, we recommend you run the following system repairs. Please refer to the Repair documentation in the SugarCRM Administration Guide for more information.

1. In SugarCRM, navigate to Admin > System > Repair.
   
2. Click the Quick Repair and Rebuild link.
3. After the repair is complete, click the Clear Additional Cache link.
   

Upgrading the Sugar Market Module

If you are upgrading to the newest version of Sugar Market, you must first uninstall the Sugar Market module by following these steps:

1. Log in to SugarCRM and navigate to Admin > Developer Tools > Module Loader.
2. Click the Uninstall button next to the Sugar Market module.
   
3. On the Ready to Uninstall page, select the "Do Not Remove Tables" option, and then click the Commit button. 
4. Navigate to Admin > System > Repair.
5. On the Repair page, click the Quick Repair and Rebuild link.
6. Proceed to the steps in the Installing Sugar Market section.

Configuring the SugarCRM Connector in Sugar Market

The SugarCRM Connector provides access to set up and modify your connection information and sync preferences.

To access the connector:

1. Log in to your Sugar Market account and from the user menu, click "Admin".
2. In the CRM Administrator section, within the External Connector tab, click "SugarCRM Settings".
   

Complete the following steps to configure the connector:

1. Connect Sugar Market to SugarCRM.
2. Inform your Implementation Consultant that your connection settings have been completed and verified. Your Implementation Consultant will then enable the initial sync of your data.
3. Set up your sync preferences.
4. Set up your sync filters (optional).

Connecting Sugar Market to SugarCRM

The first step in configuring your Sugar Market Connector is to let Sugar Market know how to connect to your instance of SugarCRM. These steps must be completed before you can set your sync preferences.

1. Complete the following fields:
   • Unique Key: This is a Sugar Market-generated GUID, unique to your organization, which is used in calls to Sugar Market from your CRM.
   • SugarCRM Instance URL: The URL for your SugarCRM's web service endpoint http://sugar.domain.tld/rest/v10/.
   • CRM Username: Identify the Sugar CRM username that Sugar Market will use to sync with your CRM.
     Please note: Always create a dedicated syncing user in the CRM for the Sugar Market sync since SugarCRM does not support concurrent logins. Additionally, all records created or updated by the sync will be attributed to the syncing user; therefore, the syncing user must have the necessary permissions to read and update all records you want to sync with Sugar Market.
   • CRM Password: The password for the above user.
2. After entering the SugarCRM connection information, click the Test Login button to validate the syncing user credentials. If the credentials are not valid, then you cannot save the connection information.
3. Click the Save Connection Information button.

Setting Up Sync Preferences

Setting up your syncing preferences includes determining what information you want Sugar Market to sync down from SugarCRM and what information you want Sugar Market to update and create in SugarCRM, and corresponding settings as described in the sections below.

• Setting Your Sync Data
• Identifying Sync Time Settings
• Selecting Database Integrity Settings
• Setting CRM Sync Alert Contacts

Click the section heading bars to expand or collapse sections on the page:

Setting Your Sync Data

To identify the data you want to sync between Sugar Market and SugarCRM:

1. In the "Default user for new records" field, select the name of the Sugar Market user to be assigned as the default (catchall) owner of a new lead when it is pushed up to SugarCRM and the user does not already exist in SugarCRM (the user only exists in Sugar Market). When the user does not already exist in SugarCRM, Sugar Market assigns the defined user in this setting as the lead record owner. User names only populate this list after the initial sync is complete.
   Note: The default user must have previously logged into Sugar Market and accepted cookies. 
   
2. Select the desired settings for data to be pulled from SugarCRM.
   
3. Set the desired settings for data to be pushed from Sugar Market to SugarCRM, and then click the Save button at the bottom of the section.
   
   
   

Please refer to the Understanding the Sugar Market Integration with SugarCRM section for more information on how the following sync settings affect the records that are shared between Sugar Market and SugarCRM.

Pull Data (Sync from CRM)

Push Data (Sync to CRM)

Identifying Sync Time Settings

Records are synced between Sugar Market and SugarCRM according to the schedule identified on the Integration Overview page. If you do not want to sync your data between the hours of 9:00 PM and 6:00 AM Eastern time, then select the checkbox in the Sync Time Settings section, and then click the Save button.

Selecting Database Integrity Settings

We strongly suggest you work with your Client Services Representative to configure the settings in the Database Integrity section.

To select database integrity settings, select the desired options as described below, and then click the Save button at the bottom of the section.

• Reconcile deleted Contact and Lead records from your CRM: This feature records the deletion of Lead and Contact records in SugarCRM and deletes the same records from Sugar Market. This feature is helpful for compliance with data privacy regulations such as GDPR since the process eliminates the need to separately delete a lead/contact from Sugar Market when it is deleted in SugarCRM. 
• Keep records but disconnect them from CRM: This option keeps the deleted Leads and Contact records in Sugar Market but disassociates them from their previous parent record in SugarCRM
• Post-sync cleanup reports: These optional reports can be configured to run at the completion of every data sync cycle, to identify and remove Lead and Contact records from Sugar Market that meet certain criteria. Records will not be removed from SugarCRM. Available reports were built with the viewAccountContact view with a filter of CRMType = "Contact" or "Lead".
  
  Note: When a Lead or Contact record is deleted the historical tables (ex. campaign activity, web activity, etc.) are preserved and are linked to the unique email address. If a record is recreated with the same email address any preserved historical data is restored.

Setting CRM Sync Alert Contacts

To have automated sync alert emails sent to specific users, identify the email addresses in the Alerts section, and then click the Save button.

Setting Up Sync Filters

Sync Filters allow you to choose which records to sync from SugarCRM into Sugar Market based on fields that match specific criteria. Sync Filters define the records that sync from SugarCRM into Sugar Market; they do not define the records that sync from Sugar Market back to SugarCRM.

After setting up your sync preferences, complete the steps in this section to set up sync filters. If you do not set up any sync filters, then all records in core tables will sync from SugarCRM into Sugar Market. Since Sync Filters define the records that are syncing down from SugarCRM, it is important to consider these settings carefully and to test before using the filters.

Note: Sync filters are at the record level, not at the field level.

To set up sync filters:

1. Confirm you have allowlisted the IP addresses identified in the Integration Overview. These are required for sync filters to be enabled.
2. Navigate to the Sync Filtering tab of the SugarCRM Settings page.
3. From the Sugar Sell Module dropdown, select the module in which you want to select fields to sync to Sugar Market, and then click the Build Filter button.
   
4. In the Sync Filtering popup dialog, click the pencil icon to set specific conditions.
   
5. To identify the field to be synced from SugarCRM, select a field from the Field list by scrolling or using type ahead. Do not set up sync filters for non-database fields.
6. Set the conditions for the selected field by selecting an operator and identifying the value to match (e.g. Billing State Equals TX).
7. To set additional conditions to be combined with or evaluated against the condition you just set, click the AND or OR button based on the type of logic desired (e.g. Billing State Equals TX and Industry Equals Banking). Repeat this step as many times as desired.
   
8. To create a separate field grouping within the selected SugarCRM module, click the AND or OR button at the bottom of the dialog, and then repeat the steps outlined above.
   
9. Click the Save button when all filter conditions for the selected module are complete.
10. To set filter conditions for fields in other SugarCRM modules, repeat from Step 2 with the desired module.

Testing Sync Filters

After all filter conditions are set as desired, you can perform a test to help you determine if your filters are set as expected. The test returns a preview of up to twenty records that will be synced over from SugarCRM with the filters as currently defined.

Note: While testing sync filters is not a required step, it is strongly recommended to ensure the expected results are returned. 

To test sync filters:

1. Click the Run Test Sync button on the Sync Filtering tab.
   
2. Results display with default fields. Click the field labels to remove fields from the displayed results, or use type ahead to locate and add additional fields.
   
3. Use the Search field to locate specific records. Partial keywords will return results for string fields, but full keywords need to be used to locate records for multi-select and checkbox fields.
4. If the results are not as desired, then return to the sync filters settings to review your conditions.

Viewing Sync Results

Once your sync between Sugar Market and SugarCRM is activated, the state of the sync is shown in the sync banner which is displayed at the top of your SugarCRM Settings page. Depending on the state of your sync you will see one of the three statuses in the banner:

Inactive

The inactive status is displayed when the sync has not been configured yet or has been disabled. You will need to either configure or reenable your sync to resolve this status.

Active

The active status is displayed when the sync is active and data is being pushed and pulled between Sugar Market and SugarCRM.

Error

The error status is displayed when either your syncing user credentials are invalid or if their access in SugarCRM is preventing data from being synced. You will need to either update the syncing users' login credentials on the SugarCRM settings page or update the syncing users' access in SugarCRM to resolve this status.

Sync Alert Emails

You can also receive sync alert emails to inform you of sync status changes as well as dynamic list sync status changes. You can select which email addresses receive these alerts in the Alerts section of your SugarCRM Settings: 

Understanding the Sugar Market Integration with SugarCRM

When Sugar Market is integrated with SugarCRM, records are synced to corresponding modules according to your sync settings.

Timeline Dashlet

In addition to synced records being available in corresponding Sugar modules, the following records are displayed in the Timeline dashlet in Account, Contact, and Lead record view dashboards, providing the entire customer journey within Sugar: Emails, Events, Landing Pages, and Web Activity. 

In addition to the standard record cards in the Timeline dashlet, the following record cards are available for Sugar Market integrations:

Record Card Icon	Record Card Type	Content
	Email card1	Emails sent through Sugar Market campaigns
	Event card	Event name Event date Registration badges: registered, attended Event description
	Landing Page card	Landing page name Landing page responses Date completed
	Web Activity card	Web page name Visit date Visit duration in seconds

¹ The Email card is part of the standard record cards in the Timeline dashlet; therefore, this card also includes emails sent through SugarCRM.

In addition, field updates to the Assigned to field in Events are included in the timeline.

Integration by Module

This section describes how Sugar Market module records are integrated with SugarCRM, and includes references to the corresponding sync settings:

• Campaigns
• Emails
• Events
• Landing Pages
• Target Lists
• Tasks
• Web Activity

Please refer to the Setting Your Sync Data section for more information on configuring the settings for these integrations.

Campaigns

Sugar Market Sync Setting: "Push Email Statistics to Campaigns and Campaign Targets"

Sugar Market will create a new Campaign record in SugarCRM that includes the email send statistics and a Target List record that contains the email recipients.

Clicking the View Status button in the Campaign record displays the campaign statistics at the bottom of the record:

For more information about campaign records in SugarCRM, please refer to the Sugar Application Guide.

Emails

Sugar Market Sync Setting: "Push Sent Email to Email Module" or "Push Sent Email to Completed Task"

When Sugar Market has captured the delivery status of an email recipient, the Email record in SugarCRM is updated according to the selected push setting in the connector configuration:

• Emails: When emails are pushed to the email module in Sugar, an Email record is created. This option contains the Opens and Clicks count (if enabled in the push settings), the email sender, and the name of the campaign. Using this option helps to eliminate clutter in the Task module.
  
• Tasks: When emails are pushed to completed task, the email record is pushed to an existing Task record in SugarCRM with a status of "Completed". This option does not include the Opens and Clicks count but is a good option if your Sales team is active in the Activity history.
  

The options to sync email open and click records are available with both email settings. When the records are pushed to Sugar, their subjects are prefaced with "Email Opened", "Email Sent", or "Email Clicked", as shown below:

Events

Sugar Market Sync Setting: "Allow Sugar Market to Push Event Data"

After a Sugar Market Event has occurred, all registered and attended contact and lead records are updated in SugarCRM with the event information inserted into the Event Management custom module. Event records contain event details for which the record has registered and/or attended.

Landing Pages

Sugar Market Sync Setting: "Push Form Completion Data"

When Sugar Market has captured a landing page completion, a landing page completion is added to the respective record in SugarCRM's Landing Pages custom entity. The landing page name and completed date for each landing page completion are displayed here.

Target Lists

Sugar Market Sync Setting: "Pull Target Lists to Distribution Lists"

Sugar Market will sync down members of SugarCRM campaigns into a distribution list, which can then be used as an include or exclude list in Sugar Market campaigns. 

The following conditions will prevent the syncing of target list members into distribution lists:

• A corresponding Contact record does not already exist in Sugar Market
• Duplicate, blank, or invalid email addresses

Tasks

Sugar Market Sync Setting: "Allow Sugar Market to Create Tasks"

When Task records are created in Sugar Market they are pushed as open Task records in SugarCRM. 

Web Activity

Sugar Market Sync Setting: "Push Web Activity to Activity History" or "Push Web Activity to Custom Tables"

When Sugar Market has captured cookied web activity for a lead or contact, the corresponding record in SugarCRM is updated according to the push setting in the connector configuration:

• Activity History: Pushes web activity to Sugar's Task module as a "Web Activity Detected" record. This option is most useful if your team is often working in the Task module. 
  
• Custom Tables: Pushes the web activity and corresponding web activity detail records to the Web Activity and Web Activity Detail custom modules in SugarCRM. This option allows you to see more information easily.
  

Reports

SugarCRM reports in the Leads and Contacts modules can be synced with Sugar Market in the form of dynamic distribution lists. Syncing these reports will create new records in Sugar Market when they do not already exist and update existing records, in addition to updating the dynamic distribution list in Sugar Market. These dynamic distribution lists can be used in the following ways:

• As include and exclude lists in email and nurture campaigns.
• Can be updated from lead/contact listeners, scoring actions, and event actions.
• Can be referenced in nurtures to determine flow (i.e., if a member of a dynamic distribution list, then take this path).

The following sync settings need to be enabled to use dynamic distribution lists:

• Pull leads
• Pull contacts
• Allow the creation of new leads
• Allow the creation of new contacts

About the Buyer's Journey Integration

The Buyer's Journey integration allows you to view the entire lifecycle of a prospect's marketing activity. As part of the Sugar Market installation, your Sales team has access to the invaluable marketing journey, which is located in your contact and lead records directly in SugarCRM. Simply click the Sugar Market button in a Contact or Lead record in SugarCRM to display a drawer that contains the Buyer's Journey integration.

Please refer to the Sugar Market User Guide for more information about the Buyer's Journey Integration in Sugar Market.

Lead Conversion

When converting leads in Sugar, a new contact record is created in Sugar with a relationship to the original lead record. If an existing contact record is found during conversion, Sugar provides the option to either create a new contact or link to the existing contact record. Sugar Market handles these options as follows:

1. Create new contact during lead conversion: When the lead already exists in Sugar Market, the following fields will be updated on the Contact record in Sugar Market at the next sync:
   • ContactID is replaced with Sugar's Contact ID
   • CRMType is updated from "Lead" to "Contact"
   • IsConverted is updated from "False" to "True"
2. Select existing contact during lead conversion: Both lead and contact records will remain in Sugar Market and be synced based on the customer's sync settings.

For more information on lead conversion in Sugar, please refer to the Sugar Application Guide.

Related Records in Conversion

When the "Lead Conversion Option" is set to "Move" in Sugar's System Settings, all related Event, Landing Page, and Web Activity records will be moved to the converted contact record along with the lead's related CRM activity records.