How to: Create an Unqork Connector Using the Integration Gateway

Overview

The Integration Gateway accelerates digital transformations by easily integrating with over 700 systems across enterprise applications and databases, including the Unqork API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.. This how-to guide provides you an example on how to configure the Unqork Get workspace application by workspace Id & application id endpoint using the Integration Gateway. After configuring the endpoint, you'll setup a Plug-In component to call it.

To learn more about the Integration Gateway, view our Integration Administration article.

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 Unqork environment to make API calls using the Integration Gateway. This process requires an account and authorization credentials for access to the Unqork API.
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 the Unqork service in your 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.

What You Need

Create a Connection

The first step when creating your Unqork recipe is generating Unqork Access Credentials using the API Access Management page. Then, you'll use the credentials to set up the Unqork connection in the Integration Gateway.

You must have an Unqork Administrator account to create access credentials.

Generate Unqork Access Credentials

This example connects the Unqork API to the Integration Administration recipe. To grant the recipe access to the Unqork API for your environment, create a Creator Access Credential in API Access Management. You'll insert these credentials into the recipe in the next section.

1. At the top right of the Unqork Designer Platform, click Settings ▾.
2. Select Administration.
3. Under Integration, click API Access Management.
4. On the API Access Management page, click + Create New ▾.
5. Select Creator Access Credential. The Create New Creator Access Credential modal A modal is a window that appears on top of the content you are currently viewing. displays.
6. In the Name* field, enter a unique name for the credential.
7. (Optional) In the Description field, enter a short explanation for how the access credential is used.
8. From the Select Creator Role(s)* drop-down, select the level of access the Custom Connector will use. For this how-to guide, select Administrator.
9. Click Generate Credential. The Client ID & Secret modal displays.
10. Copy the Client ID and Client Secret field values to a secure location. You'll use the Client ID and Client Secret values in a later step.

To maintain security, do not share credentials with other users.

Configure Your Unqork Connection

Access Unqork's Integration Administration page to configure the Unqork connection using the Integration Gateway.

To access the Integration Administration page:

1. At the top right of the Unqork Designer Platform, click Settings ▾.
2. Select Administration.
3. Under Integration, click Integration Administration.

Now, use the Integration Gateway to create an Unqork connection.

A static image displaying the Create drop-down to select a new connection.

1. Open your Integration Gateway project.
2. Click Create ▾.
3. Select Connection.
4. Search for and select the Icon Unqork Customer API connection tile.
5. In the Connection Name* field, enter a unique name for your connection.
6. In the Host* field, enter your environment address. For example, https://training.unqork.io/.

A static image displaying the creation of the Unqork connection.

7. In the Client ID* field, enter the value recorded during the Generate Unqork Access Credentials steps.
8. In the Client Secret* field, enter the value recorded during the Generate Unqork Access Credentials steps.
9. Click Connect. The Connection Status changes to Icon Connected.

Your connection is now established and active for use in your recipe. Next, you'll review how to create your recipe.

Create a Recipe

Recipes let you integrate your connections, set up triggers, and determine the actions and events you want to occur. For this how-to guide, you'll configure a recipe to retrieve specified Workspace Application fields from Unqork.

To create a recipe and designate a starting point:

A static image displaying the Create drop-down to select a new recipe

1. Open the Unqork project.
2. Click Create ▾.
3. Select Icon Recipe.

Configure a Starting Point

First, you must configure the starting point, or trigger, for your recipe. With the recipe page now open, configure the following fields:

1. In the Name field, enter a unique name for the recipe. For example, {{teamName}} - Get Workspace Application.
2. From the Location* drop-down, specify the project.
3. From the Pick a starting point* list, select icon Trigger from an App.

A static image displaying the creation of the Get Workspaces Application recipe.

4. Click Start Building. The recipe page loads.

Configure the Trigger

1. On the Recipe Canvas, under TRIGGER, click the icon Select an App and Trigger Event button. A configuration panel displays all your connected apps at the right of the page.
2. Under icon Choose an App, in the search field, enter API to filter the list.
3. Select icon API Platform by Workato. The TRIGGER step changes to icon New API request Real-time.

Configure the First Action

1. Under ACTIONS, click the (Add Step) button. A list of actions displays.
2. Click Icon Action in App. The configuration panel displays.
3. Under icon Choose an App, search for and select the Icon Unqork Customer API tile. The configuration panel navigates to the Action step.
4. Under Icon Choose an Action, search for and select Get workspace application by workspace Id & application id. The configuration panel navigates to the Connection step.

A static image displaying the second step's Action page, the Get Workspace Application Endpoint is selected.

Connect to the Unqork Customer API

Select the connection set up in the Configure Your Unqork Connection section. Doing so adds the Access Credentials to your API Request.

1. In the Connection step, search for and select the Unqork Connection created in the Configure Your Unqork Connection section.
2. Click Connect. The configuration panel navigates to the Setup step.

A static image displaying the second step's Connection settings, the Unqork API Access Credentials are selected.

Pass the workspaceId and applicationId fields to the Endpoint

Because you're retrieving a workspace's application using its Workspace ID and Application ID values, you must map them from the TRIGGER step to the ACTIONS' Setup step. Mapping these fields lets you to pass workspace and application ID values to the endpoint from inside a module.

1. Select the icon New API request Real-time TRIGGER step. The configuration panel displays.
2. On the Setup pane, navigate to the Request Schema section.
3. Click Add fields manually. The Add New Field modal displays.

A static image displaying the first step's Setup settings. The Request Schema section displays and the add fields manually link is highlighted.

4. In the Name* and Label* fields, enter workspaceIdIntegrationGateway.

A static image displaying the first step's Setup settings. The Add New Field modal displays, the name and label fields are filled.

5. Click Add Field. The field displays under the Request Schema section.
6. Click +Add Field. The Add New Field modal displays.

A static image displaying the first step's setup settings, the Schema Response's Add Field button is highlighted.

7. In the Name* and Label* fields, enter applicationIdIntegrationGateway.
8. Click Add Field. The field displays under the Request Schema section.
9. Select the Icon Get workspace application by Id & application id in Unqork Customer API step and return to the Setup section.
10. Click the workspaceId* field, the Recipe Data modal expands.
11. In the Recipe Data modal, navigate to the Request Parameters section.
12. Drag and drop the workspaceIdIntegrationGateway datapill Datapills are output data from a trigger or an action step. They are variables that you can use to map business logic into recipe steps. into the workspaceId* field.
13. Drag and drop the applicationIdIntegrationGateway datapill Datapills are output data from a trigger or an action step. They are variables that you can use to map business logic into recipe steps. into the applicationId* field.

Create the API Response

The third step in the recipe locates the response from the API request.

1. Under ACTIONS, click the  (Add Step) button. A list of actions displays.
2. Click Icon Action in App. The configuration panel displays.
3. Under icon Choose an App, search for and select the icon API Platform by Workato tile. This step changes the action to icon RETURN API Response and the configuration panel navigates to the Setup step.
4. Return to and select the icon New API request Real-time TRIGGER step.
5. From the right-menu, scroll to the Responses* section.
6. Click Add Response.
7. In Name field of the Response #1 box, enter response.
8. From the HTTP status code* drop-down, select 200 - OK. Whenever the API successfully returns the response values, this status code displays.

To learn more about response codes, view our HTTP Status Codes article.

A static image displaying the first step's API Response settings. The Name and HTTP Status Code fields are filled out.

Add the Response Schema

Use the Response schema fields to return specific values from the Get workspace application by workspace Id & application id endpoint. For this example, use Unqork's API documentation to find and copy the JSON definition.

1. Under Response Schema, select Use JSON. The Generate Schema modal displays.
2. Open a new browser tab and navigate to your Unqork environment's API documentation. For example, https://training.unqork.io/#/apidocs.
3. In the Search Bar, search for and select Get workspace application by workspace Id & application id. The page displays the endpoint and response samples.
4. Under Response Samples, click Copy. The JSON definition copies to your clipboard A place on your operating system that stores recently copied content. The clipboard only stores one item at a time..

A static image displaying the envrionment's API docs. The Get Workspace application by workspace id & application id endpoint is selected.

5. Return to the Generate Schema modal and paste the clipboard data into the JSON Sample code box.
6. Click Next. The Review Data section displays the JSON definition for review.

A static image displaying the Generate Schema modal's Review data tab.

7. Click Generate Schema. The modal closes, and the JSON definition's fields are added to the icon New API request Real-time TRIGGER step's Response Schema box, and to the Recipe Data modal.

Set the Settings and Promotions Fields to Optional

For this example, not all fields from the JSON definition are required. Edit the Response Schema to remove the promotions and settings fields.

1. Under Responses* in the Response Schema box, navigate to and mouse-over the Promotions* field.
2. Click the  icon (Edit) button. The Edit Field modal displays.
3. From the Optional* drop-down, select Yes.
4. Click Save. The Promotions field no longer displays the * (Required) symbol.
5. Repeat this process for the Settings* field.

Pass the JSON Fields to the API Response Step

Now that your Recipe has a Response schema, add the response fields to the API Response's Setup step.

1. Select the icon RETURN API Response step. The configuration menu displays the Setup settings.
2. From the Response* drop-down, select response. The Response body* box displays below.
3. Select the Created* field. The Recipe Data modal expands.
4. From the Recipe Data modal, under Payload, select the Created datapill Datapills are output data from a trigger or an action step. They are variables that you can use to map business logic into recipe steps. and drag it onto the Response Body's Created* field.
5. Repeat this process by matching the Payload datapills Datapills are output data from a trigger or an action step. They are variables that you can use to map business logic into recipe steps. to the rest of the fields: Created by, Description, ID, Modified, Modified By, Name, Title, Type, Workspace ID.
6. At the top of the panel, click Save.
7. At the top right of the panel, click x Exit.
8. Click Start Recipe.

The recipe is now running and ready for use in Unqork. The final step in the Integration Gateway is to create an endpoint for the recipe.

Configure Your Endpoint

In order to use your recipe in a Plug-In component, you must create an endpoint in the Integration Gateway. Once created, it displays in the Plug-In component's External Services drop-down.

To configure your endpoint:

1. At the top left of the Recipe Builder, click the API Platform tab.
2. From the API Collections panel, select an existing API Recipe collection.
3. Click + New Endpoint. The Add New Endpoint modal displays.
4. From the Recipe* drop-down, search for and select your recipe's name.
5. From the HTTP Method* drop-down, select the method to use for this endpoint. In this case, leave it as the default GET.
6. In the Endpoint Name* field, enter a unique name for this endpoint. For example, Get Workspace Application. This value displays in the Plug-In component's External Services setting.
7. In the Endpoint Path* field, enter a unique path for your endpoint. For example, getWorkspaceApplication.

A static image displaying the Add New Endpoint modal with it's completed fields to get a workspace application in Unqork.

8. Click Add Endpoint. You return to the API Platform page and the new endpoint tile displays at the top of the page.
9. On the endpoint tile, click the ··· (options) button.
10. Select Activate Endpoint. The endpoint's status changes from Never Active to Active.

You endpoint is now active, so you can select it in a Plug-In component.

Configuration

The last step of the process is to configure a module to retrieve Unqork application data using the endpoint. These instructions assume you have a module saved with a title.

Configure the Text Field Components

Configure two Text Field components for entering the Workspace ID and Application IDs. These values input into the Plug-In component.

1. In the Module Builder, drag and drop two  Text Field component onto the 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 the following:.
Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. Label Text

textWorkspaceId

Workspace ID

textApplicationId

Application ID
3. Click Save & Close for each component as you complete it.

Configure the Plug-In Component

Add a Plug-In component to use your new Integration Gateway endpoint and retrieve your workspace application.

1. Drag and drop a Plug-In component onto your canvas, placing it below the textApplicationId  Text Field component.
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 plugGetWorkspaceApplicationByIds.
3. Under Data, set the Service Type to External.
4. From the External Services drop-down, select the endpoint you created.

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

A static image displaying the Plug-In component's configuration window with the selected Get Workspace Application by eye dees endpoint.

5. In the INPUTS table, enter the following:
Property ID Mapping

textWorkspaceId

workspaceIdIntegrationGateway

textApplicationId

applicationIdIntegrationGateway
6. Click Save.

Configure the Button Component

Next, add a Button component to trigger the Plug-In component.

1. Drag and drop a Button component Icon Button component onto the canvas, placing it below your Plug-In component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter btnGetWorkspaceApplication.
3. In the 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. field, enter Get Workspace Application.
4. Set the Action Type to Event.
5. In the Trigger field, enter plugGetWorkspaceApplicationByIds.
6. Click Save & Close.
7. Save your module.

View the API Response In Console

Now that you've built your endpoint and created a module that can call it, verify the endpoint works correctly.

1. Preview your module in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View..
2. In the Workspace ID and Application ID fields, enter a workspace and application ID from your environment.
3. Click the Get Workspace Application button.
4. In the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software., use the Angular Command to inspect the submission data.

The Plug-In retrieves the fields specified in the Pass the JSON Fields to the API Response step.

A static image displaying the submission data. The Plugin data displays the fields set by the Integration Administration endpoint.

Resources