Extract External Data with an Integration Procedure

Learning Objectives

After completing this unit, you’ll be able to:

List potential external data sources for FlexCards and OmniScripts.
Summarize how data flows in an Integration Procedure that extracts external data.
Build a URL to pull external data with an API key.
Add external data to an Integration Procedure.

Introduction

External data includes all data from outside a Salesforce org. When you need data that is not in Salesforce, you use an external data source. Displaying external data on a FlexCard or an OmniScript is a common need for most implementations. External data sources include:

Legacy data sources
On-premises data sources
API integrations
Other third-party data and applications

Using a weather API is a great way to practice getting data via a web API. There are lots of use cases for weather since severe weather is an important factor for many industries. Examples include weather damage to homes (insurance) and service outages due to inclement weather (energy).

Various types of severe weather that affect different industries, like flood or hail damage for insurance companies, high wind damage to telecommunications towers, or fire dangers at a utility company.

This FlexCard contains the current and forecasted weather for an account’s location, determined by the billing postal code. The current temperature and location displays on the parent FlexCard, and a flyout modal displays the forecast for the next 5 days.

FlexCard flyout displays the forecast for the next 5 days in a modal, ranging from heavy snow to clear sky.

This OmniScript displays the current weather for the account’s location and shows alerts if there are any hazardous weather conditions.

An OmniScript displays the current weather and a Weather Alert of heavy snow for the Account’s location.

What if we told you that the FlexCard and the OmniScript are using the same Integration Procedure? What’s more, the same Integration Procedure retrieves internal and external data for the FlexCard and the OmniScript.

One of the reasons Integration Procedures are a best practice for retrieving data is their ability to extract data from multiple sources. It’s possible, for example, to extract data from your Salesforce org with one Integration Procedure element, then extract data from an external source with another Integration Procedure element.

When you want to extract data from an external source, use an API key to pull the data and then transform it before it returns to the tool (FlexCard or OmniScript) that called the Integration Procedure. In the weather example, you pull the account postal code, send it to Weatherbit.io to request both current and forecast data, and then edit and trim that data.

The steps in this module are for demonstration purposes only. OmniStudio is not enabled in Trailhead Playground orgs.

The Data Flow for Extracting External Data

How does this work? Let’s review the flow of data from a FlexCard or OmniScript to an Integration Procedure, and then through the Integration Procedure and back to the FlexCard or OmniScript.

A FlexCard or an OmniScript sends an AccountId to an Integration Procedure.

A FlexCard or an OmniScript sends an AccountId (1) to an Integration Procedure.

The Integration Procedure shares the AccountId with a DataRaptor Extract that extracts the Account Postal Code from Salesforce and returns it to the Integration Procedure.

The Integration Procedure passes the AccountId to a DataRaptor Extract Action element that uses a DataRaptor Extract to extract the Account Postal Code from Salesforce and return it to the Integration Procedure (2).

A Set Values element shares an API Key with two HTTP Action elements and the DataRaptor Extract element shares the Account Postal Code with them.

The Integration Procedure uses a Set Values element to hold an API Key. The Set Values element shares an API Key with two Hypertext Transfer Protocol (HTTP) Action elements. The DataRaptor Extract Action element shares the Account Postal Code with the two HTTP Action elements (3).

Two HTTP Action elements send the Account Postal Code and API Key to Weatherbit.io and receive weather data in return.

Both HTTP Action elements send the Account Postal Code (the account’s location) and the API Key to the Weatherbit.io site. One Action receives a JavaScript Object Notation (JSON) with the current weather, and the other receives a JSON with 5 days of forecast weather data (4).

The weather JSONs are sent to a DataRaptor Transform, which returns only a selected JSON.

Both the current and forecast weather JSON are sent to a DataRaptor Transform (5), which trims and transforms the data, returning only a selected JSON.

The selected JSON is sent to a Response Action element, which returns the selected JSON to the tool that called the Integration Procedure.

The selected JSON is sent to a Response Action element (6), which returns the selected JSON data to the FlexCard or OmniScript that called the Integration Procedure (7).

Pretty nifty, right? Now, in order to pull external data into your org from the Weatherbit.io website, you need an API key and you need to build a special URL.

Build a URL to Pull External Data with an API Key

Before you build URLs to pull weather data, you must get an API key. Create a free account on the Weatherbit.io website. Once signed in, locate your API key in the Master API Key field on the Account dashboard. Save it somewhere to use when you build the URLs, which you’ll do next.

On the Weather API Documentation page, locate the Current Weather API heading and click Swagger UI under that heading.

Swagger UI button on the Current Weather API section.

The Swagger UI Documentation page shows various methods to get the current weather data.

Link to Return an observation and Parameters fields.

Select the Returns a current observation by postal code link (1) and enter the required Parameters (2), including your API key.

Request URL generated.

When you finish entering the Parameters, click the Try it out! button (1) to generate a Request URL (2). You will use this URL in the current weather HTTP Action element.

Return to the Weather API Documentation page. Locate the Forecast API (16 day/daily) heading, and click Swagger UI under that heading. Select the Returns a daily forecast - Given a Postal Code link, and enter the required parameters, including your API key.

When you finish entering the Parameters, click the Try it out! button to generate a Request URL for the forecast data. You will use this URL in the forecast weather HTTP Action element.

Request URL generated for forecast data.

You’ve built your URLs, which means you’re ready to build your Integration Procedure!

Configure the Integration Procedure to Extract External Data

As you configure your Integration Procedure to extract data, take advantage of some of the other features in this powerful OmniStudio data tool.

Use a Set Values element to store the API key.
Configure the properties of the HTTP Action element to trim the JSON response.

It’s good practice to place the API Key in a Set Values element where it’s more visible, reduces calls to the client, and makes the Integration Procedure easier to maintain. Here’s how to add a Set Values element to store the API key.

Use a Set Values element to store the API Key.

Add a Set Values element (1) to the Structure panel of your Integration Procedure. Then use the Element Value Map section to save the API Key (2).

Once you have the key saved here, you replace the actual API key in the HTTP Action elements with %APIKey% (the name of the element in the Element Value Map).

If the API key ever changes, you need to edit only the one Set Values element. This makes it easier to maintain your Integration Procedure.

Speaking of making this easier, did you know you don’t need to pass on the entire JSON response that is sent from Weatherbit.io? That’s right! You can use the properties of the HTTP Action element to trim the data response.

HTTP Path and HTTP Method Properties of the HTTP Action element.

First, drag an HTTP Action element (1) to the Structure panel. Then, in the HTTP Path field (2), add the Request URL you built to get external data, and in the HTTP Method field (3) enter GET.

After defining the HTTP Path and Method, use the Response JSON Path field to trim the JSON response to share only the data node. Why would you want to do this? Because it focuses the Response JSON to only send the information in the data node to the next elements in the Structure panel.

Response JSON Path field in the HTTP Action element properties.

You’ve now simplified the data that is received in the HTTP Action elements. Keep on reading to learn how to trim and transform this external data into the format that you need and send it back to the FlexCard or OmniScript.