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.
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.
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 ON when sending a request that isn't part of the API's body. When set to (ON), the Alternative Multipart Sub-Type (Services) field displays.
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 (ON), the Object/Array Key field displays.
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.
Setting
Description
Property ID
Examples of supported inputs include:
The Property ID of another component in the module. For example, this component can be a trigger, an input for a Micro Decision, or is referenced in a formula.
The Property ID entered must match the Property ID used in the output component. Remember, use camel case (stylized as camelCase) without spaces or punctuation.
When using the Watch Trigger Type, enter all inputs the component must watch for in the Property ID column.
You can use dot notation to reference values nested in a Property ID in the submission data.
Values that are present in the submission object. For example, you can enter currentUser to retrieve information about the end-user from this object.
Native values generated by Unqork, like entering buttonClick. Unqork creates this value following button-click events.
Values you want to hard-code into an API call. For example, entering 'no-reply@unqork.com' to map the from.email parameter of a SendGrid call.
When hard-coding a value, add single quotes around it. This tells the Plug-In the value isn't the Property ID of a component.
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 'no-reply@unqork.com' in the Inputs table's Property ID and from.email in the Mapping column, your From address is no-reply@unqork.com.
Required
When (Checked), the end-user must enter a value into the field before navigating ahead or saving the module.
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.
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).
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:
Fill: If there's already a value in the output field, the value remains the same. The API call's value doesn't replace the existing value.
Replace: If there's already a value in the output field, this setting overwrites the value.
Validate: The Plug-In component maps and validates the value. Validation occurs based on the validation rules set in the output field's settings.
Disable: This setting maps the response to the field and then disables the field. Use this setting to disable editing of the output field after it populates.
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:
Manual: The component fires when triggered by another component. For example, when using a Button or Initializer component to trigger a Plug-In component.
By default, this Trigger Type is selected.
Watch: The component fires when there's any action taken on the input listed in the Inputs table. Actions include entering a new value, editing, or overwriting a saved value. If there are multiple inputs, use the Required setting to specify what inputs must be present before firing.
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.
Errors can be 4xx, 5xx, and other network errors.
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.
This setting does not trigger when the Plug-In fails a PUT call to a remote execute.
Errors can be 4xx, 5xx, and other network errors.
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.
This setting does not trigger when the Plug-In fails a PUT call to a remote execute.
Errors can be 4xx, 5xx, and other network errors.
Disable Execution
If Disable Execution is set to (ON), the logic tied to this component does not execute. Use this to keep the component's settings, but disable the operations it performs.
By default, this setting is set to (OFF).
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.
1,000 milliseconds = 1 second.
Show Modal Dialog While Running
When set to (ON), this setting creates a modal that informs the end-user that the data is processing. The following fields are optional:
Modal Processing Title: Enter the modal's title.
Modal Processing Message: Enter the message end-users see while the data is processing.
Modal Completion Title: Enter the title end-users see after the data processes.
Modal Error Message: Enter the message end-users see if the data encounters an error while loading.
By default, this toggle is set to (OFF).
Show Cursor as Spinner While Running
When set to (ON), the end-user's cursor turns into a spinner while data processes.
By default, this toggle is set to (OFF).
Show Page Loader Spinning While Running
When set to (ON), the page displays a spinning icon while data processes.
By default, this toggle is set to (OFF).
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 (OFF), the values don't record.
By default, this toggle is set to (ON).
Only Set Output Variables
When set to (ON), the Plug-In component only returns the values set in the Output table, instead of the entire plugin object. Also, none of the Plug-In component's other information logs in the DevTools Console.
When set to (OFF), the plugin object logs in the DevTools Console with all response data.
When set to (ON), the server sends a single page of data at a time. This helps the page load faster and prevents bloating the end-user's memory. This setting is especially useful for large data sets.
By default, this toggle is set to (OFF).
Synchronous Processing
When set to (ON), this setting performs each logic action in sequential order. Use this setting to prevent executing logic actions out of order.
By default, this toggle is set to (OFF).
Flatten to a Single Record Value
When set to (ON), the module flattens results into a single record value. When set to OFF, the module leaves the results unflattened into multiple values.
By default, this toggle is set to (OFF).
Assign All Values Returned to Module
When set to (ON), the Plug-In component scans the module for matching values across the API call and Property IDs. Only set this toggle to (ON) when the module and the API call's data match.
By default, this toggle is set to (OFF).
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 (ON), you can remove the data. prefix from your mapping fields. For example, mapping to lastName instead of data.lastName.
By default, this toggle is set to (OFF).
Include Cookies on Cross-Site Requests
When set to (ON), an application can makes cross-site access-control requests using credentials, like cookies.
By default, this toggle is set to (OFF).
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.
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:
Navigate to the Initializer component's Actions settings.
5.
From the Trigger Type drop-down, select New Submission.
6.
Next to Inputs & Outputs, click Edit.
7.
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.
1.
Drag and drop a Hidden component onto your canvas, placing it below your initStart Initializer component.
Navigate to the Plug-In component's Data settings.
5.
From the Internal Services drop-down, enter or select List Submissions for Dashboard.
6.
Next to Inputs & Outputs, click Edit.
7.
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.
8.
Click Save Component.
Configure the ViewGrid Component
Next, add a ViewGrid component to display your data in a dashboard.
1.
Drag and drop a ViewGrid component onto the canvas, placing it below your plugGetSubmissions Plug-In component.
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.
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 Canvas Label Text indicates the purpose of the corresponding field or component. For non-input components, the Canvas 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 ON when sending a request that isn't part of the API's body. When set to (ON), the Alternative Multipart Sub-Type (Services) field displays.
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 (ON), the Object/Array Key field displays.
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.
Setting
Description
Property ID
Examples of supported inputs include:
The Property ID of another component in the module. For example, this component can be a trigger, an input for a Micro Decision, or is referenced in a formula.
The Property ID entered must match the Property ID used in the output component. Remember, use camel case (stylized as camelCase) without spaces or punctuation.
When using the Watch Trigger Type, enter all inputs the component must watch for in the Property ID column.
You can use dot notation to reference values nested in a Property ID in the submission data.
Values that are present in the submission object. For example, you can enter currentUser to retrieve information about the end-user from this object.
Native values generated by Unqork, like entering buttonClick. Unqork creates this value following button-click events.
Values you want to hard-code into an API call. For example, entering 'no-reply@unqork.com' to map the from.email parameter of a SendGrid call.
When hard-coding a value, add single quotes around it. This tells the Plug-In the value isn't the Property ID of a component.
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 'no-reply@unqork.com' in the Inputs table's Property ID and from.email in the Mapping column, your From address is no-reply@unqork.com.
Required
When (Checked), the end-user must enter a value into the field before navigating ahead or saving the module.
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.
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).
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:
Fill: If there's already a value in the output field, the value remains the same. The API call's value doesn't replace the existing value.
Replace: If there's already a value in the output field, this setting overwrites the value.
Validate: The Plug-In component maps and validates the value. Validation occurs based on the validation rules set in the output field's settings.
Disable: This setting maps the response to the field and then disables the field. Use this setting to disable editing of the output field after it populates.
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:
Manual: The component fires when triggered by another component. For example, when using a Button or Initializer component to trigger a Plug-In component.
By default, this Trigger Type is selected.
Watch: The component fires when there's any action taken on the input listed in the Inputs table. Actions include entering a new value, editing, or overwriting a saved value. If there are multiple inputs, use the Required setting to specify what inputs must be present before firing.
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.
Errors can be 4xx, 5xx, and other network errors.
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.
This setting does not trigger when the Plug-In fails a PUT call to a remote execute.
Errors can be 4xx, 5xx, and other network errors.
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.
This setting does not trigger when the Plug-In fails a PUT call to a remote execute.
Errors can be 4xx, 5xx, and other network errors.
Disable Execution
If Disable Execution is set to (ON), the logic tied to this component does not execute. Use this to keep the component's settings, but disable the operations it performs.
By default, this setting is set to (OFF).
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.
1,000 milliseconds = 1 second.
Show Modal Dialog While Running
When set to (ON), this setting creates a modal that informs the end-user that the data is processing. The following fields are optional:
Modal Processing Title: Enter the modal's title.
Modal Processing Message: Enter the message end-users see while the data is processing.
Modal Completion Title: Enter the title end-users see after the data processes.
Modal Error Message: Enter the message end-users see if the data encounters an error while loading.
By default, this toggle is set to (OFF).
Show Cursor as Spinner While Running
When set to (ON), the end-user's cursor turns into a spinner while data processes.
By default, this toggle is set to (OFF).
Show Page Loader Spinning While Running
When set to (ON), the page displays a spinning icon while data processes.
By default, this toggle is set to (OFF).
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 (OFF), the values don't record.
By default, this toggle is set to (ON).
Only Set Output Variables
When set to (ON), the Plug-In component only returns the values set in the Output table, instead of the entire plugin object. Also, none of the Plug-In component's other information logs in the DevTools Console.
When set to (OFF), the plugin object logs in the DevTools Console with all response data.
When set to (ON), the server sends a single page of data at a time. This helps the page load faster and prevents bloating the end-user's memory. This setting is especially useful for large data sets.
By default, this toggle is set to (OFF).
Flatten to a Single Record Value
When set to (ON), the module flattens results into a single record value. When set to OFF, the module leaves the results unflattened into multiple values.
By default, this toggle is set to (OFF).
Assign All Values Returned to Module
When set to (ON), the Plug-In component scans the module for matching values across the API call and Property IDs. Only set this toggle to (ON) when the module and the API call's data match.
By default, this toggle is set to (OFF).
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 (ON), you can remove the data. prefix from your mapping fields. For example, mapping to lastName instead of data.lastName.
By default, this toggle is set to (OFF).
Include Cookies on Cross-Site Requests
When set to (ON), an application can makes cross-site access-control requests using credentials, like cookies.
By default, this toggle is set to (OFF).
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.
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:
To the left component's configuration window, select Actions.
4.
From the Trigger Type drop-down, select New Submission.
5.
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.
6.
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.
1.
Drag and drop a Hidden component onto your canvas, placing it below your Initializer component.
In the Default Value field, enter 5eb01aa6811bf80215fd706b.
4.
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.
1.
Drag and drop a Plug-In component onto your canvas, placing it below your Hidden component.
2.
In the Property ID and Canvas Label Text fields, enter plugGetSubmissions.
3.
From the Internal Services drop-down, select List Submissions for Dashboard.
4.
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.
5.
Click Save.
Configure the ViewGrid Component
Next, add a ViewGrid component to display your data in a dashboard.
1.
Drag and drop a ViewGrid component onto the canvas, placing it below your Plug-In component.
(Checked), the end-user must enter a value into the field before navigating ahead or saving the 
Manual: The component fires when triggered by another component. For example, when using a 
Button
Initializer component triggers the Plug-In component that you'll set up later.
Hidden component to store the module ID of your source module. If you have your own source module, you can use its module ID.
ViewGrid component to display your data in a dashboard.
Actions
