How to: Create Connections and Recipes Using the Integration Gateway

Estimated Reading Time:  5 minutes

Overview

The Integration Gateway lets you integrate with over 700 systems across enterprise applications, databases, and legacy on-premise infrastructure—in the cloud or on-premise. To take advantage of these integrations, it requires creating connections and recipes, activating them, and using a Plug-In component to run them. This how-to guide teaches you how to create connections and recipes and run your integrations.

TIP  To learn how to access the Integration Gateway, view our Integration Administration article.

What You'll Learn

In this how-to guide, you'll learn how to create recipes, connections, and endpoints to run external integrations in Unqork.

Creating an Integration Using Integration Gateway

A few steps are involved when creating connections and recipes and running them:

1. Create a connection: First, you must connect to your external service to make any API calls using Unqork. This process requires an account and authorization credentials for that service.
2. Create a recipe: Recipes are workflow-like steps that perform actions. Recipes have many advanced features that can handle all application integrations and workflow automation scenarios, including conditional triggers, actions, and so on.
3. Define an endpoint for a recipe: To make an API call to an external service in your Unqork applications, you must establish an endpoint. You'll use this endpoint to make the call in a Plug-In component.
4. Configure a Plug-In component: Set up a Plug-In component to call your recipe's endpoint and perform the recipe's actions.

Creating a Connection

You must have accounts to all your external systems to create connections. For example, if you connect to Salesforce, you're prompted to log into your Salesforce account to complete the connection. After confirming your credentials, you can use the connection in a recipe to set up the integration.

To create a connection:

1. Open your Integration Gateway project.
2. Click Create ▾.
3. Select Connection.
4. Search for or select the supported connection you want to use.
5. In the Connection Name* field, enter a name for your connection.

TIP  It's a best practice to create a name that clearly defines the connection's purpose.

6. From the Auth Type* drop-down, select an authentication type.

NOTE  By default, OAuth 2.0 is selected.

7. From the Sandbox drop-down, determine if you want to set up this connection in a non-production sandbox.

TIP  Setting up a connection in a sandbox lets you test the connection without altering the live data.

8. Complete the remaining fields to authenticate the connection. These fields are specific to the external service.

TIP  If you are unsure how to configure the remaining fields, visit that external service's documentation.

9. Click Connect.

Below is an example of a configured connection:

A static image displaying a configured connection.

Creating a Recipe

With your connection set up, you can now build a recipe. A recipe works like an Unqork Workflow. You'll create a starting and ending point with steps in between. Recipes let you integrate your connections, set up triggers, and determine the actions and events you want to trigger.

Setting a Starting Point

To create a recipe:

1. Open your Integration Gateway project.
2. Click Create ▾.
3. Select Recipe.
4. In the Name field, enter a name for your recipe.
5. From the Pick a Starting Point* section, select Build an API Endpoint.

IMPORTANT  You must create an API endpoint recipe or the integration will not be available in Unqork.

6. Click Start Building.

Below is an example of a configured starting point:

A static image displaying a configured recipe starting point.

Configuring Actions

With the starting point set, you can create actions and link them to the connections. Actions are recipe steps that let you create, update, and search for data in a target application.

Using the button, you can add multiple actions, connecting them to your connection and Unqork. When your recipe is complete, click Save. Then, click Test Recipe to confirm it works correctly. Recipe actions include:

Action in an App

Performs a specific action in an application.

IF Condition

Performs an action when criteria are met and another action when not.

IF/ELSE Condition

Performs a different action if the specified criteria are not met.

Repeat Action

Performs the same action on each item of a list.

Call Function

These actions are called recipe functions. They let you call another recipe so you can reuse recipe logic.

Stop Job

Stops a job from processing. You can use this action to define a failed or successful job and end it.

Handle Errors

Lets you monitor for errors, make another job attempt, or notify a user.

Starting the Recipe

Before you leave your recipe, you must run it.

To start your recipe:

1. At the top of the Recipe Builder panel, click Save.
2. At the top right of the Recipe Builder panel, click x Exit.
3. Click Start Recipe.

Below is an image of a configured and running recipe:

A static image displaying a configured recipe.

Your recipe is now running and ready for use in Unqork. The final step is to create an endpoint for your recipe.

Creating an Endpoint

Next, you must create a usable endpoint for your recipe. Doing so lets you use a Plug-In component to run the recipe. You'll define your endpoint's path and HTTP method, set up timeouts, and determine how long the response is stored in the cache. Use the API Platform tab in the Integration Gateway to set up your endpoint.

To configure your endpoint:

1. At the top of the Recipe Builder, click the API Platform tab.
2. From the API Collections panel, select the Unqork Gateway collection tile.
3. Click + New Endpoint. A modal A modal is a window that appears on top of the content you are currently viewing. displays to configure your new endpoint.
4. In the Endpoint Name* field, enter a name for this endpoint.

TIP  It's a best practice to create a name that defines your endpoint.

5. From the Recipe* drop-down, select your recipe.
6. In the Endpoint Path* field, enter a unique path for your endpoint. For example, createSalesforceContact.
7. From the HTTP Method* drop-down, select the method for this endpoint.
8. Click Add Endpoint. You return to the API Platform page.

Below is an example of a configured endpoint:

A static image displaying a configured endpoint.

Before you can configure your API call in a Plug-In component, you must activate your endpoint. On your endpoint tile, set the Active toggle to (ON). You can now select the endpoint in a Plug-In component.

A static image displaying the activated endpoint.

Configuring a Plug-In Component

The final step is to configure your endpoint in a Plug-In component. These instructions assume that you have an open module saved with a title.

1. In the Module Builder, drag and drop a Plug-In component onto your canvas.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. and Canvas Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. fields, enter values that describe your Plug-In component.
3. To the left of the component's configuration window, click Data Icon Data.
4. Set External as the Service Type.
5. From the External Services drop-down, select the endpoint you created.

NOTE  On selection, the Data Source URL and Request Type automatically populate.

6. In the Inputs table, configure the specific fields you want.
7. Click Save & Close.
8. Save your module.

Below is an example of a configured Plug-In component:

A static image displaying a configured Plug-In component with an Integration Gateway endpoint selected as the External Service.

Resources