Geocode New Salesforce Accounts using Axway’s AMPLIFY Integration Builder: Part 2

In Part 1 of this blog post series, we created an Integration Builder flow that was detected when a new Salesforce account is created and we populated its GPS coordinates. This enables developers to create richer applications that can display Salesforce accounts on a map and provide routing details, for example.

In part 2, we’ll enhance the flow as follows:

• Use a Webhook for the connector instead polling so that our flow will execute when a new Salesforce Account is created and we’re not having to make endless API requests to SFDC to check for account activity
• Use a Data Model so the SFDC field names don’t need to be hard coded in the flow. This is particularly important for the Geocode field names as they will definitely be different for each user/SFDC instance but it also makes the flow more reusable with other CRM applications
• Use the OpenCage connector we created in this blog post so we’re not hard coding the OpenCage API Key and we’re authenticating and calling it programmatically instead of using HTTP Request step

Webhook Setup

Instead of polling, some back ends can be configured for webhooks to notify your application when some event occurs. Both Salesforce and Integration builder support webhooks so let’s use webhooks instead of polling.

• Setup Salesforce for webhooks as follows:
  • Via a web browser, log in to your Salesforce account
  • In the Quick Find box, type Remote Site Settings
  • Click New Remote Site
  • Create a remote site for the following URL:
    • https://staging.cloud-elements.com:

• When creating the Integration Builder Salesforce Sales Cloud connector, do the following:
  • Enable events and set the type to webhook
  • Enter https://staging.cloud-elements.com for the Event notification callback URL
  • Enter something for the Callback Notification Signature Key (e.g. 12345)
  • End Account for the Objects to Monitor for Changes

• Click the CREATE INSTANCE button to create an instance. I named mine SF Account Added Webhook.

We’ll use this Instance as an Event trigger for our flow.

Data Mapping

Data Mappings can be used to create a normalized data model for use within Integration Builder. This makes the Integration Builder flow more reusable as it is not using hardcoded field names tied to a particular back end application (e.g. Salesforce). For example, the custom geocodes fields for lat and lon are very specific to an individual or organization’s Salesforce instance. It is useful to use data mapping for these fields and for the address fields, and all fields, in general.

The Basic idea is to create a data map for accounts with desired field names that I’ll use in my flow and then attach a connector to the map and describe how the fields map between the data map field names and the connector instance account field names. Then in the flow, reference the data map field names and endpoint instead of the connector field names and endpoint in Connector Calls, etc… For example use /AccountToGeocode instead of /Account for the API PATH for the API call to GET a Salesforce account and city instead of ShippingCity for the field name.

Follow the online docs for Create a Mapping in the UI to create a data map below called AccountToGeocode for the Salesforce instance SF Account Added Webhook.

Detailed, step-by-step instructions and screenshots of creating a Data Map can be referenced in the blog post Create a Simple Integration Builder Flow.

A screenshot of my Data Map is shown below:

You can my normalized fields names are:

• city
• country
• lat
• lon
• state
• street
• zip

The corresponding Salesforce Account field names are:

• ShippingCity
• ShippingCountry
• lb_sftest__Geocode__Latitude__s
• lb_sftest__Geocode__Longitude__s
• ShippingState
• ShippingStreet
• ShippingPostalCode

The Path for API calls is /AccountToGeocode instead of /Account as mentioned earlier.

You can also see that my Connector Instance Transformation includes my Connector Instance SF Account Added Webhook.

Use the OpenCage Connector

In this blog post we created a connector and connector instance for the OpenCage Geocode API.

So, instead of using the HTTP Request step to get the GPS coordinates in the flow, we’ll use an API Request step. This is similar to how we retrieve the new account from Salesforce.

Create an OpenCage Connector as described here or import the connector exported JSON here. Either way, create an instance using your OpenCage API Key.

Flow

I create a new flow called SF New Account Geocode v2. It has two Connector Instance variables called sfdc-in and geocoder, which we need to add for our Salesforce and OpenCage connector instances.

The completed flow is shown below:

Notice that from this view, it is virtually the same as before except that getGPS is a API Request instead of an HTTP Requeststep and instead of a prepareURL step prior to getting the GPS coordinates, we have a prepareQuery step to prepare the Query parameter based on the account address.

Inside some steps, the JS has changed since we now reference data map fields and not Salesforce account fields.,

Let’s dive into the differences.

getNewAccount Step

You can see how we’re calling the mapped API Path /AccountToGeocode/${trigger.event.objectId} instead of /Account/${trigger.event.objectId}. This will return the account data with the mapped field names.

isGPSPopulated Step

In this step, you can see how we’re accessing the account’s latitude and longitude fields using the data mapped fields names, lat and lon.

The Javascript for this step is below:

var account = steps.getNewAccount.response.body;
let lat = account.lat;
let lon = account.lon;
console.log(lat);
console.log(lon);
done(!lat  && !lon);

isAddressAvailable Step

In this step, you can see how we’re accessing the account’s address fields using the data mapped fields names (city vs ShippingCity).

The Javascript for this step is below:

var account = steps.getNewAccount.response.body;
let addressExists = account.street && account.city && account.state && account.zip && account.country;
console.log("addressExists = "+addressExists);
if(addressExists) {
  done(true);
} else {
  done(false);
}

prepareQuery Step

Instead of a prepareURL step that we had before, we only need to prepare the query for the Connector API call.

The Javascript for this step is below:

var account = steps.getNewAccount.response.body;
let address = encodeURIComponent(account.street) + ',' + encodeURIComponent(account.city) + ',' + encodeURIComponent(account.state) + ',' + encodeURIComponent(account.zip) + ',' + encodeURIComponent(account.country);
let query={
  query:address
}
done({query:query});

getGPS Step

getGPS is now an API Request Step instead of an HTTP Request step.

The Query which was calculated in the step above is referenced as ${steps.prepareQuery.query}

constructBody Step

The last difference is the constructBody step. In this step, you can see how we’re using the data mapped fields.

The Javascript for this step is below:

var gps = steps.getGPS.response.body;
let body={
    lon: gps[0].geometry.lng,
    lat: gps[0].geometry.lat
}
done({body:body});

Flow Instance

Now we can create a flow instance and attach our connectors as shown below:

Create a new account in Salesforce and make sure you fill out the Shipping Address fields fully and after saving, click refresh once or twice and you will magically see the GPS coordinates get populated (by our Integration Builder flow).

Summary

In this blog post, we leveraged the power of Integration Builder to enhance our Salesforce Account Geocode flow to use webhooks instead of polling, use Data Mapping to make the flow more reusable and use an OpenCage connector instead making direct HTTP requests to the OpenCage API.