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 manipulates this data by using Excel formulas and Lodash 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 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.
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
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 |
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 |
Select this tab to manage your component's display settings. |
Data |
Select this tab to manage your component's data settings. |
Actions |
Select this tab to manage your component's actions settings. |
Advanced |
Select this tab to manage your component's advanced settings. |
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 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 |
Select this tab to open the list of supported keyboard shortcuts you can use in the component settings modal. Keyboard shortcuts include:
Additional keyboard shortcuts:
|
Documentation |
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
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
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:
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 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
Actions
Setting |
Description |
---|---|
Trigger Type |
This setting provides the following options:
By default, this Trigger Type is selected.
|
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
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 . |
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:
-
2 Text Field components
-
1 Number component
-
1 DataMapper component
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. |
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. |
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. |
6. | Set Required to (ON). |
7. | Click Save & Close. |
Configure the DataMapper Component
Lastly, you'll configure the Data Mapper component. This is where you'll create the logic that maps data into 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. |
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".
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 component records "qualified":"no".
Data Structure of a DataMapper Component
The DataMapper 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 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.
Resources
-
Discover more about the DataMapper component in the Community Hub.
-
View the latest enhancements and bug fixes for the DataMapper component.