Connect a Workflow to an API Callout Library

This article provides a minimal worked example to demonstrate how to add an API Callout to a Workflow. It uses the {{Open Weather Map}} API as an example and assumes the API has already been set up and configured in the API Library.

When you setup a new Work Flow, it will look like this:

The Workflow Builder showing 3 sections:
left = drag and drop 'Activities' (all workflows have a 'start' and 'end' activity)
middle = the Workflow design & layout area
right = a properties window for the selected 'Activity'

Drag-and-Drop activities onto the design area

In this example the API takes an 'Argument' called {city}, and returns information about the weather in whichever city was 'passed' to the API. 

To achieve this we will drag-and-drop the following Activities to the Workflow:

1. User Activities > User Input (prompts user to enter a city)
2. Other Activities > API Callout (calls the API, gets raw data for the city)
3. User Activities > User Message (displays specific weather information)

Workflow Activities on the design canvas, before being connected to each other.  Each activity (except 'end') has a small grey square on it that can be dragged to other activities (the squares are easier to see when you hover over them). 

Link the activities

Once the Activities are linked together the workflow should looks something like:

Workflow with linked activities resembles flow-chart logic.

To achieve drag connectors from:

1. 'start' onto 'User Input'
2. 'User Input Cancel' onto 'end'
3. 'User Input Done' onto 'API Callout'
4. 'API Callout Exit' onto 'User Message'
5. 'API Callout Failure' onto 'end'
6. 'User Message Succeeded' onto 'end'

Setup the Workflow Variable for passing the {city} argument to the API

The Workflow needs to have a variable to pass to the API {city} argument, variables can be in the configuration options for the 'start' activity.  Once it is set up it should looks something like this.

Variables for the workflow are associated with the 'start' activity. 

To achieve this, navigate to the 'Variables' tab, then:

1. Click on 'New Variable'
2. Give the variable a Name (it does NOT have to be 'city')
3. Select 'string' as the variable type
4. Optionally, enter a 'default value'

Setup the User Input

The workflow needs to pass a 'city' to the API and since the API can check the weather in any city we thought it would be sensible to ask the user to enter a city. In this example when the workflow is run, a form will appear and the person who initiates the workflow (i.e. the 'Triggering Person' will be prompted to enter a city.

The city that the person specifies will be save to the variable called 'City'. 

User Input configuration.

To achieve this, select the User Input activity, and:

1. Click on the {{Tickbox}} for 'For Person' > 'Select Parameter' > choose: [Triggering Person]
2. For the Prompt type the text as shown (must include the 'single quotes')
3. From the 'Display As' drop down, select: Form
4. Associate the input with the variable 'City'

Setup the API Callout

Once configured the API Callout activity should look like:

API Callout configuration.To achieve this:

1. For 'API to call', click on the {{Tickbox}} and select the 'Open Weather Map'
2. For the 'City' input, click on the {{Tickbox}} and select 'Select Parameter' > choose 'City'
3. For the 'metric' input, click on the {{Tickbox}} and select 'Calculation' > type:  'metric' 

Setup the User Message

If the API call is successful it will return a response (similar to the one in the response template) AND we will want to display a message that includes the name of the 'city' and the current 'temperature'.

Message Text in the Calculation editor,  the user message will display something like:
"The temperature in Sydney is 19.420"

To achieve this:

1. Click on the {{Tickbox}} for 'Send To' and select  '[Workflow Initiator]'
2. Click on the {{Tickbox}} for 'Message Text' and:
   • type:  'The temperature in ' + 
   • click on the parameters button, select: 'City'
   • type:   + ' is ' + 
   • click on parameters button, select: 'API Callout.Response'
   • type:   .[main].[temp]