Your First Integration in 60 Minutes

Introduction

So you want to try out the Cloud Elements platform and see if it solves your use case?

While our platform can realize many different use cases (e.g. 2016 & 2018 Top Marketplaces), this tutorial is specifically designed to guide you, a developer or system integrator, through setting up a contact sync between different endpoint services using Cloud Elements. During this tutorial, you will learn how to:

  1. Authenticate application instances using the Cloud Elements platform
  2. Configure events to monitor changes to a CRM
  3. Map and normalize objects across different services
  4. Perform a contact sync by creating, executing, and testing formula instances

The intent of this tutorial is to familiarize you with the components of the Cloud Elements platform through a simple data sync use case. We'll use Salesforce Sales Cloud, HubSpot Marketing, and SugarCRM as examples, but the concepts and workflows in this tutorial still apply to other use cases—if a contact sync is not your exact use case, this can still help you along your integration path!

This tutorial is also designed to be accessible people who may not have much experience with coding or APIs. You won't have to be a ninja-level programmer to follow along, but familiarity with these concepts will be helpful:

  • REST and JSON data formatting
  • Invoking an API
  • JavaScript basics

Things you will need for this tutorial

  • Cloud Elements trial account (click here to register)

  • Sandbox accounts for the applications and endpoint environments you will integrate. The examples we'll use in this tutorial are:
    • SFDC developer account (click here for a free account)
    • SugarCRM account (click here for a free trial account)
      • Some additional configuration values are needed to connect to SugarCRM once your sandbox account has been created; to learn more, see SugarCRM API Provider Setup
    • HubSpot (click here for a free trial account)

The first step in setting up our contact sync is to authorize the Salesforce Sales Cloud, HubSpot Marketing, and SugarCRM elements applications to connect to your accounts. To do so, you will authenticate with the API providers to create element instances of the Salesforce Sales Cloud, HubSpot Marketing, and SugarCRM.

First, we'll walk you through a simple authentication of an instance.

Here's a video that show how to create an element instance


Authenticating Instances

Authenticate a Salesforce Sales Cloud Instance

In this step, you will authenticate an element instance with Salesforce Sales Cloud. As part of that authentication, you will enable events so Cloud Elements can monitor any additions or changes to your list of contacts.

Below is a quick overview about how to authenticate, but you can also walk through detailed instructions for authenticating either by using the UI or via API.

  1. Find Salesforce Sales Cloud in the Elements Catalog, hover over the card, and click Authenticate.
  2. On the Create Instance page, enter a name for your instance (for this tutorial, use Salesforce Contacts), enable events by clicking Events Enabled, and then select webhook.
  3. In the Objects to Monitor for Changes field, enter Contact.
  4. So we receive event notifications, in Event Notification Callback URL enter https://api.cloud-elements.com/elements/api-v2/events/sfdc.
    If you would like to test webhook functionality during this integration, the Webhook Tester site provides a free bucket from which to send requests and view payloads. For more information about events, see the Events Overview.

    Your setup should look like this (note the code example created as you enter data):

    Create SFDC Instance

  5. Click Create Instance, log in to Salesforce and allow the connection to Cloud Elements.
  • After you authenticate the element instance we suggest that you test it out using the API docs. 

    1. Click Test in the API docs.

    2. Note on the left that we already selected the instance you just created, so any APIs you try execute against that instance. 

    3. Click to open GET /accounts, and then click Try it out.

    4. Scroll down, and then click Execute. The response body includes all of the accounts in your Salesforce account.
  • Once you finish testing, move on to authenticate with HubSpot Marketing.

    Authenticate a HubSpot Marketing Instance

    In this step, you will authenticate an element instance with HubSpot Marketing, allowing . Because this example creates a one-directional sync from Salesforce to HubSpot, you do not need to configure events for HubSpot.

    1. Navigate to the Elements Catalog and search for HubSpot Marketing.
    2. Hover over the element card, and then click Authenticate.

      As you did when authenticating the Salesforce Sales Cloud instance, you will also use Oauth 2.0 to authenticate with HubSpot Marketing.

    3. Name your instance (for this tutorial, use HubSpot Contacts).
    4. Click Create Instance, and then authorize Cloud Elements.
  • Like the Salesforce Sales Cloud instance, we suggest that you test HubSpot out using the API docs. Click Test in the API docs, open GET /contacts, click Try it out, and then click Execute. The response body includes all of the contacts in your HubSpot account.

    Authenticate a SugarCRM Instance

    In this step, you will authenticate an element instance with SugarCRM. Because this example creates a one-directional sync from Salesforce to SugarCRM, you do not need to configure events for SugarCRMbSpot.

    1. Navigate to the Elements Catalog and search for SugarCRM.
    2. Hover over the element card, and then click Authenticate.
    3. Name your instance (we suggest SugarCRM Contacts)
    4. Input the required fields.  These are the additional configurations collected after the sandbox account was created.
    5. Click Create Instance, and then authorize Cloud Elements.
  • Like the Salesforce Sales Cloud instance, we suggest that you test SugarCRM out using the API docs. Click Test in the API docs, open GET /contacts, click Try it out, and then click Execute. The response body includes all of the contacts in your SugarCRM account.

    With the authenticated instances, you're now ready to clone the Basic Contacts VDR template in order to map /contacts object across different services.

    Clone Basic Contact VDR Template

    1. Log in to Cloud Elements and navigate to the Virtual Data Resources page.
    2. On the Virtual Data Resources Catalog page, click the VDR Templates tab.
    3. Hover over the basic-contacts VDR template, and then click Mappings to clone the VDR, or to see the VDR's name and URL, system level fields, and mapped elements.
    4. Navigate to the Mappings tab of the basic-contacts VDR template and click Clone.
    5. Search for and select the elements you want to include in the VDR (for this tutorial, select Salesforce, HubSpot Marketing, SugarCRM), and then click Next. You can also click the check box next to the Element Name column header to select or de-select all listed elements.
    6. Select the level at which the system fields should be created in the VDR (for this tutorial, select Organization), and then click Next.
    7. Click Save. For this tutorial, do not change the name from basic-contact. In the future, we suggest modifying the name, although we will use the basic-contact name in our formula workflow.
    8. Your new VDR now appears in the My Resources list and is ready for transformations.
  • Import Basic Contact Sync Formula Template

    You can import templates from their JSON source file.

    To import a formula template:

    1. Download the BasicContactSync.json
    2. Click Formulas, and then click Build New Formula. Build New Formula
    3. Click Import. Import Formula
    4. Select the JSON file you downloaded in step 1.
    5. Optionally rename the file, and then click Create.
  • Create Formula Instances

    In order to test this formula workflow with multiple services, we will create two instances of the formula template and select our Source and Destination instances.

    To create the first formula instance:

    1. Navigate to the Formulas page.
    2. Hover over the formula card, and then click Create Instance.
    3. Enter a name for the instance (We recommend Salesforce to HubSpot).
    4. In the Variables section under Instances, select an instance variable, and then choose or create an element instance to replace the variable.
      • For Destination, select the HubSpot Marketing Instance.
      • For CRM Source, select the Salesforce Sales Cloud instance. Variables
    5. To add email or webhook error notifications, click Show Advanced and complete any of these steps:
      • In the Email field, enter a comma-separated list of email addresses you want to receive error notifications.
      • In the Webhook URL field, enter a comma-separated list of URLs you want error notifications sent to.
    6. Click Create Instance.
  • To create the second formula instance:

    1. Navigate to the Formulas page.
    2. Hover over the formula card, and then click Create Instance.
    3. Enter a name for the instance (For this tutorial, use Salesforce to SugarCRM).
    4. In the Variables section under Instances, select an instance variable, and then choose or create an element instance to replace the variable. In this tutorial: 
      • For Destination, select the SugarCRM Instance.
      • For CRM Source, select the Salesforce Sales Cloud instance.Variables
    5. To add email or webhook error notifications, click Show Advanced and complete any of these steps:
      • In the Email field, enter a comma-separated list of email addresses you want to receive error notifications.
      • In the Webhook URL field, enter a comma-separated list of URLs you want error notifications sent to.
    6. Click Create Instance.
  • Test the Integration

    1. Log in to your Salesforce sandbox account and create a new contact.

    2. View the Formula Execution logs to see the details of your formula executions, including any success or error messages by completing these steps:

      • Navigate to the Formulas page.
      • Hover over the formula card, and then click Executions.
    3. Log in to HubSpot and SugarCRM to ensure the contact has been added to both destinations.