Overview
The Plug-In component connects a module to internal and external API services for passing data to and from a chosen source.
To make an external API call with a Plug-In component, set up the API service in Unqork's Services Administration. Doing so requires you to reference the external service's API documentation. Once the service is set up, the API call becomes available to use with the Plug-In component.
To learn more about Services Administration, view our Services Administration article.
You'll find the Plug-In component in the Data & Event Processing group to the left of the Module Builder.
Remote Executing Your Plug-In Component
It's best practice to configure your Plug-In component to remote execute. Remote execute, or server-side execution, lets the Plug-In component execute the call outside of the browser. Running APIs in the browser is not secure. If the API call happens in the browser, malicious agents can access the data in the DevTools Console—including accessing PII (personally identifiable information) and inject malware.
The benefits of using remote execute are:
Speed: Back-end services handled by a remote server ease the burden on the browser.
Security: No one can use the DevTools Console to access PII.
Debugging: Modularization provides a smaller code-base for debugging.
To learn more about the DevTools Console, view our Access Submission Data Using the DevTools Console article.
What You'll Learn
After completing this article, you’ll know when to use a Plug-In component, how to configure its settings, and how to use it in an Unqork application.
About the Configuration Window
To learn more about general component settings and those that display when a component is associated with Data Models, view our General Component Settings article.
Display Panel
Field Text
Setting | Description |
---|---|
Label Text | Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. User-friendly labels make your module more accessible. Keep labels short and descriptive (a word or two) using title case. For longer entries, use sentence case. |
Data Panel
Data Storage
Service Type
The Plug-In component can be used for making internal Unqork API calls and external API calls.
Unqork
Selecting this option provides you with an Internal Services drop-down.
Setting | Description |
---|---|
Internal Services | Shows all internal Unqork services available for use. After selecting a service, the Request Type and Data Source URL autofill. |
Pre-Request Transform | This setting only displays for certain internal services. In the Pre-Request Transform drop-down, you can select a transform to perform on the submission. The transformed output creates the request body passed to the API call. |
Module/Workflow | If you are making a call to a module or workflow, a Module or Workflow drop-down displays, so you can select a specific module or workflow. |
Data Source URL | For an API to retrieve data, you need the API's URL information. In this field, enter the API information as obtained from the API documentation. Add additional filters at the end of the URL if you want to drill down to a specific type of data. |
.jpg)
External
Selecting this option provides you with an External Services drop-down.
Setting | Description |
---|---|
External Services | Shows all services already configured in Services Administration. After selecting a service, the Request Type and Data Source URL autofill. |
Data Source URL | For an API to retrieve data, you need the API's URL information. In this field, enter the API information as obtained from the API documentation. Add additional filters at the end of the URL if you want to drill down to a specific type of data. |
Request Type
The Request Type is automatically selected after you've completed the Service Type settings. The Plug-In component includes five Request Types.
Get: Retrieves and reads existing resources, like submission data.
Patch: Partially updates existing resources.
Post: Creates new resources.
Put: Updates existing resources.
Delete: Deletes resources.
If Patch, Post, or Put are selected, two new toggles display:
Setting | Description |
---|---|
Make a MultiPart API Call | Multipart API calls combine one or more sets of data into a single body. Multipart requests are common for file uploads and for transferring multiple data types with a single request. Set this toggle to |
Alternative Multipart Sub-Type (Services) | The Alternative Multipart Sub-Type (Services) field is only available for external APIs, but can be used to specify whether the parts of your request are related, mixed, or otherwise correlated. |
Promote Object/Array to Top Level | Use this setting to call an object or array, and make it the body of the API request. When the Promote Object/Array to Top Level toggle is set to |
Object/Key Array | In this field, enter the key of the object or array that you're promoting to the top level. |
Inputs Table
Use these fields to enter inputs as references for your logic components. These references include values you want to send as part of the API call's request header or body. For example, when getting module submission details for a dashboard, you need to enter the fields that you want to pull from the source module.
There is a 50 MB limit for all request payloads to internal services in Unqork.
Setting | Description |
---|---|
Property ID | Examples of supported inputs include:
|
Mapping | API documentation includes mapping information. Mapping information tells your Plug-In component which data to send or retrieve from the API call. In the case of SendGrid integration, the Mapping column indicates where the Property ID values show up in the email. If you enter '[email protected]' in the Inputs table's Property ID and from.email in the Mapping column, your From address is [email protected]. |
Required | When |
Exclude | When selected, the Plug-In component doesn't pass the field as part of your API call's request body. But, the Plug-In component can still watch for changes made to the value. |
Header | When selected, the Plug-In component passes the field as part of the API call's request header. When clear, the Plug-In component passes the field as part of the request body. |
Resolvebase64 | Select this setting if you're expecting a Base64 file from your API request. Selecting this setting prepares the system for the Base64 file, making it easier to convert the file. |
Optional | When selected, the Plug-In component doesn't pass the field in the API call's request body if there's no value (null). By default, the Plug-In passes every Input in the request body, even if the field is empty (null). |
Outputs
Use the Outputs table to send the data retrieved by the API call to a specific location.
Setting | Description |
---|---|
Property ID | For your logic component to recognize an output, you must enter the destination component's Property ID(s). The Property ID entered must match the Property ID of the component that acts as the output. Remember, use camel case without spaces or punctuation. |
Mapping | Map Property IDs according to the API's documentation. Mapping tells your Plug-In component what to retrieve from the API call. For the Outputs table, map specific data to put into your output components. |
Option | This setting offers handling methods for your outputs:
|
Header | When selected, the Plug-In component looks for the output value in the response header. When clear, the Plug-In looks for the field in the response body. |
Actions Panel
Triggers
Setting | Description |
---|---|
Trigger Type | This setting provides the following options:
|
Concurrent Trigger | Enter the Property ID of the component to trigger concurrently when the Plug-In component makes the API call. |
Post Trigger | Enter the Property ID of the component to trigger after the Plug-In completes the API call. For example, triggering a component to display the data received from the Plug-In component's API call. |
Error Trigger | Enter the Property ID of a component to trigger on failure of the API call.
|
Set Timeout | The number of milliseconds that pass before the API call times out. If an API call doesn't respond within a reasonable time, you don't want the Plug-In component to continue to wait. Unresponsive API calls can stall your entire application. The maximum timeout is 120,000 milliseconds. |
Set Retry Delay | The number of milliseconds that pass before the component tries the API call again after it failed. Waiting before retrying an API call could give the destination server time to clear the issues that caused it to be unresponsive. The maximum delay is 10,000 milliseconds.
|
Set Number of Retries | The number of retries the Plug-In component makes on a failed API call. It's best practice to limit the number of retries, so a continually failing API call doesn't stall your application. Use this setting to limit the number of times the Plug-In component retries the failed API call. If the API call fails all retries, the Error Trigger fires. The maximum number of retries is 10.
|
Disable Execution | If Disable Execution is set to By default, this setting is set to |
.jpg)
Advanced Panel
Setting | Description |
---|---|
Set Debounce | The number of milliseconds that pass before the module loads this component. This is useful if you have a large module and you load several components at the same time.
|
Show Modal Dialog While Running | When set to
By default, this toggle is set to |
Show Cursor as Spinner While Running | When set to By default, this toggle is set to |
Show Page Loader Spinning While Running | When set to By default, this toggle is set to |
Assign Values if They Are Null or Empty String | If an output comes back empty, you can either have the data store as an empty value or choose not to store the data. By setting this toggle to By default, this toggle is set to |
Only Set Output Variables | When set to When set to By default, this toggle is set to |
Convert XML Response to JSON | Older API calls are more likely to use XML coding language. The Unqork Designer Platform reads JSON coding language only. If you know your API call returns XML, set this toggle to By default, this toggle is set to |
Expect Binary Response | When set to By default, this toggle is set to |
Enable Server Side Pagination | When set to By default, this toggle is set to |
Synchronous Processing | When set to By default, this toggle is set to |
Flatten to a Single Record Value | When set to By default, this toggle is set to |
Assign All Values Returned to Module | When set to By default, this toggle is set to |
Use "Data" Value from Response | The Plug-In component looks for all specified output values in the data section of the response body. When set to By default, this toggle is set to |
Include Cookies on Cross-Site Requests | When set to By default, this toggle is set to |
Required Property Path in Response | This field lets you set a required property path return value. If the path isn't present in the response body, the call results in an error. |
Adding a Plug-In Component
In this example, set up the Plug-in component's List Submissions for Dashboard API call. This call retrieves data submitted by your end-user and populates it on a dashboard. To make it easier, we already created the source module your end-user uses to submit their information. You can find the prebuilt source module here: https://training.unqork.io/#/form/5eb01aa6811bf80215fd706b/edit.
If you preview this module in Express View, you see a page that collects your end-user's information. This source module includes name, email, and date of birth fields. After your end-user adds their information, they click Save. Their submission data is then stored. The List Submissions for Dashboard API call references this source module and retrieves the submission data to display in a dashboard. These instructions assume that you have an open module saved with a title.
In this configuration, you need the following components:
1 Initializer component
1 Hidden component
1 Plug-In component
1 ViewGrid component
Configure the Initializer Component
This Initializer component triggers the Plug-In component that you'll set up later.
In the Module Builder, drag and drop an Initializer component onto your canvas.
In the Property ID field, enter initStart.
In the Canvas Label Text field, enter
initStart
.Navigate to the Initializer component's Actions settings.
From the Trigger Type drop-down, select New Submission.
Next to Inputs & Outputs, click Edit.
In the Outputs table, enter the following:
Source
Type
Value
plugGetSubmissions
trigger
GO
The Property ID here matches the Plug-In component you'll add in a later step.
8.Click Save Component.
Configure the Hidden Component
Next, add a Hidden component to store the module ID of your source module. If you have your own source module, you can use its module ID.
You can get the module ID from your source module’s hyperlink as follows: https://training.unqork.io/#/form/5eb01aa6811bf80215fd706b/edit. This module ID comes from the prebuilt source module.
Drag and drop a Hidden component onto your canvas, placing it below your initStart Initializer component.
In the Property ID field, enter moduleId.
In the Canvas Label Text field, enter
moduleId
.In the Default Value field, enter 5eb01aa6811bf80215fd706b.
Click Save Component.
Configure the Plug-In Component
Now, add a Plug-In component to retrieve the submissions from your source module, so you can display them in a dashboard.
Drag and drop a Plug-In component onto your canvas, placing it below your moduleIdHidden component.
In the Property ID field, enter plugGetSubmissions.
In the Canvas Label Text field, enter
plugGetSubmissions
.Navigate to the Plug-In component's Data settings.
From the Internal Services drop-down, enter or select List Submissions for Dashboard.
Next to Inputs & Outputs, click Edit.
In the Inputs table, enter the following:
Property ID
Mapping
moduleId
moduleId
'firstName,middleName,lastName,email,dateOfBirth'
fields
The first row references the module ID stored in the Hidden component. The second row shows the source module fields you're retrieving to insert into the dashboard. The values entered in the Mapping column (moduleId and fields) are native values in Unqork.
Click Save Component.
Configure the ViewGrid Component
Next, add a ViewGrid component to display your data in a dashboard.
Drag and drop a ViewGrid component onto the canvas, placing it below your plugGetSubmissions Plug-In component.
In the Property ID field, enter vgSubmissions.
In the Canvas Label Text field, enter
Submissions
.Navigate to the ViewGrid component's Data settings.
Next to Inputs & Display & Outputs, click Edit.
In the Inputs table, enter the following:
Source
Required
plugGetSubmissions
(Checked)
In the Display table, enter the following:
ID
Formula
Heading
firstName
First Name
middleName
Middle Name
lastName
Last Name
email
Email
dateOfBirth
=MOMENT(MOMENT(dateOfBirth), 'format', 'MM/DD/YY')
Date of Birth
The Moment.js in the Formula column formats the dateOfBirth values as MM/DD/YY.
8.In the Outputs table, enter the following:
Source
Mapping
submissionId
id
9.Navigate to the
ViewGrid component's Actions settings.
10.In the Action field, enter
null
.11.Click Save Component.
12.Save your module.
Now, Preview your module in Express View. A dashboard displays showing the data from the source module. Using an API call, the Plug-In component retrieves the submissions from the source module and your ViewGrid component displays them. This is one of many examples of using the Plug-In component in Unqork.
The completed configuration looks like this in Express View:
Structure of a Plug-In Component's Data
Each row of the table stores as an array in the Unqork database.
Overview
The Plug-In component connects a module to internal and external API services for passing data to and from a chosen source.
Common uses of the Plug-In component include:
Generating an email on submission of an application.
Populating a dashboard with application submissions.
Retrieving and displaying up-to-date data from an external source.
To make an external API call with a Plug-In component, you must set up the API service in Unqork's Services Administration. Doing so requires you to reference the external service's API documentation. Once you set up the service, the API call becomes available to use with your Plug-In component.
To learn more about Services Administration, view our Services Administration article.
You'll find the Plug-In component in the Data & Event Processing group to the left of the Module Builder.
Remote Executing Your Plug-In Component
It's best practice to configure your Plug-In component to remote execute. Remote execute, or server-side execution, lets the Plug-In component execute the call outside of the browser. Running APIs in the browser is not secure. If the API call happens in the browser, malicious agents can access the data in the DevTools Console—including accessing PII (personally identifiable information) and inject malware.
The benefits of using remote execute are:
Speed: Back-end services handled by a remote server ease the burden on the browser.
Security: No one can use the DevTools Console to access PII.
Debugging: Modularization provides a smaller code-base for debugging.
To learn more about the DevTools Console, view our Access Submission Data Using the DevTools Console article.
What You'll Learn
After completing this article, you’ll know when to use a Plug-In component, how to configure its settings, and how to use it in an Unqork application.
About the Configuration Window
To learn more about general component settings and those that display when a component is associated with Data Models, view our General Component Settings article.
Display Panel
Setting | Description |
---|---|
Canvas Label Text | A component’s Label Text indicates the purpose of the corresponding field or component. For non-input components, the Label Text isn't end-user facing, and only appears in the Module Builder. User-friendly labels make your module more accessible. Keep labels short and descriptive (a word or two) using title case. For longer entries, use sentence case. |
Data Panel
Service Type
The Plug-In component can be used for making internal Unqork API calls and external API calls.
Unqork
Selecting this option provides you with an Internal Services drop-down.
Setting | Description |
---|---|
Internal Services | Shows all internal Unqork services available for use. After selecting a service, the Request Type and Data Source URL autofill. |
Pre-Request Transform | In the Pre-Request Transform drop-down, you can select a transform to perform on the submission. The transformed output creates the request body passed to the API call. |
Module/Workflow | If you are making a call to a module or workflow, a Module or Workflow drop-down displays, so you can select a specific module or workflow. |
Data Source URL | For an API to retrieve data, you need the API's URL information. In this field, enter the API information as obtained from the API documentation. Add additional filters at the end of the URL if you want to drill down to a specific type of data. |
External
Selecting this option provides you with an External Services drop-down.
Setting | Description |
---|---|
External Services | Shows all services already configured in Services Administration. After selecting a service, the Request Type and Data Source URL autofill. |
Data Source URL | For an API to retrieve data, you need the API's URL information. In this field, enter the API information as obtained from the API documentation. Add additional filters at the end of the URL if you want to drill down to a specific type of data. |
Request Type
The Request Type is automatically selected after you've completed the Service Type settings. The Plug-In component includes five Request Types.
Get: Retrieves and reads existing resources, like submission data.
Patch: Partially updates existing resources.
Post: Creates new resources.
Put: Updates existing resources.
Delete: Deletes resources.
If Patch, Post, or Put are selected, two new toggles display:
Setting | Description |
---|---|
Make a MultiPart API Call | Multipart API calls combine one or more sets of data into a single body. Multipart requests are common for file uploads and for transferring multiple data types with a single request. Set this toggle to |
Alternative Multipart Sub-Type (Services) | The Alternative Multipart Sub-Type (Services) field is only available for external APIs, but can be used to specify whether the parts of your request are related, mixed, or otherwise correlated. |
Promote Object/Array to Top Level | Use this setting to call an object or array, and make it the body of the API request. When the Promote Object/Array to Top Level toggle is set to |
Object/Key Array | In this field, enter the key of the object or array that you're promoting to the top level. |
Inputs Table
Use these fields to enter inputs as references for your logic components. These references include values you want to send as part of the API call's request header or body. For example, when getting module submission details for a dashboard, you need to enter the fields that you want to pull from the source module.
There is a 50 MB limit for all request payloads to internal services in Unqork.
Setting | Description |
---|---|
Property ID | Examples of supported inputs include:
|
Mapping | API documentation includes mapping information. Mapping information tells your Plug-In component which data to send or retrieve from the API call. In the case of SendGrid integration, the Mapping column indicates where the Property ID values show up in the email. If you enter '[email protected]' in the Inputs table's Property ID and from.email in the Mapping column, your From address is [email protected]. |
Required | When |
Exclude | When selected, the Plug-In component doesn't pass the field as part of your API call's request body. But, the Plug-In component can still watch for changes made to the value. |
Header | When selected, the Plug-In component passes the field as part of the API call's request header. When clear, the Plug-In component passes the field as part of the request body. |
Resolvebase64 | Select this setting if you're expecting a Base64 file from your API request. Selecting this setting prepares the system for the Base64 file, making it easier to convert the file. |
Optional | When selected, the Plug-In component doesn't pass the field in the API call's request body if there's no value (null). By default, the Plug-In passes every Input in the request body, even if the field is empty (null). |
Outputs
Use the Outputs table to send the data retrieved by the API call to a specific location.
Setting | Description |
---|---|
Property ID | For your logic component to recognize an output, you must enter the destination component's Property ID(s). The Property ID entered must match the Property ID of the component that acts as the output. Remember, use camel case without spaces or punctuation. |
Mapping | Map Property IDs according to the API's documentation. Mapping tells your Plug-In component what to retrieve from the API call. For the Outputs table, map specific data to put into your output components. |
Option | This setting offers handling methods for your outputs:
|
Header | When selected, the Plug-In component looks for the output value in the response header. When clear, the Plug-In looks for the field in the response body. |
Actions Panel
Setting | Description |
---|---|
Trigger Type | This setting provides the following options:
|
Concurrent Trigger | Enter the Property ID of the component to trigger concurrently when the Plug-In component makes the API call. |
Post Trigger | Enter the Property ID of the component to trigger after the Plug-In completes the API call. For example, triggering a component to display the data received from the Plug-In component's API call. |
Error Trigger | Enter the Property ID of a component to trigger on failure of the API call.
|
Set Timeout | The number of milliseconds that pass before the API call times out. If an API call doesn't respond within a reasonable time, you don't want the Plug-In component to continue to wait. Unresponsive API calls can stall your entire application. The maximum timeout is 120,000 milliseconds. |
Set Retry Delay | The number of milliseconds that pass before the component tries the API call again after it failed. Waiting before retrying an API call could give the destination server time to clear the issues that caused it to be unresponsive. The maximum delay is 10,000 milliseconds.
|
Set Number of Retries | The number of retries the Plug-In component makes on a failed API call. It's best practice to limit the number of retries, so a continually failing API call doesn't stall your application. Use this setting to limit the number of times the Plug-In component retries the failed API call. If the API call fails all retries, the Error Trigger fires. The maximum number of retries is 10.
|
Disable Execution | If Disable Execution is set to By default, this setting is set to |
Advanced Panel
Setting | Description |
---|---|
Set Debounce | The number of milliseconds that pass before the module loads this component. This is useful if you have a large module and you load several components at the same time.
|
Show Modal Dialog While Running | When set to
By default, this toggle is set to |
Show Cursor as Spinner While Running | When set to By default, this toggle is set to |
Show Page Loader Spinning While Running | When set to By default, this toggle is set to |
Assign Values if They Are Null or Empty String | If an output comes back empty, you can either have the data store as an empty value or choose not to store the data. By setting this toggle to (ON), null or empty strings store as empty values. If set to By default, this toggle is set to |
Only Set Output Variables | When set to When set to By default, this toggle is set to |
Convert XML Response to JSON | Older API calls are more likely to use XML coding language. The Unqork Designer Platform reads JSON coding language only. If you know your API call returns XML, set this toggle to By default, this toggle is set to |
Expect Binary Response | When set to By default, this toggle is set to |
Enable Server Side Pagination | When set to By default, this toggle is set to |
Flatten to a Single Record Value | When set to By default, this toggle is set to |
Assign All Values Returned to Module | When set to By default, this toggle is set to |
Look for 'Data' Key in Response | The Plug-In component looks for all specified output values in the data section of the response body. When set to By default, this toggle is set to |
Include Cookies on Cross-Site Requests | When set to By default, this toggle is set to |
Required Property Path in Response | This field lets you set a required property path return value. If the path isn't present in the response body, the call results in an error. |
Adding a Plug-In Component
In this example, set up the Plug-in component's List Submissions for Dashboard API call. This call retrieves data submitted by your end-user and populates it on a dashboard. To make it easier, we already created the source module your end-user uses to submit their information. You can find the prebuilt source module here: https://training.unqork.io/#/form/5eb01aa6811bf80215fd706b/edit.
If you preview this module in Express View, you see a page that collects your end-user's information. This source module includes name, email, and date of birth fields. After your end-user adds their information, they click Save. Their submission data is then stored. The List Submissions for Dashboard API call references this source module and retrieves the submission data to display in a dashboard. These instructions assume that you have an open module saved with a title.
In this configuration, you need the following components:
1 Initializer component
1 Hidden component
1 Plug-In component
1 ViewGrid component
Configure the Initializer Component
This Initializer component triggers the Plug-In component that you'll set up later.
In the Module Builder, drag and drop an Initializer component onto your canvas.
2.In the Property ID and Canvas Label Text fields, enter initStart.
To the left component's configuration window, select
Actions.
From the Trigger Type drop-down, select New Submission.
In the Outputs table, enter the following:
Property ID
Required
Value
plugGetSubmissions
trigger
GO
The Property ID here matches the Plug-In component you'll add in a later step.
Click Save & Close.
Configure the Hidden Component
Next, add a Hidden component to store the module ID of your source module. If you have your own source module, you can use its module ID.
You can get the module ID from your source module’s hyperlink as follows: https://training.unqork.io/#/form/5eb01aa6811bf80215fd706b/edit. This module ID comes from the prebuilt source module.
Drag and drop a Hidden component onto your canvas, placing it below your Initializer component.
In the Property ID and Canvas Label Text fields, enter moduleId.
In the Default Value field, enter 5eb01aa6811bf80215fd706b.
Click Save & Close.
Configure the Plug-In Component
Now, add a Plug-In component to retrieve the submissions from your source module, so you can display them in a dashboard.
Drag and drop a Plug-In component onto your canvas, placing it below your Hidden component.
In the Property ID and Canvas Label Text fields, enter plugGetSubmissions.
From the Internal Services drop-down, select List Submissions for Dashboard.
In the Inputs table, enter the following:
Property ID
Mapping
moduleId
moduleId
'firstName,middleName,lastName,email,dateOfBirth'
fields
The first row references the module ID stored in the Hidden component. The second row shows the source module fields you're retrieving to insert into the dashboard. The values entered in the Mapping column (moduleId and fields) are native values in Unqork.
Click Save.
Configure the ViewGrid Component
Next, add a ViewGrid component to display your data in a dashboard.
Drag and drop a
ViewGrid component onto the canvas, placing it below your Plug-In component.
In the Label field, enter Submissions.
In the Property Name field, enter vgSubmissions.
In the Action field, enter null.
In the Inputs table, enter the following:
ID
Required
plugGetSubmissions
(Checked)
In the Outputs table, enter the following:
ID
Required
plugGetSubmissions
(Checked)
In the Display table, enter the following:
ID
Formula
Heading
firstName
First Name
middleName
Middle Name
lastName
Last Name
email
Email
dateOfBirth
=MOMENT(MOMENT(dateOfBirth), 'format', 'MM/DD/YY')
Date of Birth
The Moment.js in the Formula column formats the dateOfBirth values as MM/DD/YY.
Click Save.
Save your module.
Now, Preview your module in Express View. A dashboard displays showing the data from the source module. Using an API call, the Plug-In component retrieves the submissions from the source module and your ViewGrid component displays them. This is one of many examples of using the Plug-In component in Unqork.
The completed configuration looks like this in Express View:
Structure of a Plug-In Component's Data
Each row of the table stores as an array in the Unqork database.
Resources
Is it implied that the Data Source URL includes an http:// or https:// protocol?
How do you create an API query parameter for a specific API endpoint?
Why is a "Get Submissions" API call failing when you change roles?