DataMapper Component

Overview

The DataMapper component is a data manipulation component. The DataMapper supports both Excel formulas and Lodash functions.

A few scenarios lend themselves particularly well to using the DataMapper 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 Datagrid component.

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

You'll find the DataMapper component in the Data & Event Processing group at the left of the Module Editor.

What You'll Learn

In this article, you'll learn how to:

About the Configuration Window

General

Setting

Description

Property ID

A Property ID is the unique field ID used by Unqork to track and link components in your module.

The Property ID is how the software identifies your component. Using Property IDs lets you link components, creating logic-based configurations and API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. calls.

Property IDs must use camel case A naming convention for computer programming. Use camelCase for Property IDs, for example: newUser, lastName, & rdoButton. (stylized as camelCase) without spaces or punctuation.

Field Tags

Assign components one-word labels to help organize, identify, and group the components in your application.

Consider an example from the API Specification Snippet: Field Tags are applied to Hidden components in the panelRequest and panelResponse Panels. The Field Tags identify the data type of parameters included in the API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. request and response. The API Docs Dashboard tool populates with information about each parameter’s data type, identified by the Field Tag.

Field Tags act as a type of Property ID A Property ID is the unique field ID used by Unqork to track and link components in your module. group and let you group components for configuration purposes. Field Tags let you target two or more components using a simple logic component.

For example, add the Field Tag tagForDecision to multiple components in your module. Open the Inputs table of a Decisions component and reference the tagForDecision Field Tag as the input of the Decisions component. The output of the Decisions component then affects all components with the tagForDecision Field Tag.

Save your Field Tags by pressing Enter (Return) or adding a comma after each entry.

Settings Tab

Select this tab to display the component's Display, Data, Actions, and Validation settings panels, as applicable.

Permissions Tab

Select this tab to see the RBAC RBAC (Role-Based Access Control) is a method to control system access for authorized users. The role in RBAC refers to the levels of access employees have to a network. (role-based access control) settings of the component.

Notes Tab

Select this tab to display the component's Notes area. You can use notes to keep your teammates informed.

The Notes editor offers a semi-WYSIWYG (What You See is What You Get) content editor. Built to look like a word processor, this editor lets you create, edit, and format your notes. Notes save when saving the component.

Cancel Button

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

Save Button

Click this button to save all settings as configured and return to the canvas.

Display Panel

Setting

Description

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.

Actions Panel

Setting

Description

Trigger Type

This setting provides the following options:

  • Manual:  The component fires when triggered by another component. For example, using a Button component or Initializer component to trigger the Plug-In component. By default, the Manual Trigger Type is selected.
  • Watch: The component fires when there's any action taken on the input component(s) listed in the Inputs table. Actions include entering a new value, editing, or overwriting a saved value. If there are multiple inputs, use the Required setting to specify what inputs must be present before firing.

Watch Field to Refresh Mapping

Enter the Property ID 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.

Disable Execution

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

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

Prevent Execution While Loading Data

Switching this toggle to ON stops the end-user from saving data until the component fully loads. With the toggle OFF, the end-user can save data before the component loads fully.

By default, the Prevent Execution While Loading Data toggle is set to OFF.

Data Panel

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 (e.g. =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 Excel.

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, the Restrict Search to Array toggle is set to OFF.

Traverse Array Bottom to Top

When set to ON, the DataMapper will search through arrays from bottom to top.

By default, the Traverse Array Bottom to Top toggle is set to OFF.

Add All Fields into the Table

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 would not appear in that row's object.

By default, the Add All Fields into the Table toggle 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, the Wrap in Table toggle is set to OFF.

Store Data in Database

The Store Data in Database setting affects how data persists through your application. When set to Toggle On Icon (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.

NOTE  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 Toggle Off icon (OFF) when you don’t want to store the values from this field in the database.

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

TIP  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 Toggle On Icon (ON) in Module Settings, only values from fields with Store Data in Database enabled are tracked.

Run Another DataMapper as Function

You can use other DataMappers as variables in your DataMapper table. To do so, reference the other DataMapper component's Property ID in this field.

Adding a DataMapper Component

Let's set up a DataMapper component to create an array with a single row of data. Your end-user will enter their name and salary. But, as you'll see in the DevTools Console, an extra data point stores in the array. That data point, based on the salary input, is whether or not the end-user qualifies for a program.

For this configuration, you'll need:

  • 2 Text Field components

  • 1 Number component

  • 1 DataMapper component

Configure the Text Field Components

These Text Fields are where your end-user enters their name.

1. Drag and drop 2 Text Field components onto your canvas.
2. Complete the Property ID and Label Text fields as follows:

Property ID

Label Text

firstName

First Name

lastName

Last Name

3. Set the Required toggle to ON in each component.
4. Save each component as you add it.

Configure the Number Component

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

1. Drag and drop a Number component onto the canvas.
2. Enter salary in the Property ID.
3. Enter Your Salary in the Label Text.
4. Enter $ in the Prefix.
5. Set the Required toggle to ON.
6. Click Save.

Configure the DataMapper Component

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

1. Drag and drop a DataMapper component onto the canvas.
2. Enter dmQualified in the Property ID and Label Text.
3. Select Watch from the Trigger Type.
4. Complete the Data Mapper table as follows:

A

B

C

D

E

 

firstName

lastName

salary

qualified

=TRUE

firstName

lastName

salary

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

NOTE  The IF statement tells the system: if the value of salary is over $50,000, record "qualified":"yes". If the value of salary is less than $50,000, record "qualified":"no".

5. Click the Save button.
6. Save your module.

Now you're ready to test out the DataMapper. Preview your module in Express View, then fill in the fields. Now check out what records in the submission data.

You can expand the dmQualified key to view your DataMapper array. For example:

Changing a DataMapper Component's Settings

Let's revisit and make changes to your saved component's settings.

1. Hover over the DataMapper component.

A 5-button toolbar appears above the component on hover-over.

2. Using the toolbar, click the (Settings) button.
3. Using the Configuration window, make changes to the component's settings as needed.
4. Click Save.
5. Save your module.

Moving a DataMapper Component

Let's move your component to a new position on your module.

1. Hover over the DataMapper component.

A 5-button toolbar appears above the component on hover-over.

2. Click and drag the (Move) button, dropping the component when it's in position.
3. Save your module.

Copying a DataMapper Component

You can make a copy of your component using the Copy and Paste tools. Copy and Paste creates an exact copy of your component, matching all settings. The only noticeable difference between the two components is the Property ID. The Property ID on the new component automatically updates. Remember, every component needs a unique Property ID. Property IDs track and connect components in Unqork.

1. Hover over the DataMapper component.

A 5-button toolbar appears above the component on hover-over.

2. Click the (Copy) button.
3. Click the (Paste) button.
4. Update the copied component's settings as needed.
5. Save your module.

Removing a DataMapper Component

Lastly, let's delete your DataMapper component from the module.

1. Hover over the DataMapper component.

A 5-button toolbar appears above the component on hover-over.

2. Click the (Remove) button.
3. Save your module.