API Builder

Integration Builder – Connector Request Triggered Flow Example

Axway Integration Builder – Variable Persistence

Often, Integration Builder flows are triggered by an event received from an Integration Builder connector based on polling or a webhook from a change in a SaaS (Software as a Service) application. For example, the connector can be configured to detect when a Hubspot contact is added and then cause an event-triggered flow to copy the contact from Hubspot to Salesforce as described in this blog post: Create a Simple Integration Builder Flow

However, what if we’d like to expose an API to a SaaS application (like Hubspot) so that when a POST is made to the API (e.g. to create a contact), a flow is triggered to copy the contact to Salesforce. This alleviates the need and cost of polling and circumvents the fact that Hubspot (and other SaaS applications) might not support webhooks.

In this post, we’ll basically replicate the blog post – Create a Simple Integration Builder Flow – but use a Connector Request Trigger instead of an Event Trigger.

Since Integration Builder is part of the Axway AMPLIFY Platform, we’ll take advantage of another component – AMPLIFY Central – to expose the API in a secure, governed fashion.

Here is what we’ll accomplish in this blog post:

  • Create a Salesforce Connector Instance in Integration Builder
  • Create a Hubspot Connector Instance in Integration Builder, which we’ll expose in the AMPLIFY Central Catalog
  • Use AMPLIFY Central to add API Key authentication and create an app and get an API key to use for API calls
  • Create an Integration Builder flow that is triggered by a Connector Request (the Hubspot connector instance)
  • The flow will do the following:
    • Make sure the POST to contacts succeeded and that a new Hubspot contact was created
    • Check that the contact doesn’t already exists in Salesforce
    • POST the contact to Salesforce
  • Test out the flow

Pre-requisites

We’ll need access to the following, which are all available for free/trial:

  • Salesforce access
  • Hubspot access
  • AMPLIFY Integration Builder access
  • AMPLIFY Central access

Refer to other Integration Builder blog posts, videos and documentation for some background, as we will not cover every aspect in detail since they are already covered or documented here:

Let’s get started.

Create a Salesforce Connector Instance

Create a Salesforce Sales Cloud Connector instance and don’t enable events. We will use this connector instance to check if the contact exists and write our contact to Salesforce.

Create a Salesforce Sales Cloud Connector instance

Make sure you can create a contact and, in general, exercise the APIs through the API Docs.

Create a Hubspot Connector Instance

Use your Hubspot API Key and authenticate a new Hubspot Connector instance using API Key authentication. Don’t enable events, since we’ll be calling this directly and triggering a flow based on a POST to contacts.

Authenticate a new Hubspot Connector instance

Make sure you can create a contact and, in general, exercise the APIs through the API Docs.

Integration Builder Connector Instances appear in the AMPLIFY Central API Proxy automatically. This will allow us to secure, govern, expose and monitor API usage.

Add API Key Authentication in AMPLIFY Central

We need to expose the Hubspot connector instance from Integration Builder above to the AMPLIFY Catalog and get API Keys to call the API.

You can learn about publishing to the Unified Catalog and creating an app and API Key on the online documentation. The specific video is called Publishing to the Unified Catalog of the AMPLIFY Platform.

Screenshots are shown for reference:

    • Hubspot Connector Instance in Integration Builder:Hubspot Connector Instance
    • Hubspot API Proxy Appears Automatically in AMPLIFY CentralHubspot API Proxy in AMPLIFY Central

      Note that I enabled API Key authentication for this proxy. I also added this API Proxy to the Catalog.
    • AMPLIFY Central App created in order to subscribe to the API in the Catalog and to get an API KeyAMPLIFY Central App created

      Note that I subscribed this app to the Hubspot API in the Catalog.

 

  • Hubspot Connector in the AMPLIFY CatalogHubspot Connector in the AMPLIFY Catalog

 

We are now ready to create our flow.

Create an Integration Builder Flow

Create a new Flow and select Connector Request for the Trigger. You will be prompted for a connector instance variable name, which will be created during this process as well as the API method (POST) and the path (/contacts) as follows:

Select Connector Request

Create another Connector Instance variable for the Salesforce connector. I named mine sfdc as shown below:

Create another Connector Instance variable for the Salesforce connector

My entire flow is shown below:

Entire flow

It is worth noting the following about the Trigger step in our flow:

  • trigger.request.body contains the contact details from the Hubspot Connector API POST body, e.g.:
    {
      "properties": {
        "email": "a@test.com",
        "firstname": "Leor",
        "jobtitle": "CEO",
        "lastname": "Brenman"
      }
    }
  • trigger.response.body will have the response sent to the Hubspot Connector API POST requestorThis is a good new account POST response:
    {
      "vid": 1501,
      "raw": {
        "vid": 1501,
        "isNew": true
      }
    }

    A valid POST but a duplicate contact has the following response:

    {
      "vid": 1501,
      "raw": {
        "vid": 1501,
        "isNew": false
      }
    }

    Note that we’ll check isNew to make sure the contact is new before writing to Salesforce.

  • trigger.response.code contains the response code, e.g. 200
    Note that we’ll also check the response code to make sure the POST was successful.

Let’s review each of the steps. It is worth noting that for best practices, we should use a data model but to keep it simple, we won’t.

isValidCreate JS Filter Step

The first thing we should do is make sure that the POST processed properly and that the contact is a new contact as follows:

if(trigger.response.code == 200 && trigger.response.body.raw.isNew) {
  done(true);
} else {
  done(false);
}

invalidCreateLog JS Script Step

This step simply writes to the console for debugging purposes

console.log('Not a valid contact create');

buildEmailQueryParam JS Script Step

Before we post to Salesforce, we should make sure the contact doesn’t already exist by make a contact GET with a where clause:

where=Email='{email address of new Hubspot contact}’

e.g. Email=’barr_tim@grandhotels.com

We’ll create the where clause in this step as follows:

var email = trigger.request.body.properties.email;
var urlEncoded = encodeURIComponent("Email="+"'"+email+"'");
var encodedParam = "where=" + urlEncoded;
done(encodedParam);

queryDestinationContact API Request Step

In this step, we’ll make a call to Salesforce to check if the contact exists using the where clause from the prior step. The configuration of this step is shown below:

  • Connector Instance Variable: ${config.sfdc}
  • Method: GET
  • API: /contacts?${steps.buildEmailQueryParam}

isNewContact JS Filter Step

In this step we’ll check the response to see if it’s empty (i.e. contact does not exist)

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

notNewContact JS Script Step

This step simply writes to the console for debugging purposes

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

constructPostBody JS Script Step

In this step, we’ll create the body for the POST to Salesforce as follows:

var newContactSource = trigger.request.body;
var newContactDest = {
  FirstName: newContactSource.properties.firstname,
  LastName: newContactSource.properties.lastname,
  Email: newContactSource.properties.email,
  Title: newContactSource.properties.jobtitle

}
done(newContactDest);

createNewContact API Request Step

In this step, we POST the contact to Salesforce. The configuration of this step is shown below:

  • Connector Instance Variable: ${config.sfdc}
  • Method: POST
  • API: /contacts
  • Body: ${steps.constructPostBody}

Test Out Our Flow

To test our flow, let’s create an instance of the flow we created and attach our two connectors as follows:

Create an instance of the flow

Let’s review our Hubspot contacts and Salesforce contacts shown below:

Review our Hubspot contacts

Review our Salesforce contacts

Let’s use curl to call our Hubspot API in AMPLIFY Central.

I’ll use the following body for the POST:

{
  "properties": {
    "email": "string",
    "firstname": "string",
    "lastname": "string"
  }
}

The curl command is shown below:

curl -X POST \
  https://test-e4f77ce669fd0b1a016a22c82f8013c9.apicentral.axwayamplify.com/hubspotcrm_169601-/contacts \
  -H 'Authorization: Apikey 9c92a6b5-0e03-41a4-b576-1b325d1b182e' \
  -H 'Content-Type: application/json' \
  -d '{
  "properties": {
    "email": "a@test.com",
    "firstname": "John",
    "lastname": "Doe"
  }
}'

You can view your Flow’s execution and see a successful run as follows:

View your Flow's execution

We can also see that John Doe is in both Hubspot and Salesforce as shown below:

See that John Doe is in Hubspot

See that John Doe is in Salesforce

Additional Testing

To make sure our flow is robust, let’s run the following two tests:

  • Repeat the exact same curl as above and make sure the flow detects that the Hubspot contact already exists. The response to the curl command was:
    {
      "vid": 3301,
      "raw": {
        "vid": 3301,
        "isNew": false
      }
    }

Our flow handled this use case properly:

  • Delete the Hubspot contact and repeat the same curl command and make sure the flow detects that the SFDC contact already exists.

This time, we’ll successfully create a new contact in Hubspot, but the flow will not POST it to Salesforce because the contact already exists there:

We can use AMPLIFY Central to view analytics of our API calls in the API Observer tab as shown in the screen shots below:

View analytics of our API calls in the API Observer tab

View analytics of our API calls in the API Observer tab

View analytics of our API calls in the API Observer tab

Summary

In this blog post, we saw how to create an Integration Builder Connector Request triggered flow example. This enables us to have the flow triggered when a POST is made to the Hubspot contacts connector that is created in Integration Builder but exposed, secured, monitored, and governed in AMPLIFY Central.

The flow for this blog post can be found here.