API Development

Create a Simple Integration Builder Flow

Integration Builder and HubSpot

In this blog, we’ll build a simple Integration Builder flow which monitors HubSpot CRM for new contacts. If a new contact is created in HubSpot, the flow will automatically create the same contact in Salesforce Sales Cloud. We’ll demonstrate the following key functions of the Integration Builder platform:

  1. Authentication with external services
  2. Data mapping
  3. Event triggers

Prerequisites

You’ll need the following for this tutorial:

Note: You will need to log into your Salesforce Developer account at least once before proceeding.  The initial login triggers the creation of the sandbox environment which will be used in this example.

Overview of steps

  1. Create instances of HubSpot CRM and Salesforce Sales Cloud connectors
  2. Build a data mapping to create a normalized representation of a Customer
  3. Configure your connector instances to use the mapping
  4. Configure the HubSpot CRM connector instance to poll for updates
  5. Build a flow template using the connector instances and mapping
  6. Create a flow instance that triggers when the HubSpot CRM connector instance polls for an update

Create Connector Instances

  • Log onto the AMPLIFY platform at https://platform.axway.com
  • Click the Sandbox link on the Application Integration tile to enter the Integration Builder interface
  • In the left-hand menu, select the Connectors tab
  • Use the search bar to search for HubSpot CRM
  • Hover over the HubSpot CRM connector tile and select Authenticate
  • Name the connector HubSpot In
  • Set Authentication Type to API Key
    To obtain your API Key, log into the HubSpot console, navigate to Settings -> Integrations -> API Key.  If you have no keys, then go ahead and create one.
  • Create a Connector Instance Tag named hubspot2salesforce and check the box labeled Create option: hubspot2salesforce
    NOTE: Instance tags can be used to filter and search for objects in the UI. This becomes helpful when you have many objects and only want to view a subset. We’ll tag all of the objects in this demo with the same name so that we can view them as a group later.
  • Under Events Configuration, move the slider to Events Enabled. This will enable the polling we need to watch for updates.
  • Under Configure Polling, deselect accounts and opportunities, since we are only interested in looking for new contacts.
  • Set the Event poller refresh interval to 1 minute.

    HubSpot CRM
  • Click the CREATE INSTANCE button. You’ll be redirected to the HubSpot authentication page
  • Navigate to the Instances tab, and you should now have an Instance of the HubSpot CRM connectorInstance of the HubSpot CRM connector
  • Return to the Connectors tab
  • Search for Salesforce Sales Cloud
  • Hover over the Salesforce Sales Cloud connector tile and select Authenticate
  • Name the connector Salesforce Out
  • Set Authentication Type to oauth2
  • Use the hubspot2salesforce tag created earlier in the Connector Instance Tag field
  • This connector instance will be invoked by a flow, so there is no need to configure polling
  • Click the CREATE INSTANCE button, and you’ll be redirected to the Salesforce Cloud authentication page. Use your Salesforce Cloud credentials to authenticate the connector instance.
    Click the CREATE INSTANCE button
  • Navigate to the Instances tab, and you should now have an Instance of the Salesforce connectorInstance of the Salesforce connector

Create a mapping

Mappings can be used to create a normalized data model for use within Integration Builder.  In this example, we’ll use a mapping on the inbound call to map the HubSpot-specific data model into a custom data model, mapping only the fields we need and giving them convenient names for internal reference. The map will also be used on the outbound call to Salesforce where it will map the internal data model to the appropriate fields in the Salesforce data model.

  • Navigate to the Mappings tab and click the Build a new Mapping tile
  • Click BUILD NEW RESOURCE
  • Under Mappings Name and URL, enter myContacts
  • Under Organizational Level Fields, click the + button (far right) 8 times to create 8 fields.
  • Create the following fields:
    Field NameTypeDisplay Name
    emailstringEmail
    firstNamestringFirst Name
    lastNamestringLast Name
    streetstringStreet Address
    citystringCity
    statestringState
    postalCodestringPostal Code
    countrystringCountry
  • Click Save next to the Mappings Name and URL fieldMappings Name and URL

Associate mapping with a Connector Instance

  • Click Create New Transformation for “myContacts” under Mapped TransformationsMapped Transformations
  • Under Connector Instances, click the the HubSpot In connector instance
  • Under Connector Instance Resources, find and click on the contacts resource.
  • Using the drop-down lists for each Field Name, select the HubSpot data model field to map to appropriate mapping field. You can start typing the name of the field to narrow the results to pick from.
    Field NameHubSpot Field
    cityproperties.city
    countryproperties.country
    emailproperties.email
    firstNameproperties.firstname
    lastNameproperties.lastname
    postalCodeproperties.zip
    stateproperties.state
    streetproperties.address
  • Click the Transformation Settings button (gear icon)Transformation Settings button (gear icon)
  • Enable Add to API Docs and Remove Unmapped Fields options
  • Click Save
  • Click the Save button next to the Transformation Settings icon

Test the mapping

  • Click the Try it Out button (play icon in image above)
  • Click the Send button
  • A successful result will return the HubSpot demo data, showing only the fields in the map formatted per the defined JSON data model.
    [
       {
         "firstName": "Cool",
         "lastName": "Robot (Sample Contact)",
         "city": "Cambridge",
         "state": "MA",
         "email": "coolrobot@hubspot.com"
       },
       {
         "firstName": "Brian",
         "lastName": "Halligan (Sample Contact)",
         "city": "Cambridge",
         "state": "MA",
         "email": "bh@hubspot.com"
       },
    ...

Associate mapping with Salesforce Connector Instance

Click the Mappings button

  • Refresh the mappings view by clicking the Mappings button
  • Click the Create New Transformation for “myContacts” button
  • Under Connector Instances, select the Salesforce Out instance
  • Under Connector Instance Resources, search for and select the Contact resource
  • Map the following fields as done previously with the HubSpot connector
Field NameSalesforce Field
cityMailingCity
countryMailingCountry
emailEmail
firstNameFirstName
lastNameLastName
postalCodeMailingPostalCode
stateMailingState
streetMailingStreet

 

  • Click the Transformation Settings (gear) icon
  • Enable Add to API Docs and Remove Unmapped Fields options
  • Click Save in the Transformation Settings window
  • Click Save next the Mappings window
  • Refresh the Mappings window again by clicking on the Mappings button as above
  • Note that the HubSpot In and Salesforce Out Connector Instances are now associated with the myContacts mapping

Inspect API Docs

Understanding the changes made to the API Docs by the mapper will help to explain values used when building the flow in the next section.

  • Navigate to the Instances tab in the Integration Builder UI
  • Click the API DOCS button for the HubSpot In Connector instance
  • Scroll down to the Contacts section and locate the /myContacts set of APIs. These are the APIs that were added by the mapper when the myContacts map was created.

Note the GET /myContacts and GET /myContacts/{id} APIs. These will get all contacts from HubSpot or contacts based on the result of a query string. Looking forward to the flow, the trigger event will contain the id of any newly created contact. The flow will then call the GET /myContacts/{id} and retrieve the fields defined in the mapping from the new contact entry.

Examine the API docs for the Salesforce Connector Instance. The flow will use the GET /myContacts/{id} to check if a contact already exists and then the POST /myContacts to create a new contact.

Create a flow

  • Navigate to the Flows tab in the Integration Builder UI
  • Click the Build New Flow Template tile
  • Click the BUILD NEW FLOW option
  • Name the flow HubspotToSalesforce
  • Click CREATE
  • Select Event as the trigger type by clicking the ADD EVENT button
  • Under Connector Instance Variable, click the + button
  • In the Select a flow Variable dialog, click the + button
  • Click the Connector Instance icon
  • Name the variable hubspot-origin
  • Click Save
  • Add a variable to associate with the Salesforce connector Instance by again clicking on the + button in the Select a flow variable dialog
  • Select Connector Instance
  • Name the variable salesforce-destination
  • Click Save
  • Select the hubspot-origin Flow Variable
  • Click Save
  • The Connector Instance Variable should now be populated with ${config.hubspot-origin}
  • Click Save

Build the flow

  • You should now be in the flow editor with the beginning of a flow on the pallet
    flow editor
  • The first thing you need to do is determine what type of event the connector picked up
  • Click the Add Step icon (blue plus)
  • Select JS Filter (true/false) as the flow step type.
  • Enter a name of isCreateContact
  • In the body of the code editor, enter
    let theEvent = trigger.event.eventType;
    let theObject = trigger.event.objectType;
    
    done((theEvent === 'CREATED') && (theObject === 'contact' || theObject === 'contacts'));
    

    This code inspects values within the inbound trigger event and returns true or false based on values of the eventType and eventObject. This example will evaluate to True if the event type is CREATED and the object type is contact or contacts.

  • The completed step should look like:
    Create JS Filter step
    Note: The function begin and end are supplied for you. You just need to supply the logic.
  • Click Save
  • Click on the isCreateContact step in the flow editor and select ADD ONSUCCESS
    select ADD ONSUCCESS
  • Select Connector API Request as the step type
  • Configure the step:
    Name: getNewContact
    Connector Instance Variable: ${config.hubspot-origin}
    Method: GET
    API: /myContacts/${trigger.event.objectId}
    Here you are defining the connector instance variable that will be used in this step. When we later create a flow instance from the template, this variable will be associated with a specific connector instance. The API call will retrieve the fields defined in the myContacts mapping for the ID with a value retrieved from the contact create event.
  • Click Save
  • Click on the getNewContact step in the flow editor and select ADD ONSUCCESS
  • Select JS Script as the step type
  • Configure the step:Name: buildEmailQueryParam
    Code:

    var email = steps.getNewContact.response.body.email;
    console.log(email);
    var urlEncoded = encodeURIComponent("name=" + "'" + email + "'");
    var encodedParam = "where=" + urlEncoded;console.log(encodedParam);
    
    done(encodedParam);

    We’ll use the contact’s email address as a unique identifier. So, we need to build a URL-encoded string that will be used as a query parameter in the next step. The script will return the value of encodedParam that can then be referenced in subsequent steps.

    buildEmailQueryParam

  • Click on the buildEmailQueryParam step in the flow editor and select ADD ONSUCCESS
  • Select Connector API Request as the step type
  • Configure the step:
    Name: queryDestinationContact
    Connector Instance Variable: ${config.salesforce-destination}
    Method: GET
    API: /myContacts?${steps.buildEmailQueryParam}
    The API call uses the output of the buildEmailQueryParam step as a query parameter to the /myContacts API.create Connector API Request step
  • Click Save
  • Click the queryDestinationContact step in the flow editor and select ADD ONSUCCESS
  • Select JS Filter (true/false) as the step type
  • Configure the filter:
    Name: isNewContact
    Code:

    var obj = steps.queryDestinationContact.response.body;
    if ((obj.length === 0) || obj[0] === null) {
     done(true);
    } else {
     done(false);
    }

    This filter will return True if the query in the previous step returns a null or empty result. This indicates that no contact with the given email address exists in the Salesforce instance. If a contact with the given email address does exist, then the filter will return False.

    isNewContact step

  • Click Save
  • Click on the isNewContact step in the flow editor and select ADD ONSUCCESS
  • Select Connector API Request as the step type
  • Click the SHOW ADVANCED button
  • Configure the step:
    Name: createNewContact
    Connector Instance Variable: ${config.salesforce-destination}
    Method: POST
    API: /myContacts
    Body: ${steps.getNewContact.response.body}
    This step will take the JSON object containing the contact fields defined in the myContacts mapping that was retrieved in the getNewContact step and pass it as input to the POST /myContacts API on the destination connector instance.
    CreateNewContact step

Complete the flow logic

This flow has two true/false filters where we have covered the True condition. We should add graceful exits to the False conditions and capture the output. I’m not sure if it’s necessary, but I have found it useful to understand why the filter evaluated to False when examining the flow instance execution trace.

  • Click on the isCreateContact step in the flow editor and select ADD ONFAILURE
  • Configure the step:
    Name: notCreateEvent
    Code:

    console.log("Not a CREATE event.");
    done(true);

    notCreateEvent

  • Click Save
  • Click on the isNewContact step in the flow editor and select ADD ONFAILURE
  • Configure the step:
    Name: notNewContact
    Code:

    console.log("Contact already exists.");
    done(true);

    nonNewContact

  • Click Save
  • The completed flow template should look like this:

completed flow template

Create a Flow Instance

Now that we have a complete flow template, it’s time to create an executable instance. This is where the Connector Instance Variables in the template will be associated with specific Connector Instances.

  • Navigate to the Flows tab in the Integration Builder UI. This will return you to your list of Flow Templates

flows tab

  • Hover over the HubSpotToSalesforce Flow Template tile and select CREATE INSTANCE
  • Name the instance Sync HubSpot Contact to Salesforce
  • Under Variables click the + button on the salesforce-destination tile
  • In the Connector Instance list, select Salesforce Out
  • Click the + button on the hubspot-origin variable tile
  • In the Connector Instance list, select HubSpot In
  • Click CREATE INSTANCE

Test the flow

Now would be a good time to set the polling interval of the HubSpot, in the instance of the HubSpot CRM connector to a low value if you haven’t done so already.

  • Navigate to the Instances tab in the Integration Builder UI
  • Click on the Instance Options (gear icon) for the HubSpot In Connector Instance

Click on the Instance Options (gear icon)

  • Select Edit
  • Scroll down to the Event poller refresh interval and move the slider to 1 (min).
  • Click UPDATE
  • In a separate browser tab, navigate to HubSpot at https://apps.hubspot.com and log in
  • Select Contacts from the HubSpot navigation menu
  • Click Create contact
    Email: bsmith@acmedemo.com
    First name: Bob
    Last name: Smith
    Job tile: Superhero
    City: Phoenix
    Country: US
    Street address: 6811 E Mayo Blvd
    Sate/Region: AZ
    Postal code: 85054
  • Click Create Contact
  • Return to the Integration Builder UI
  • Navigate to the Flows tab
  • Hover over the HubSpotToSalesforce tile and select EXECUTIONS
  • You should see at least one execution of the flow listed under Flow Executions
  • If you see more than one, click through the Flow Execution until you find one that shows a successful createNewContact step. You can click on each Step to view the associated input, output, headers, URI, etc. for that step. Available data depends on the type of step being viewed. This is very helpful for debugging and troubleshooting.
    flow executions

If you have a Flow Execution with a green createNewContact step, congratulations! Everything worked and you should have a new contact for Bob Smith in your Salesforce instance. If you get a red step, then it is time to do some troubleshooting. Click on the Steps to view their execution information and try to determine what went wrong.

In this blog, we demonstrated how to create Connector Instances and authenticate them against external services, define a custom Mapping to create normalized data model and build a flow to tie everything together. While this is a simple scenario, it provides an example that can be used in more complex situations.