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:

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:

  • Unqork: Unqork has a number of preconfigured, internal API services. These API calls help you create files, convert files, and access or edit submission data.

  • External: The Plug-In component can make an API call to an external source. You must configure these services in Unqork's Services Administration.

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:

  • Internal Services: Shows all internal Unqork services available for use. After selecting a service, the Request Type and Data Source URL autofill.

    On selection of an Internal Service, the Pre-Request Transform drop-down displays. 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.

  • 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 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:

  • 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 making a multipart API call.

  • Promote Object/Array to Top Level: Use this setting to call an object or array, and make it the body.

    When the Promote Object/Array to Top Level toggle is set to ON, the Object/Array Key setting shows. In the Object/Key Array field, enter the key of the object or array that you're promoting to the top level.

    Set this toggle to ON when sending a request that isn't part of the API's body.

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.

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.

  • 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 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:

  • 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.

  • DynamicRefresh: Triggers the specified panel to refresh its existing content with the provided component definitions (component JSON). The specified Panel component must have Dynamic Refresh enabled.

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:

  • Manual:  The component fires when triggered by another component. For example, using a Button component or Initializer component to trigger the Plug-In component. By default, the Manual Trigger Type is selected.
  • Watch: The component fires when there's any action taken on the input component(s) 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.

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 Toggle Button set to On (ON), the logic tied to this component does not execute. Use this to keep the component's settings, but to disable the operations it performs.

By default, Disable Execution is set to Toggle Button set to Off. (OFF).

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:

  • 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.

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

email

 

Email

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 (Settings) button.
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 (Move) button, dropping the component when it’s in position.
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 (Copy) button.
3. Click the (Paste) button.
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 (Remove) button.
3. Save your module.

Resources