Plug-In Component

Prev Next

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.

A static image displaying the UDesigner Plug-In component's Field Text setting.

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 A toggle switch indicating an on/off state for a user interface element. ON when sending a request that isn't part of the API's body. When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch indicating an on/off state for a user interface element. (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.

There is a 50 MB limit for all request payloads to internal services in Unqork.

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 '[email protected]' 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 '[email protected]' in the Inputs table's Property ID and from.email in the Mapping column, your From address is [email protected].

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.

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:

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

In the Centauri runtime, this setting does not trigger when the Plug-In component fails a PUT call to a remote execute. However, it will trigger when the PUT call fails in the Vega runtime.

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.

In the Centauri runtime, this setting does not trigger when the Plug-In component fails a PUT call to a remote execute. However, it will trigger when the PUT call fails in the Vega runtime.

Errors can be 4xx, 5xx, and other network errors.

Disable Execution

If  Disable Execution  is set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (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 A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Show Cursor as Spinner While Running

When set to A toggle switch indicating an on/off state for a user interface element. (ON), the end-user's cursor turns into a spinner while data processes.

By default, this toggle is set to A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Show Page Loader Spinning While Running

When set to A toggle switch indicating an on/off state for a user interface element. (ON), the page displays a spinning icon while data processes.

By default, this toggle is set to A toggle switch in the 'on' position, indicating an active setting or feature. (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 A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch indicating an on/off state for a user interface element. (ON).

Only Set Output Variables

When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF), the plugin object logs in the DevTools Console with all response data.

By default, this toggle is set to A toggle switch in the 'on' position, indicating an active setting or feature. (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 A toggle switch indicating an on/off state for a user interface element. (ON). When set to A toggle switch indicating an on/off state for a user interface element. (ON), the system automatically converts XML to JSON.

By default, this toggle is set to A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Expect Binary Response

When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Enable Server Side Pagination

When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Synchronous Processing

When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Flatten to a Single Record Value

When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Assign All Values Returned to Module

When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (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 A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Include Cookies on Cross-Site Requests

When set to A toggle switch indicating an on/off state for a user interface element. (ON), an application can makes cross-site access-control requests using credentials, like cookies.

By default, this toggle is set to A toggle switch in the 'on' position, indicating an active setting or feature. (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.

A static image displaying the UDesigner Plug-In component's Advanced settings.
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:

Configure the Initializer Component

This Initializer component triggers the Plug-In component that you'll set up later.

  1. In the Module Builder, drag and drop an Initializer component onto your canvas.

  2. In the Property ID  field, enter initStart.

  3. In the  Canvas Label Text field, enter initStart.

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

    A static image displaying the Initializer component's  Output table configuration.                                                      

    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.

  2. In the Property ID  field, enter moduleId.

  3. In the Canvas Label Text field, enter moduleId.

  4. In the Default Value field, enter 5eb01aa6811bf80215fd706b.

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

  1. Drag and drop a Plug-In component onto your canvas, placing it below your moduleIdHidden component.

  2. In the Property ID field, enter plugGetSubmissions.

  3. In the  Canvas Label Text field, enter plugGetSubmissions.

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

  2. In the Property ID field, enter vgSubmissions.

  3. In the  Canvas Label Text field, enter Submissions.

  4. Navigate to the ViewGrid component's Data settings.

  5. Next to Inputs & Display & Outputs, click Edit.

  6. In the Inputs table, enter the following:

    Source

    Required

    plugGetSubmissions

      (Checked)

  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

    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 Dropdown Component Icon 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:

A static image displaying the Express View dashboard populated with end-user submission data.                                                    

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

A static image dispaying the Plug-In component's Display settings.

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

A static image dispaying the Plug-In component's Data settings.

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 A toggle switch indicating an on/off state for a user interface element. ON when sending a request that isn't part of the API's body. When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch indicating an on/off state for a user interface element. (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.

There is a 50 MB limit for all request payloads to internal services in Unqork.

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 '[email protected]' 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 '[email protected]' in the Inputs table's Property ID and from.email in the Mapping column, your From address is [email protected].

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.

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:

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

A static image dispaying the Plug-In component's Action settings.                                                        

Setting

Description

Trigger Type

This setting provides the following options:

  • Inline image displaying a selected radio button. 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.

  • Inline image displaying a selected radio button. 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.

In the Centauri runtime, this setting does not trigger when the Plug-In component fails a PUT call to a remote execute. However, it will trigger when the PUT call fails in the Vega runtime.

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.

In the Centauri runtime, this setting does not trigger when the Plug-In component fails a PUT call to a remote execute. However, it will trigger when the PUT call fails in the Vega runtime.

Errors can be 4xx, 5xx, and other network errors.

Disable Execution

If  Disable Execution  is set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Advanced Panel

A static image dispaying the Plug-In component's 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.

1,000 milliseconds = 1 second.

Show Modal Dialog While Running

When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Show Cursor as Spinner While Running

When set to A toggle switch indicating an on/off state for a user interface element. (ON), the end-user's cursor turns into a spinner while data processes.

By default, this toggle is set to A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Show Page Loader Spinning While Running

When set to A toggle switch indicating an on/off state for a user interface element. (ON), the page displays a spinning icon while data processes.

By default, this toggle is set to A toggle switch in the 'on' position, indicating an active setting or feature.  (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF), the values don't record.

By default, this toggle is set to A toggle switch indicating an on/off state for a user interface element. (ON).

Only Set Output Variables

When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF), the plugin object logs in the DevTools Console with all response data.

By default, this toggle is set to A toggle switch in the 'on' position, indicating an active setting or feature. (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 A toggle switch indicating an on/off state for a user interface element. (ON). When set to A toggle switch indicating an on/off state for a user interface element. (ON), the system automatically converts XML to JSON.

By default, this toggle is set to A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Expect Binary Response

When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Enable Server Side Pagination

When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Flatten to a Single Record Value

When set to A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Assign All Values Returned to Module

When set to A toggle switch indicating an on/off state for a user interface element. (ON), the Plug-In component scans the module for matching values across the API call and Property IDs. Only set this toggle to A toggle switch indicating an on/off state for a user interface element. (ON) when the module and the API call's data match.

By default, this toggle is set to A toggle switch in the 'on' position, indicating an active setting or feature. (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 A toggle switch indicating an on/off state for a user interface element. (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 A toggle switch in the 'on' position, indicating an active setting or feature. (OFF).

Include Cookies on Cross-Site Requests

When set to A toggle switch indicating an on/off state for a user interface element. (ON), an application can makes cross-site access-control requests using credentials, like cookies.

By default, this toggle is set to A toggle switch in the 'on' position, indicating an active setting or feature. (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.

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:

Configure the Initializer Component

This Initializer component triggers the Plug-In component that you'll set up later.

  1. In the Module Builder, drag and drop an Initializer component onto your canvas.

  2. 2.In the Property ID and Canvas Label Text fields, enter initStart.

  3. To the left component's configuration window, select Actions Icon 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

    A static image displaying the Initializer component's New Submission Trigger Type and Output table configuration.                                                      

    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.

  2. In the Property ID and Canvas Label Text fields, enter moduleId.

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

    A static image displaying the List Submissions for Dashboard API and the Inputs table.                                                      

  5. Click Save.

Configure the ViewGrid Component

Next, add a Dropdown Component Icon ViewGrid component to display your data in a dashboard.

  1. Drag and drop a Dropdown Component Icon 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

                                                                            (Checked)

  6. In the Outputs table, enter the following:

    ID

    Required

    plugGetSubmissions

                                                                            (Checked)

  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

    The Moment.js in the Formula column formats the dateOfBirth values as MM/DD/YY.

    A static image displaying the configuration of the ViewGrid component.                                                      

  8. Click Save.

  9. 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:

A static image displaying the Express View dashboard populated with end-user submission data.                                                    

Structure of a Plug-In Component's Data

Each row of the table stores as an array in the Unqork database.

Resources