Data Mapper Component

Overview

The Data Mapper is a Centauri (v1.0) The Centauri (v 1.0.0) runtime is the first-generation foundation of the Unqork Designer Platform. Centauri provides Creators a codeless experience for developing applications. component that manipulates submission data Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections. captured from other components using Excel formulas and Lodash functions.

Data Mapper component configurations commonly use IF The If/Then system is a logical structure used to define conditional statements, where a specific condition (If), triggers an action or outcome (Then). In this system, if the specified condition evaluates as true, the corresponding action or result will follow. statements. IF statements let you make logical decisions based on an input value using the following format: =IF(condition, valueIfTrue, valueIfFalse).

A few scenarios lend themselves particularly for using the Data Mapper component:

You can find the Data Mapper component in the Data & Event Processing group to the left of the Module Builder.

About the Configuration Window

To learn more about general component settings, view our General Component Settings article.

Data Settings

Data Storage

A static image displaying the Data Mapper component's data settings.

Setting

Description

Store Data in Database

The Store Data in Database setting affects how data persists through your application. When set to  (ON), Unqork stores values entered into the field to the database (server-side submission). This occurs in three scenarios:

  • Navigating between Panels in a Navigation component. On navigation between pages (Panels), the component’s value saves to the database.

  • Triggering a module save event using a Button component with an Action Type of Save.

  • Navigating between screens of a workflow. On navigation between screens, the component’s value saves to the database.

By default, workflows persist data from all fields in the client-side submission when navigating between screens. However, only values from fields with Store Data in Database enabled store in the server-side submission.

Set the toggle to (OFF) when you don’t want to store the values from this field in the database.

When using a Plug-In to remote execute a module, ensure data moving between modules is persistent. You can optionally enable Store Data in Database for components in the source module. But any components in the API module whose values are included in an API response must have Store Data in Database enabled. When a component’s data is not persistent, the data isn't included in an API call's response. So, Plug-Ins or external services requesting data from the API module can't receive non-persistent data in the response.

Store Data in Database also affects what data is tracked using Unqork’s built-in tracker. When the Enable Tracker and Track Value toggles are set to  (ON) in Module Settings, only values from fields with Store Data in Database enabled are tracked.

Restrict Search to Array

When set to  (ON), the Data Mapper component only iterates through the array defined in the Watch Field setting. When set to (OFF), the Data Mapper component iterates through the defined array and any other fields in your module.

By default, this setting is set to (OFF).

Include All Fields

When set to  (ON), the Data Mapper component adds all columns defined by the Data Mapper table into the Data Mapper array. When enabled, this setting also includes fields that do not contain any data. For example, if a given row contains no data in the valueB column, the array will include "valueB":"" in that row's object.

When set to (OFF), the Data Mapper component omits empty cells from the Data Mapper array. So, the valueB key/value pair does not appear in that row's object.

By default, this is setting is set to (OFF).

Wrap in Table

When set to  (ON), the Data Mapper array saves in the submission data as an HTML HTML (Hyper Text Markup Language) is the standard markup language for for achieving font, color, graphic, and hyperlink effects when creating web pages. table. The table's column headers are represented as Data Element and Values. The table populates with the Data Mapper array's key/value pairs. When set to (OFF), the Data Mapper array saves in the submission data as an array.

By default, this setting is set to (OFF).

Traverse Array Bottom to Top

When set to  (ON), the Data Mapper component searches arrays from bottom to top.

By default, this setting is set to (OFF).

Data Mapper

Setting

Description

Data Mapper Table

The Data Mapper table is where you'll enter the logic for the Data Mapper component. The first column (skipping cell A1) is where you add your inclusion logic for the row. As long as the logic equals TRUE, the row attaches. For example, =TRUE, or =IF(age>18, TRUE, FALSE).

The first row (skipping cell A1) is where you define your keys. Treat this row like column headers in an Excel spreadsheet.

Actions Settings

Actions

A static image dispalying the DataMapper component's Actions 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.

Watch Field

Enter the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. of the component you want the Data Mapper component to watch. The Data Mapper component refreshes on each new entry in the Watch Field.

By default, the Data Mapper component watches all fields. Leave this field blank to continue with default settings.

Advanced Settings

A static image displaying the Data Mapper's Advanced settings.

Setting

Description

Disable Execution

If Disable Execution is set to  (ON), the logic tied to this component does not execute. Use this to keep the component's settings, but disable the operations it performs.

By default, this setting is set to (OFF).

Prevent Execution While Loading Data

When set to  (ON), stops the end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. from saving data until the component fully loads. When set to (OFF), the end-user can save data before the component fully loads.

By default, this setting is set to (OFF).

Adding a Data Mapper Component

In this example, configure a Data Mapper component to create an array with a single row of data based on an end-user's End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. name and salary. In the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software., you'll see an extra data point stored in the array. That data point, based on the salary input, determines if the end-user qualifies for a program.

Configure the First Text Field Component

Configure a Text Field component so your end-user can enter their first name.

1. In the Module Builder, drag and drop a  Text Field component onto your canvas.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter firstName.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.  field, enter First Name.
4. Navigate to the Validation settings.
5. Set Required to  (ON).
6. Click Save Component.

Configure the Second Text Field Component

Configure a second Text Field component so your end-user can enter their last name.

1. Drag and drop a second  Text Field component onto your canvas, placing it below the firstName  Text Field component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter lastName.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Last Name.
4. Navigate to the Validation settings.
5. Set Required to  (ON).
6. Click Save Component.

Configure the Number Component

The Number component is where your end-user enters their salary. Depending on the end-user's input, the system records them as qualified or not.

1. Drag and drop a Number component onto the canvas, placing it below the lastName  Text Field component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter salary.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Your Salary.
4. In the Prefix field, enter $.
5. Navigate to the Validation settings.
6. Set Required to  (ON).
7. Click Save Component.

Configure the Data Mapper Component

Lastly, configure the Data Mapper component to create the logic that maps data to the database.

1. Drag and drop a Data Mapper component onto the canvas, placing it below the salary Number component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. and Canvas Label Text 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 . fields, enter dmQualified.
3. In the Data Mapper configuration table, enter the following:
 

A

B

C

D

E

1

 

firstName

lastName

salary

qualified

2

=TRUE

firstName

lastName

salary

=IF(salary>50000, "yes", "no")

A static image displaying the Data Mapper component's Actions settings. The Trigger type is set to watch, and the Data Mapper table is filled out.

4. Navigate to the Actions settings.
5. From the Trigger Type drop-down, select Watch.
6. Click Save Component.
7. Save your module.

Preview your module in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View. and enter values in the fields. Open the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software. and use the Angular command The Angular command, or data command, is a tool that displays submission data in a browser's developer console. In Express View, enter the following command in the devtool console: angular.element('.unqorkio-form').scope().submission to view the submission data Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections.. Expand the dmQualified key to view your Data Mapper array. In the image below, the salary is less than $50,000. So, the Data Mapper component records  "qualified":"no".

A static image displaying the module in Express View. The DataMapper data displays using the Angular command.

Overview

The Data Mapper is a Centauri (v1.0) The Centauri (v 1.0.0) runtime is the first-generation foundation of the Unqork Designer Platform. Centauri provides Creators a codeless experience for developing applications. component that manipulates submission data Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections. captured from other components using Excel formulas and Lodash functions.

Data Mapper component configurations commonly use IF The If/Then system is a logical structure used to define conditional statements, where a specific condition (If), triggers an action or outcome (Then). In this system, if the specified condition evaluates as true, the corresponding action or result will follow. statements. IF statements let you make logical decisions based on an input value using the following format: =IF(condition, valueIfTrue, valueIfFalse).

A few scenarios lend themselves particularly for using the Data Mapper component:

You can find the Data Mapper component in the Data & Event Processing group to the left of the Module Builder.

About the Configuration Window

To learn more about general component settings, view our General Component Settings article.

Display Panel

A static image displaying the DataMapper component's Display settings.

Setting

Description

Canvas Label Text

Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.

User-friendly labels make your module more accessible. Keep labels short and descriptive (a word or two) using title case. For longer entries, use sentence case.

Data Panel

A static image displaying the Data Mapper component's data settings.

Data Storage

Setting

Description

Store Data in Database

The Store Data in Database setting affects how data persists through your application. When set to  (ON), Unqork stores values entered into the field to the database (server-side submission). This occurs in three scenarios:

  • Navigating between Panels in a Navigation component. On navigation between pages (Panels), the component’s value saves to the database.

  • Triggering a module save event using a Button component with an Action Type of Save.

  • Navigating between screens of a workflow. On navigation between screens, the component’s value saves to the database.

By default, workflows persist data from all fields in the client-side submission when navigating between screens. However, only values from fields with Store Data in Database enabled store in the server-side submission.

Set the toggle to (OFF) when you don’t want to store the values from this field in the database.

When using a Plug-In to remote execute a module, ensure data moving between modules is persistent. You can optionally enable Store Data in Database for components in the source module. But any components in the API module whose values are included in an API response must have Store Data in Database enabled. When a component’s data is not persistent, the data isn't included in an API call's response. So, Plug-Ins or external services requesting data from the API module can't receive non-persistent data in the response.

Store Data in Database also affects what data is tracked using Unqork’s built-in tracker. When the Enable Tracker and Track Value toggles are set to  (ON) in Module Settings, only values from fields with Store Data in Database enabled are tracked.

Actions Panel

A static image dispalying the DataMapper component's Actions settings.

Actions

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.

Watch Field

Enter the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. of the component you want the Data Mapper component to watch. The Data Mapper component refreshes on each new entry in the Watch Field.

By default, the Data Mapper component watches all fields. Leave this field blank to continue with default settings.

Data Mapper

Setting

Description

Data Mapper Table

The Data Mapper table is where you'll enter the logic for the Data Mapper component. The first column (skipping cell A1) is where you add your inclusion logic for the row. As long as the logic equals TRUE, the row attaches. For example, =TRUE, or =IF(age>18, TRUE, FALSE).

The first row (skipping cell A1) is where you define your keys. Treat this row like column headers in an Excel spreadsheet.

Advanced Panel

A static image displaying the Data Mapper's Advanced settings.

Set Execution

Setting

Description

Disable Execution

If Disable Execution is set to  (ON), the logic tied to this component does not execute. Use this to keep the component's settings, but disable the operations it performs.

By default, this setting is set to (OFF).

Prevent Execution While Loading Data

When set to  (ON), stops the end-user End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. from saving data until the component fully loads. When set to (OFF), the end-user can save data before the component fully loads.

By default, this setting is set to (OFF).

Additional Data Options

Setting

Description

Restrict Search to Array

When set to  (ON), the Data Mapper component only iterates through the array defined in the Watch Field setting. When set to (OFF), the Data Mapper component iterates through the defined array and any other fields in your module.

By default, this setting is set to (OFF).

Include All Fields

When set to  (ON), the Data Mapper component adds all columns defined by the Data Mapper table into the Data Mapper array. When enabled, this setting also includes fields that do not contain any data. For example, if a given row contains no data in the valueB column, the array will include "valueB":"" in that row's object.

When set to (OFF), the Data Mapper component omits empty cells from the Data Mapper array. So, the valueB key/value pair does not appear in that row's object.

By default, this is setting is set to (OFF).

Wrap in Table

When set to  (ON), the Data Mapper array saves in the submission data as an HTML HTML (Hyper Text Markup Language) is the standard markup language for for achieving font, color, graphic, and hyperlink effects when creating web pages. table. The table's column headers are represented as Data Element and Values. The table populates with the Data Mapper array's key/value pairs. When set to (OFF), the Data Mapper array saves in the submission data as an array.

By default, this setting is set to (OFF).

Traverse Array Bottom to Top

When set to  (ON), the Data Mapper component searches arrays from bottom to top.

By default, this setting is set to (OFF).

Adding a Data Mapper Component

In this example, configure a Data Mapper component to create an array with a single row of data based on an end-user's End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product. name and salary. In the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software., you'll see an extra data point stored in the array. That data point, based on the salary input, determines if the end-user qualifies for a program.

Configure the First Text Field Component

Configure a Text Field component so your end-user can enter their first name.

1. In the Module Builder, drag and drop a  Text Field component onto your canvas.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter firstName.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.  field, enter First Name.
4. To the left of the component's configuration window, click Validation Icon Validation.
5. Set Required to  (ON) .
6. Click Save & Close.

Configure the Second Text Field Component

Configure a second Text Field component so your end-user can enter their last name.

1. Drag and drop a second  Text Field component onto your canvas, placing it below the firstName  Text Field component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter lastName.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Last Name.
4. To the left of the component's configuration window, click Validation Icon Validation.
5. Set Required to  (ON) .
6. Click Save & Close.

Configure the Number Component

The Number component is where your end-user enters their salary. Depending on the end-user's input, the system records them as qualified or not.

1. Drag and drop a Number component onto the canvas, placing it below the lastName  Text Field component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. field, enter salary.
3. In the Label Text Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field. field, enter Your Salary.
4. In the Prefix field, enter $.
5. To the left of the component's configuration window, click Validation Icon Validation.
6. Set Required to  (ON).
7. Click Save & Close.

Configure the Data Mapper Component

Lastly, configure the Data Mapper component to create the logic that maps data to the database.

1. Drag and drop a Data Mapper component onto the canvas, placing it below the salary Number component.
2. In the Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. and Canvas Label Text fields, enter dmQualified.
3. To the left of the component's configuration window, click Actions Icon Actions.
4. From the Trigger Type drop-down, select Watch.
5. In the Data Mapper table, enter the following:
 

A

B

C

D

E

1

 

firstName

lastName

salary

qualified

2

=TRUE

firstName

lastName

salary

=IF(salary>50000, "yes", "no")

A static image displaying the Data Mapper component's Actions settings. The Trigger type is set to watch, and the Data Mapper table is filled out.

6. Click Save & Close.
7. Save your module.

Preview your module in Express View Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View. and enter values in the fields. Open the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software. and use the Angular command The Angular command, or data command, is a tool that displays submission data in a browser's developer console. In Express View, enter the following command in the devtool console: angular.element('.unqorkio-form').scope().submission to view the submission data Also known as Record Data. Submission data consists of information saved by Unqork components. View submission data by using the angular command, or in Record Collections.. Expand the dmQualified key to view your Data Mapper array. In the image below, the salary is less than $50,000. So, the Data Mapper component records  "qualified":"no".

A static image displaying the module in Express View. The DataMapper data displays using the Angular command.

Data Structure of a Data Mapper Component

The Data Mapper component's data stores in an array. In the above example, the dmQualified  Data Mapper component stores the firstName  Text Field, lastName  Text Field, and salary Number components in the first row (0) of the array. The Data Mapper component's logic creates the qualified key/value pair that validates if the end-user makes more than $50,000 based on the value in the salary Number component.

A static image displaying the data structure of a DataMapper component that contains three other components.

Resources