Overview

 In modern technology, there is a clear need to reuse objects and let the user configure each object once and repeatedly use it over and over again.
This is the basic assumption of the “Connection” configuration in Totango Customer Data Hub. 

Connection to a data source is usually done by Ops or Data teams, and the main idea is that it will be configured once and you can reuse the same connection for several integrations.

Important note, the CRM integration family is a closed system, therefore, the data source connectors which are created can be re-used for only CRM integrations and not for other integration families.

Topics covered in this article: 

• Creating CRM Connections
• Configuring Salesforce Connection
• Configuring MS Dynamics Connection
• Configuring HubSpot Connection

Creating CRM Connections

1. Go to your Totango instance and click on Global Settings > Data Management > Customer Data Hub > find the CRM source you wish to upload data from by searching or filtering connectors.

   
   (note: you will need Totango admin privileges). 

2. Create a new connection (or review your existing connections)
   
   
   

Configuring Salesforce Connection

Salesforce configuration is based on OAuth credentials and requires a dedicated connected app configured in Salesforce. The dedicated connected app is the authentication endpoint and the OAuth user holds the object permissions to your Salesforce.

Totango Customer Data Hub is using salesforce REST API v47.0 (/services/data/v47.0) to retrieve the data and update your sync-back attributes. Read more about Salesforce Rest API.

First, you will create the connected app in Salesforce, and then create the CRM connector in Totango.

Create A Connected App in Salesforce

Creating a connected app is needed for creating an authentication endpoint within Salesforce. The new connected app informs Salesforce of this new authentication entry point and includes the relevant authentication configuration. Read more about Salesforce connected apps.

Follow these steps to create a new connected app to sync data to Totango:

1. Open SalesForce, using Admin access.
2. create a new connected app.
   In Lightning View:
   • Open App Manager under Platform Tools --> Apps
     
   • Click 'New Connected App' from the header
     
     
     In Classic View:

• Click Apps under "Build" > "Create" menu
  
• Scroll the bottom of the page, under the "Connected Apps" section click New to start defining a new connected app.
  
• Enter the name of your application.
• Enter the contact email information, as well as any other information appropriate for your application.
• Select Enable OAuth Settings.
• Enter this Callback URL: https://app.totango.com/auth/connector/callback 
• OAuth copes are permissions given by the user running the connected app.
  Add these scopes to the "Selected OAuth Scopes" and click "Save": 
  • Full access (full) 
  • Perform requests on your behalf at any time (refresh_token, offline_access) - enable it to allow the integration to ask for a token refresh without user intervention.
• Token validation is usually configured to 12 minutes, you can change it per your company standards.
  
  
• Click the "Save" button

Important note, it might take 2-10 minutes before your new connected app is created on Salesforce server.

Create a CRM Connector to Salesforce in Totango

After the Salesforce connected app is created, create the connection in Totango.
Enter the connection name and description, client id, client secret, and select the Salesforce environment type (production or sandbox), then click the “Test and Save connection” to connect using your OAuth credentials.

You will be asked to enter your Salesforce credentials unless you are already connected in a different tab of the browser. In the later, the oAuth configuration will take the credentials stored in your active browser session.

Important note, the OAuth user holds the object permissions to your Salesforce. We recommend creating a dedicated user for this integration which has the desired object access permissions (for example, the dedicated OAuth user can access Account object but not Contact object). 

Configuring MS Dynamics Connection

MS Dynamics configuration is based on OAuth credentials and requires a dedicated connected app configured in MS Dynamics.

First, you will create the connected app in MS Dynamics, and then create the CRM connector in totango.

Create App in MS Dynamics

Creating an app is needed for creating an authentication endpoint within MS Dynamics. The new app informs MS Dynamics of this new authentication entry point and includes the relevant authentication configuration. Read more about MS Dynamics connected apps.

Follow these steps to create a new connected app to sync data to Totango:

1. Sign in to the Azure portal using an account with administrator permission. You must use an account in the same Office 365 subscription (tenant) as you intend to register the app with. You can also access the Azure portal through the Office 365 Admin center by expanding the Admin centers item in the left navigation pane and selecting Azure Active Directory.
   
2. Navigate to Azure Active Directory > App registrations > Click + New application registration.
   
   

3. In the Register an application page, enter your Totango app registration information:

   • In the Name section, enter a meaningful application name like "Totango main data sync".

   • Select "Accounts in any organizational directory" option from the supported account types section.

   • Keep the Redirect URI to https://app.totango.com/auth/connector/callback 

   • Click on "Register" to create the application.
     
     

4. On the app Overview page, hover over Application (client) ID value, and select the Copy to clipboard icon to copy the value as you'll need to specify this in your application's authentication code or app.config file where appropriate.
   
   

5. Select Manifest tab, in the manifest editor, set the allowPublicClient* property to true and click on Save button.
   
   
   

6. Select API permissions tab, click on Add a permission.
   

7. Select Dynamics CRM under the Microsoft APIs tab.    
   

8. Click on Delegated permissions and check the options and click on Add permissions.
   
   

9. Select Certificates & secrets tab, click on New client secret. Add a meaningful description and select expires Never.
   Important note, copy the client secret and later on use it in configuring the Totango connector. You will not be able to copy it later.
   
   
   
   

10. This completes the registration of your application in Azure Active Directory.

11.  Now that we have our Azure app set up complete, we’ll move on to creating an application user.

    • Once you create the app user, make sure to give it a custom Security role that has the access you want this user to have.

    • Navigate to your Dynamics 365 org > Settings > Security. Change the view to Application Users and then click +New.

      

    • This will show you a new user form (make sure to change the form to “APPLICATION USER”) where you will only need to fill the “Application ID” field. Use the application ID you created from your Azure app in the previous steps.

       

Create a CRM Connector to MS Dynamics in Totango

After the MS Dynamics app is created, create the connection in Totango.
Enter the connection name and description, and then choose the "MS Dynamics" type.
Enter the MS Dynamics details below: 

1. Client ID: Azure Active directory application ID
2. Client secret: Azure Active directory application secret (you have copied it in the steps above)
3. Organization domain: MS-Dynamics CRM domain
4. Directory (tenant) id: Azure tenant ID

MS-Dynamics CRM domain:

Click the “Test and Save connection” to connect using your OAuth credentials.

You will be asked to enter your MS Dynamics credentials unless you are already connected in a different tab of the browser. In the later, the oAuth configuration will take the credentials stored in your active browser session.

Note: Organization domain should contain the full URL (https://{org_id}.crm.dynamics.com)

Configuring HubSpot Connection

HubSpot configuration is based on OAuth credentials and requires a HubSpot admin permission to install it.

You can create the connection right from the HubSpot Marketplace OR from Totango Customer Data Hub.

Create A Connection to Totango from HubSpot Marketplace

1. Go to the HubSpot marketplace (on the right side of the top bar) and search for the Totango app.
   
   
   
   
2. Review the Totango app details and click the "Connect app" button
   
   
3. You will be redirected to your Totango account.
   Log in using a Totango global admin user or a user with Customer Data Hub permissions, enter the HubSpot connector name and meaningful description, and click "Test and Save Connection" button.
   
   
   
4. After clicking on the "Test and Save Connection" button, HubSpot dialog will open asking which HubSpot account to connect Totango, select the right HubSpot account.
   Important note, click on the HubSpot account name to select it and not any other button on the dialog.
    
   
   On the following page accept Totango permissions
   
   
5. That's it!
   
   Now you can create your first integration by clicking on the Green plus button.

Create HubSpot Connector From Totango

This is another way to create your HubSpot connector. If you already connected it from the HubSpot marketplace, you should skip this section and start streaming HubSpot data to Totango.

1. 1. Go to the CRM connection on the Customer Data Hub page, and find the HubSpot connector
   Note, you must be a Totango global admin user or a user with Customer Data Hub permissions to see this page.
   
   
2. Enter the connection name and description, and click the 'Test and add connection' to connect to HubSpot using your OAuth credentials.
   You will be asked to enter your HubSpot credentials unless you are already connected in a different tab of the browser. In the later, the oAuth configuration will take the credentials stored in your active browser session.

Important Note, when integrating to HubSpot there are cases in which a user has several accounts associated with his user. You should select the right account when authenticating.

Writing query for HubSpot

• Choose your object for query (contacts, companies, deals, line_items, etc.)
  
  
• Choose fields (properties) which we want to get (from dropdown menu) for an object or start to type name of the field:
   Important: Custom object fields are not supported for selection as HubSpot API does not support it. You should choose only fields from the list.
  
  

You can filter the inbound integration data by adding a query filter and using HubSpot querying language.
Read more about HubSpot query filtering language.

For example, if you want to filter on deals where 'dealstage' equals 'appointmentscheduled' and ‘hs_lastmodifieddate’ earlier then July 26, 2020 11:59:59 PM GMT then the query will be:

[{"propertyName":"dealstage","value":"appointmentscheduled","operator":"EQ"},
{"propertyName":"hs_lastmodifieddate","value":"1595807999000","operator":"LT"}]

Important notes:
1. No spaces are allowed within the filter text
2. Due to HubSpot limitation, the Totango-Hubspot connector supports a maximum of two filters. read more here

3. The query APIs are limited to 10,000 total results for any given query. Attempting to page beyond 10,000 will generate an error.

Key properties for objects in HubSpot

• Contacts
  
  
• Deals
  
  
• Companies
  
  

How to add a Company Id property to deals object

Deals object in HubSpot, as well as other objects, are missing the Company Id property.
Company Id is a required property to connect the entity to the right company, thus it is a mandatory key for syncing data to Totango.

Follow the below steps to configure a workflow including a trigger and automation that will add the Company Id to the Deals object

1. In your HubSpot account click on Automation - Workflows
   
2. Click on ‘Create workflow’ button
   
   
3. On the left-side panel choose ‘Company based’ and write a name of workflow in the top field ‘Name your workflow’. After that click the ‘Next’ button.
   
   
4. Click on button ‘Set enrollment triggers’
   
   
5. Choose 'Company' as the Filter type
   
   
6. Choose 'Associated deals' as the triggered workflow
   
   
7. Configure the criteria to be 'is greater than 0', click on the radio button ‘Include objects with no data’, and click on ‘Apply filter’.
   
   
8. You can test the criteria by clicking on 'Test Criteria' button and at the end click 'Save'.
   
   
   
9. Now that the workflow trigger is created, you should create workflow automation.
   This workflow automation will copy the 'Company Id' value whenever a company has deals associated with it. The workflow automation will be configured for a company object that has property “Associated deals” greater than zero.
   
   Click on Plus ('+') icon in the middle of the workflow chart
   
   
10. Choose the action ‘Copy property value’ from the list
    
    
11. Choose the property ‘Company ID’ as the property to copy from, and 'Deal' as the target property type.
    If you already have an 'AssociatedCompanyID' property in the Deal object select it in the 'Property to copy to' dropdown.
    If you do not have this property, click on 'Create a new deal property' the link below the dropdown and follow the steps described in How to create an AssociatedCompanyID property in the Deal object section below.
    
12. In the 'Copy Property' window, click the 'Save' button.
    
13. Now your workflow is ready, review your created workflow by clicking on the 'Review' button on the top-right corner.
    
14. Review the workflow details, and select the 'Yes, enroll on existing companies as of now' radio-button to copy company id to their existing deals.
    Click on Turn On' button in the top right corner to activate the workflow.
    

15. After enabling the workflow, you can find it in the list of workflows as turned 'on'.
    
    

How to create an 'AssociatedCompanyID' property in the Deal object

1. In your HubSpot account, click the settings icon settings in the main navigation bar.
   In the left sidebar menu, navigate to Properties.
   In the upper right, click 'Create property', fill in the fields according to the screenshot below, then click 'Next'.
   
   
2. Choose 'Single line text' as the 'Field Type', check the ‘Allow users to search for information entered to this field' option, and click the 'Create' button.
   
   
3. After clicking the 'Create' button, you'll see an 'AssociatedCompanyID property was created' notification. 

FAQs 

Question: Will the configured Salesforce integration jobs in Totango get impacted if there is a transition from Salesforce Classic to Salesforce Lightning (no change to backend code in SFDC)?

Answer: No, the jobs will not get impacted.