DataMapper Component

Overview

The DataMapper component 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. The Data Mapper Icon Data Mapper manipulates this data by using Excel formulas and Linkout iconLodash functions.

DataMapper component configurations commonly use IF statements. IF statements let you make logical decisions based on an input value. IF statements typically look like this: =IF(condition, valueIfTrue, valueIfFalse).

A few scenarios lend themselves particularly well to using the Data Mapper Icon Data Mapper component:

  • Organizing top-level fields into a key/value pair array and manipulating that data.

  • Iterating an existing array as defined in the Watch Field setting. For example, the output of an Advanced Data Grid Icon Advanced Datagrid component.

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

What You'll Learn

After completing this article, you’ll know when to use a DataMapper component and how to configure its settings.

About the Configuration Window

General

A static image displaying the Data Mapper component's configuration window general settings.

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.

Notes Note-Icon

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.

Display Icon Display

Select this tab to manage your component's display settings.

Data Icon Data

Select this tab to manage your component's data settings.
Actions Icon Actions

Select this tab to manage your component's actions settings.

Advanced Icon Advanced

Select this tab to manage your component's advanced settings.

Permissions Icon Permissions

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. settings of the component.

Field Tag Icon 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 Panel components. 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.

Shortcuts Icon Shortcuts

Select this tab to open the list of supported keyboard shortcuts you can use in the component settings modal. Keyboard shortcuts include:

  • Cmd + S (Mac) / Ctrl + S (PC): Save and close the component settings modal.

  • Cmd + G (Mac) / Ctrl + G (PC): Opens a search window to find specific fields and settings in the component settings modal.

  • Tab: Tab to the next field or setting in the component settings modal. This keyboard shortcut tabs left to right and top to bottom.

  • Shift + Tab: Tab to the previous field or setting in the component settings modal. The keyboard shortcut tabs from right to left and bottom to top.

  • Enter (Return): When tabbing to a Tooltip Icon (tooltip), press Enter (Return) to display the field or setting tooltip. Press Enter (Return) again to hide the tooltip.

Additional keyboard shortcuts:

  • Drop-down menus: When you Tab to a settings drop-down, use the keyboard's Up-Arrow Icon (up)/ Down-Arrow icon (down) arrows to make a selection. Then, press Enter (Return) to confirm the selection.

Documentation IconDocumentation

Select this tab to access the component documentation in Unqork's In-Product Help.

Cancel

Click this button to undo any unsaved configuration changes and return to the Module Builder canvas.

Save & Close

Click this button to save all setting  configuration changes and return to the Module Builder canvas.

Display Panel

A static image displaying the DataMapper component's Display settings.(Click image to enlarge)

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.(Click image to enlarge)

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. To learn more about Store Data in Database in the context of API modules, see the panelResponse Panel section of the API Specification Snippet article in our In-Product Help.

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.(Click image to enlarge)

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 component Icon Button or Radio Button component icon 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 DataMapper to watch. The DataMapper refreshes on each new entry in the Watch field.

By default, the DataMapper 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 DataMapper.

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 will attach. 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.(Click image to enlarge)

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 DataMapper only iterates through the array defined in the Watch Field setting. When set to (OFF), the DataMapper searches in 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 DataMapper adds all columns defined in the DataMapper table into the DataMapper array. This includes fields that don't 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 DataMapper omits empty cells from the DataMapper 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 DataMapper array saves in the submission data as an HTML table. The table's column headers are Data Element and Values. The table populates with the DataMapper array's key/value pairs. When set to (OFF), the DataMapper array saves in the submission data simply as an array.

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

Traverse Array Bottom to Top

When set to (ON), the DataMapper searches arrays from bottom to top.

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

Adding a DataMapper Component

For this example, configure a DataMapper component to create an array with a single row of data using 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, decides if the end-user qualifies for a program.

What You Need

For this configuration, you'll need the following components:

Configure the First Text Field Component

Add a  Text Field where your end-user enters 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

Add a second  Text Field for the end-user to input 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 the 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 DataMapper Component

Lastly, you'll configure the Data Mapper Icon Data Mapper component. This is where you'll create the logic that maps data into the database.

1. Drag and drop a Data Mapper Icon 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")

The IF statement tells the system that if the salary value is over $50,000, record "qualified":"yes". If the salary value is less than $50,000, record "qualified":"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.(Click image to enlarge)

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

Preview your module in Express View Express View is how your end-user views you 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 DataMapper array. In the image below, the salary is less than $50,000. So, the Data Mapper Icon Data Mapper component records "qualified":"no".

A static image displaying the module in Express View. The DataMapper data displays using the Angular command.(Click image to enlarge)

 

Data Structure of a DataMapper Component

The DataMapper component's data stores in an array. In the above example, the dmQualified Data Mapper Icon Data Mapper component stores the firstName  Text Field., lastName  Text Field, and salary  Number components in the first row (0) of the array. The DataMapper'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