Plug-In Component
Estimated Reading Time: 17 minutes
Overview
The Plug-In component connects your module to the outside world. The component uses internal and external API (application programming interface) calls to pass 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, set up the API call in Unqork's Services Administration section of the Unqork Designer Platform. To do this, you need 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.
TIP To learn more about Services Administration, search Services Administration in our In-Product Help.
You'll find the Plug-In component in the Data & Event Processing group at the left of the Module Editor.
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 everything in the browser isn't secure. If the API call happens in the browser, anyone can pull up the DevTools Console and see your data. They can also access PII (personally identifiable information) and inject malware.
The benefits of using remote execute are:
-
Speed: Back-end services handled via a remote server, easing overburden on the browser.
-
Security: The DevTools Console inspector can't access PII, and so it's protected.
-
Debugging: Modularization provides a smaller code-base for debugging.
By creating remote executes, you prevent malicious actors from seeing sensitive data. That sensitive data is instead hidden, processed only in the remote execute module.
What You'll Learn
In this article, you'll learn how to:
- Use the Plug-In component's configuration window.
- Add and configure a Plug-In component.
- Understand the structure of a Plug-In component's data.
- Apply best practices.
- Edit a Plug-In component.
- Move a Plug-In component.
- Copy a Plug-In component.
- Remove a Plug-In component.
About the Configuration Window
Jump to:
General
Setting |
Description |
---|---|
Property ID |
A Property ID is the unique field ID used by Unqork to track and link components in your module. The Property ID is how the software identifies your component. Using Property IDs lets you link components, creating logic-based configurations and 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. calls. Property IDs must use camel case A naming convention for computer programming. Use camelCase for Property IDs, for example: newUser, lastName, & rdoButton. (stylized as camelCase) without spaces or punctuation. |
Field Tags |
Assign components one-word labels to help organize, identify, and group the components in your application. Consider an example from the API Specification Snippet: Field Tags are applied to Hidden components in the panelRequest and panelResponse Panels. The Field Tags identify the data type of parameters included in the 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. request and response. The API Docs Dashboard tool populates with information about each parameter’s data type, identified by the Field Tag. Field Tags act as a type of Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. group and let you group components for configuration purposes. Field Tags let you target two or more components using a simple logic component. For example, add the Field Tag tagForDecision to multiple components in your module. Open the Inputs table of a Decisions component and reference the tagForDecision Field Tag as the input of the Decisions component. The output of the Decisions component then affects all components with the tagForDecision Field Tag. Save your Field Tags by pressing Enter (Return) or adding a comma after each entry. |
Settings Tab |
Select this tab to display the component's Display, Data, Actions, and Validation settings panels, as applicable. |
Permissions Tab |
Select this tab to see the RBAC RBAC (Role-Based Access Control) is a method to control system access for authorized users. The role in RBAC refers to the levels of access employees have to a network. (role-based access control) settings of the component. |
Notes Tab |
Select this tab to display the component's Notes area. You can use notes to keep your teammates informed. The Notes editor offers a semi-WYSIWYG (What You See is What You Get) content editor. Built to look like a word processor, this editor lets you create, edit, and format your notes. Notes save when saving the component. |
Cancel Button |
Click this button to undo any unsaved configuration changes and return to the canvas. |
Save Button |
Click this button to save all settings as configured and return to the canvas. |
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 Editor. 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
Setting |
Description |
---|---|
Service Type |
The 2 Service Types offered by the Plug-In component are:
TIP To learn more about Services Administration, search Services Administration in our In-Product Help. |
Internal/External Services |
Depending on your choice of the Unqork or External Service Type, an Internal Services or External Services drop-down displays:
|
Data Source URL |
For an API to bring in 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 |
Based on if you select an internal or external service, the Request Type auto-selects as one of the following: GET, PATCH, POST, PUT, or DELETE. If the API call is a PATCH, POST, or PUT, 2 toggles display:
|
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 entered must match the Property ID used in the output component. Remember, use camel case (stylized as camelCase) without spaces or punctuation. NOTE When using the Watch Trigger Type, enter all inputs the component must watch for in the Property ID column. TIP You can use dot notation to reference values nested under a Property ID in the submission data.
|
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 set to ON, the end-user must enter a value into the field before navigating ahead or saving the module. Set the toggle to OFF when an entry is optional. By default, the Required toggle is set to OFF. |
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) here. The Property ID entered must match the Property ID used in the output component. Remember, use camel case A naming convention for computer programming. Use camelCase for Property IDs, for example: newUser, lastName, & rdoButton. (stylized as camelCase) without spaces or punctuation. |
Mapping |
Map Property IDs according to the API's documentation. Mapping tells your Plug-In 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 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, Disable Execution is set to |
Advanced Settings
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. NOTE 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:
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. By default, this toggle is set to OFF. |
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 ON. When set to ON, the system automatically converts XML to JSON. By default, this toggle is set to OFF. |
Expect Binary Response |
When set to ON, the response doesn't convert to and store as base64. Enable this setting when you expect the API call to return a large file, and/or want to store the response in its original file format. By default, this toggle is set to OFF. |
Enable Server Side Pagination |
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 |
Synchronous processing forces each workflow process to run one at a time. When set to ON, all other processes in your module stop running until the Plug-In component finishes the API call. This style of processing can result in longer processing times. It's best practice when your Plug-In component uses data processed by other components. 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. |
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
Now, set up a simple API call using a Plug-In component. The API call you'll set up is the List Submissions for Dashboard API call. This is a common API call at Unqork. The call retrieves data your end-users submit through your application. To make it easier, we already created the source module your end-user uses to enter 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. This button stores their data in a submission. The List Submissions for Dashboard API call references this module and retrieves the submission to display in a dashboard.
Let’s add a Plug-In component.
Configure the Initializer Component
This Initializer component triggers the Plug-In component that you'll set up later.
1. | In the Module Editor, drag and drop an Initializer component onto your canvas. |
2. | In the Property ID and Canvas Label Text fields, enter initStart. |
3. | Select New Submission as the Trigger Type. |
4. | In the Outputs table, enter the following: |
Property ID |
Required |
Value |
---|---|---|
plugGetSubmissions |
trigger |
GO |
NOTE The Property ID here matches the Plug-In component you'll add in a later step.
5. | Click Save. |
Configure the Hidden Component
Next, add a Hidden component. This component houses 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. |
2. | In the Property ID and Canvas Label Text fields, enter moduleId. |
3. | In the Default Value field, enter 5eb01aa6811bf80215fd706b. |
4. | Click Save. |
Configure the Plug-In Component
Now, add your Plug-In component. After configuration, the Plug-In gets 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 |
NOTE The first row references the module ID stored in the Hidden component. The second row shows the source module fields you're pulling 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. |
2. | In the Label field, enter Submissions. |
3. | In the Property Name field, enter vgSubmissions. |
4. | In the Action field, enter null. |
5. | In the Inputs table, enter the following: |
ID |
Required |
---|---|
plugGetSubmissions |
Yes (checked) |
6. | In the Outputs table, enter the following: |
ID |
Mapping |
---|---|
submissionId |
id |
7. | In the Display table, enter the following: |
ID |
Formula |
Heading |
---|---|---|
firstName |
|
First Name |
middleName |
|
Middle Name |
lastName |
|
Last Name |
|
|
|
dateOfBirth |
=MOMENT(MOMENT(dateOfBirth), 'format', 'MM/DD/YY') |
Date of Birth |
NOTE The Moment.js in the Formula column formats the dateOfBirth values as MM/DD/YY.
8. | Click Save. |
9. | Save your module. |
Now, preview your module in Express View. A dashboard displays showing the data from your end-user's submissions in 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.
Best Practices
- It's best practice to remote execute all Plug-In components to avoid malicious attacks on your data.
-
Plug-in components process data asynchronously. To guarantee that a manually-triggered component doesn't run until it receives the necessary input, enter that component as the Plug-in component's Post Trigger.
-
Apply custom RBAC to the module. RBAC helps control who can execute the API call. Another best practice is to create a proxy module between your API module and Express View module.
-
The Flatten to Single Record Result setting formats the data into an object instead of an array.
-
The Look for 'Data' Key in Response setting prohibits how you manipulate that data in your application. Avoid this setting to control your data format.
-
The Assign All Values Returned to Form setting takes everything from your API response and adds it to the submission data. The result is a slow call and a bad submission.
-
Plug-In components don't store data. Your module's performance improves if you store the Plug-In component's outputs in other components.
-
Modules might perform poorly if the List Submissions for Dashboard service returns a large number of submissions and server-side paginations isn't enabled.
-
If you don't plan on using disabled components in your application, remove them to ensure optimal performance. Remember to check all active components that connect to disabled components. Ensure active components still function properly after you remove the disabled ones.
-
If getSubmission Plug-In components don't enforce limits, they might fetch more data than the module can handle.
-
Use the component's Notes tab to comment on complex data processes. Add notes to explain what components are being triggered, trigger types, and the importance of each component.
Editing a Plug-In Component's Settings
You can revisit and make changes to your saved component's settings.
1. | In the Module Editor hover over the Plug-In component. |
A 5-button toolbar displays above the component on hover-over.
2. | Using the toolbar, click the ![]() |
3. | Using the Configuration window, make changes to the component’s settings as needed. |
4. | Click Save. |
5. | Save your module. |
Moving a Plug-In Component
You can move your component to a new position on your canvas.
1. | Hover over the Plug-In component. |
A 5-button toolbar displays above the component on hover-over.
2. | Click and drag the ![]() |
3. | Save your module. |
Copying a Plug-In Component
You can make a copy of your component using the Copy and Paste tools. Copy and Paste creates an exact copy of your component, matching all settings. The only noticeable difference between the two components is the Property ID. The Property ID on the new component automatically updates. Remember, every component must have a unique Property ID. Property IDs are the main method used to track and connect components in Unqork.
1. | Hover over the Plug-In component. |
A 5-button toolbar displays above the component on hover-over.
2. | Click the ![]() |
3. | Click the ![]() |
4. | Update the copied component’s settings, if needed. |
5. | Click Save. |
6. | Save your module. |
Removing a Plug-In Component
You can remove your component from the module.
1. | Hover over the Plug-In component. |
A 5-button toolbar displays above the component on hover-over.
2. | Click the ![]() |
3. | Save your module. |
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?