How to: Retrieve a Payload Using an Unqork Connector

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 retrieve the entire payload of the Unqork Get Module Submissions 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 the Unqork Get Module Submissions' full payload.

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 Module Submissions.
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 Module Submissions. The configuration panel navigates to the Connection step.

A static image displaying the second step's Action page, the Get Module Submissions 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 moduleId Field to the Endpoint

Because you're retrieving a module's submissions using its module ID, you must map it from the TRIGGER step to the ACTIONS Setup step. Mapping this field lets you to pass the module ID value 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 moduleId.

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. Select the Icon Get Module Submissions in Unqork Customer API step and return to the Setup section.
7. Click the moduleId* field, the Recipe Data modal expands.
8. In the Recipe Data modal, navigate to the Request Parameters section.
9. Drag and drop the moduleId 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 moduleId* field.

Create the API Response

The third step in the recipe sets the response to Text/XML, and specifies what HTTP status code to display when retrieving data from the endpoint successfully.

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 Response* section.
6. From the Content Type* drop-down, select Text/XML.
7. Scroll to the Responses* section and click Add Response
8. In Name field of the Response #1 box, enter response.
9. 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.

Pass and Convert the Text/HTML Body 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. Hover over the Body field, the Text Formula button displays.
4. Click the Formula button. The Body field changes background colors and the Recipe Data modal expands.
5. From the Recipe Data modal, select the Payload 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 Body* field.
6. Select the Body field to the right of the Payload 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., enter .to_json. This formula converts the payload data to JSON.

7. At the top of the panel, click Save.
8. At the top right of the panel, click x Exit.
9. 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

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 Component

Configure a Text Field component for entering the ModuleID. This value inputs into the Plug-In component you'll configure in the next section.

1. In the Module Builder, drag and drop a  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. field, enter textModuleId
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 Module ID:.
4. Click Save & Close.

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 textModuleId  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 plugGetModuleSubmissions.
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 Module Submissions by eye dees endpoint.

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

textModuleId

moduleId
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 btnGetModuleSubmissions.
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 Module Submissions.
4. Set the Action Type to Event.
5. In the Trigger field, enter plugGetModuleSubmissions.
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 Module Submissions 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 payload 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