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:
|
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 By default, Disable Execution is set to |
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
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 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 |
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 ![]() |
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 ![]() |
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 ![]() |
3. | Click the ![]() |
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 ![]() |
3. | Save your module. |