Okta Workflows Tutorial: Build a Connector for OpenWeather API

This tutorial will teach you how to build a connector for the OpenWeather API using the Okta Workflows Connector Builder.

• Connector for OpenWeather API
• What is the Connector Builder
• Build a connector for OpenWeather API
• Resources

Connector for OpenWeather API

You have several email notification flows you built in Okta Workflows. When you activate a user, you want to include weather information in the welcome email.

You want to use OpenWeather for weather information. There is no pre-built connector for the OpenWeather in Workflows today.

Several team members are unfamiliar with setting up API calls. To help them use OpenWeather, you will build a connector for the OpenWeather using the Okta Workflows Connector Builder.

A pre-built connector for OpenWeather will make adding weather information to flows and emails more straightforward.

What is the Connector Builder

Okta Workflows Connector Builder is a no-code tool to create API connectors. A connector will appear in the connector list, and you can use it to build identity automation flows.

The Connector Builder uses Workflows flows and cards (action, function) to build a connector.

Read Understanding Okta Workflows Connectors to learn about several API calling options in Okta Workflows and when to use which option.

A connector consists of several flows:

• A flow to make the HTTP request.
• A flow to check authentication to the service is working.
• One or more action flows. Each action flow calls a service’s API endpoint.
• Custom action flow to allow calling any API endpoint on the service.

A connector can have other flows, such as OAuth authentication. This tutorial will not cover OAuth authentication.

Note: Building a connector in the Connector Builder is an advanced topic. Complete the Getting Started tutorials first if you are new to Okta Workflows.

Build a connector for OpenWeather API

You need OpenWeather API key before you start building the connector.

Get OpenWeather API key

1. Create an OpenWeather account to get an API key.
   • It is usually faster, but the API key could take up to two hours to activate.

Go to API keys tab to view and manage your API keys.

You will use an API key from this page in the following sections.

Create a connector project

1. Click the four squares in the upper-right corner of Workflows and select Connector Builder.
2. Click I agree, let me in! to accept the Connector Builder terms.

Launch the Connector Builder.

3. Click + New Connector to create a connector project.
   • Click the ➕ in the left panel if you created a connector project before.
4. Enter OpenWeather for the Connector name.
5. Enter The OpenWeather connector provides weather information. for the Connection description.
6. Click Save to save the connector project.

You will see the connector’s Overview page.

Connector project.

You will return to this page later to set the connector’s icon and other information.

Connector flows and authentication

The connector you will build has five flows:

• httpHelper: manages all authentication and HTTP requests for the connector.
• authPing: checks connection health.
• Current: an action to get the current weather from the current weather API endpoint.
• Forecast: an action to get a five-day weather forecast from the 5-day forecast API endpoint.
• Custom API action: an action to call any API endpoint from OpenWeather API.

The connector also has Authentication.

Authentication is where you define the parameters required to create a secure connection to an API service.

When an end user creates a connection to your service, the New Connection dialog collects the specific authentication details.

There are three authentication types:

• Basic: uses username and password.
• OAuth 2.0: grants limited access to resources to a third party. You can use Authorization Code or Client Credential grant types in a connector.
• Custom: uses API key or other authentication process.

Create authentication for OpenWeather API

The OpenWeather API passes an API key in the request query for authentication. You will set up a custom authentication with an API key for the connector.

1. On the Overview page, click Set up authentication to create a connection.
2. Select Custom from the Auth Type list.
3. Click Add Parameter.
4. Enter the API Key for the Label.
5. Enter appid for the Key and keep Text for Type.
6. Click Save to save the connection information.

Setting up authentication.

The parameter name (key) is appid because the OpenWeather API call uses that name:

https://api.openweathermap.org/data/2.5/weather?q={city name}&units={units}&appid={API key}

Create a flow to make HTTP requests

You will create a flow named httpHelper.

The httpHelper is a system flow that manages authentication and HTTP requests for the connector. The httpHelper flow is a helper flow; other flows can call it. The flow has:

• Several inputs.
• Function cards to build request query, header, and body information.
• The HTTP – Raw Request card to make a call to an API.
• Several outputs.

Create a flow

1. Open the Flows page.
2. To create a flow click + New Flow.
3. Click Unnamed in the upper left corner to name the flow.
4. Enter httpHelper for the Flow name.
5. Enter This flow manages all authentication and HTTP requests for the connector. for the Description.
6. Check the Save all data that passes through the Flow? option.
7. To save the flow, click Save.

Set up flow inputs

1. Click Add event and choose Helper Flow.
2. Add the following fields on the Helper Flow card:
   • relative_url (type: Text).
   • request_method (Text).
   • query (Object).
   • headers (Object).
   • body (Object).

The httpHelper flow looks like this:

httpHelper flow.

Set up the API URL

The connector will support multiple OpenWeather endpoints. The base URL stays the same, and the relative URL will change. You need to combine the two values into a full URL.

1. Add the Text – Concatenate card after the Helper Flow card.
2. Enter https://api.openweathermap.org in the text 1 field.
3. Connect relative_url to the text 2 field.
4. Rename the card’s output field.
   • To edit the card, click ⚙️ > Edit card.
   • To rename the output field, click on its ✏️ icon and set the name to full_url.

Setting service URL.

To test the card:

1. At the bottom of the card, click ▶️.
2. Enter /data/2.5/weather relative URL for text 2.
3. Click Test to see the full URL: https://api.openweathermap.org/data/2.5/weather.

Set up the API query

As you did in the previous step, you must combine the user’s query information with the API key information.

1. Add the Object – Merge card after the Text – Concatenate card.
2. Connect:
   • query to object 1 field.
   • Connection to object 2 field.
3. Rename the output field to merged_query.

The flow looks like this:

Setting up service query.

Make an API call

You are ready to add a step to make the API call to OpenWeather.

1. Add the HTTP – Raw Request card after the Merge card.
2. Create the following connections:
   • full_url to the url field on the Raw Request card.
   • request_method to the method on the Raw Request card.
   • headers from the Helper Flow card to the headers field on the Raw Request card.
   • merged_query to the query field.
   • body to the body field.

The flow looks like this:

Setting up HTTP request.

You can test the HTTP – Raw Request card if you would like.

1. Click ▶️ to test the card.
2. For the url field, enter: https://api.openweathermap.org/data/2.5/weather
3. Enter GET for the method field.
4. For the query field, enter (replace the appid value with your OpenWeather API key):

{
    "q": "Rome, IT",
    "units":"metric",
    "appid": "89b03d9e1df4094dda81b5bc2b01ad5a"
}

4. Click Test to test the card.

The last step is to set up the flow outputs.

Set up flow outputs

1. Connect statusCode, headers, and body fields from the HTTP – Raw Request card to the Flow Control – Return card.
2. Change the body field type to Object.

httpHelper output.

Test the httpHelper flow

You created a flow with several inputs. One of the inputs is an OpenWeather API endpoint (relative_url). The flow calls the API endpoint and returns a response (statusCode, headers, and body).

It’s a good practice to test the flow.

1. To test the flow, click the Run button.
2. Select New connection from the Test Connection list.
3. Enter OpenWeather connection for the Name.
4. Enter OpenWeather API connection for the Description.
5. Enter your OpenWeather API key for the API Key.
6. Click Create.

You created a connection to OpenWeather API.

Next, provide the rest of the information for the flow input:

Input for the httpHelper flow.

1. Enter /data/2.5/weather for relative_url.
2. Enter GET for request_method.
3. For the query, enter with your OpenWeather API key:

{
    "q": "Rome,IT",
    "units":"metric"
}

4. Leave headers and body fields blank.
5. Click Run to run the flow.

Testing the httpHelper flow.

If you’d like, you can create a fake connection that will result in an error. The fake connection will help see how the connector works when authentication fails.

Fake connection.

You built and tested the httpHelper flow. Other connector flows will call the httpHelper flow.

The following section will teach you to create another system flow. This flow will check authentication to the service is working.

Create a flow to check for a valid connection

You will create a flow named _authPing. An _authPing flow is a system flow used by the platform to call an API and check for valid authorization.

This action acts as a validation check and runs when you first authenticate the connector, add new connectors, or open flows.

Create a flow

1. Return to the connector project view.
2. Click + New Flow from the Flows page.
3. Click Add event, and select the Authping event.
4. To save the flow, click Unnamed in the upper left corner.
5. Enter _authping for the the Name.
6. Enter Connection health check. for the description.
7. Check the Save all data that passes through the Flow? option.
8. Click Save.

New authping flow.

Add connection health check cards

1. Click Add function, and select Error Handling – If Error card.
2. In the Try block (automatically selected), click ➕, then function (calculator icon), and select the Flow Control – Call Flow card.
3. On the Call Flow card, click Choose Flow.
4. Select the httpHelper flow, and click Choose.

The flow looks like this:

authping flow with the Call Flow card.

This flow calls the httpHelper flow to check the connection to the service is working. You must use an API endpoint that requires authentication.

Note: The Okta Workflows team recommends a request with the smallest response size. For example, some APIs have a /me endpoint to get information about the logged-in user.

The OpenWeather doesn’t provide /me endpoint. You will use a regular request to check the connection’s health.

Finish configuring the Call Flow card:

1. Enter /data/2.5/weather for the relative_url.
2. Enter GET for the request_method.
3. For query, enter:

{
  "q": "Rome,IT"
}

4. Leave the headers and body fields blank. You also don’t need units in the query since this is only a ping request.
5. Connect the Connection field from the first card to the Connection field on the Call Flow card.

The flow looks like this:

authping flow with the Call Flow card set up.

To create outputs on the Call Flow card:

1. Click inside the Click or drag to create area and create the following output fields:
   • statusCode (type Number).
   • headers (Object).
   • body (Object).

Call Flow with outputs.

Next, you will set up a message when the connection is working and a message when the connection is not working.

To set up a message when for working connection:

1. Click the ➕ after the Call Flow card inside the If Error card and select the Flow Control – Assign card.
2. Add a message field and set it to The connection is successful value in the Control – Assign card.

Create outputs for the If Error card:

1. Click View Outputs in the If Error card (upper right corner). The card opens a section where you define the card’s outputs.
2. Click inside the field box and create two outputs:
   • statusCode.
   • message.
3. Create the following connections:
   • statusCode from the Call Flow card to the statusCode‘s first sub-field.
   • message from the Assign card to the message‘s first sub-field.

The card looks like this:

Set up a message when the connection is working.

To set up a message when the connection is not working:

1. Using the list where it says Try, switch to the If Error block on the If Error card.
2. Add two fields to the Error object:
   • statusCode (type Text).
   • description (Text).
3. Click ➕ to the right of the Error object inside the If Error block and add the Text – Concatenate card.
4. Create the following connections:
   • description from the Error object to the text 1 field.