Map Values Operator

Overview

The Map Values operator lets you update multiple values in a table at once. With the help of a mapping table, you can easily update many values, across multiple keys, in one go. You'll sometimes hear this process referred to as "data normalization". The Map Values operator is a great tool for bringing consistency and cohesion to your data.

Common scenarios when you might use the Map Values operator include:

• Updating values before presenting them to your end-user. For example, changing values from camel case to title or sentence case.
• Updating values retrieved from outside or outdated sources.
• Standardizing values between data sets.
• Standardizing similar values in a single data set. For example, standardizing multiple spellings or abbreviations.

You’ll find the Map Values operator under the Table group at the left of the Data Workflow canvas.

Similar Data Workflow Operators

The Map Values and Map Keys operators are siblings, but functionally different. Map Values is functionally similar, though, to the Create Field operator.

Here are the comparisons:

• Map Keys operator: The Map Keys operator lets you update the keys in a set of key/value pairs. By comparison, Map Values updates values in a set of key/value pairs.
• Create Field operator: The Create Field operator can also update values in key/value pairs. With Create Field, though, you can use IF statements to conditionally update values. Create Field also differs in that it doesn't use a mapping table. With Create Field, you use the operator's Info window to define what values to change.

What You'll Learn

In this article, you'll learn:

• About the Map Values operator's settings.

• How to add and configure a Map Values operator.

• How to modify a Map Values operator's settings.

• How to copy a Map Values operator.

• How to remove a Map Values operator.

About the Info Window

Here's what the Map Values operator looks like, along with its Info window:

And here's a breakdown of each setting in the Info window:

Setting	Description
Category	Grayed out and non-adjustable setting indicating the operation type.
Label	Sets the label for your operator. The label you enter here shows beneath your operator on your Data Workflow canvas. This field is optional, but set a label if you use more than one of the same operator type. A label helps you identify your operators without opening any Info windows.
Source Column	Enter the name (column header) of the column in your mapping table that defines the original values.
Target Column	Enter the name (column header) of the column in your mapping table that defines the new values.
Keys	Enter which keys contain values you want the operator to update, according to the mapping table. To list multiple keys, use a comma-separated list. If left empty, the operator updates all keys with values that match the mapping table.

Adding a Map Values Operator

In this use case, you'll see a simple example for using the Map Values operator to update values in a table. You'll also explore the importance of using the operator's Keys setting when the same value exists across multiple keys. Since the Map Values operator updates table-based data, let's start by creating a Data Table.

TIP  You can use the Map Values operator with any table-based data, not just data created with a Data Table component. For example, you can use Map Values with data returned by the List Submissions for Dashboard API call. In that case, set up a Hidden component to store the data returned by the Plug-In running the API call. Then, use a simple Input-to-Output Data Workflow to move the data from Plug-In to Hidden component. The Hidden component is then used as the input in your Map Values Data Workflow.

Here's how the completed use case will look in the Module Builder:

Here's how the completed use case will work in Express View, including a peek at the final table in the DevTools Console:

What You'll Need

To set up this use case, you'll need:

• 2 Data Table components

• 1 Data Workflow component

• 1 Button component

• 1 Hidden component

To set up your Data Workflow, you'll need:

• 2 Input operators

• 1 Map Values operator

• 3 Console operators

• 1 Output operator

NOTE  These instructions assume you have a new module open, saved, and with a title.

Configure the First Data Table Component

First up, let's create a Data Table you can use as a data source. This will include location data that deliberately includes the same value in 2 columns. In this case, the value "CA" refers to both the country Canada and the state California.

1.

Drag and drop a Data Table component onto your canvas.

2.

Enter dtData in the Label and Property Name fields.

3.

In the data table, enter the following:

4.

Click Save.

Configure the Second Data Table Component

This second Data Table is an essential part of using the Map Values operator. Here, you'll create a 2-column table that acts as a mapping table. In the first column, oldValue, you'll list all the values you want the Map Values operator to change. In the second column, newValue, you'll list what you want the new values to be. Then, you'll reference the mapping table's column headers in the Map Values operator's Info window.

Let's update the abbreviation "US" to be "USA" and the abbreviation "CA" to be "CAN".

1.

Drag and drop a Data Table component onto your canvas, placing it below the first Data Table.

2.

Enter dtMapping in the Label and Property Name fields.

3.

Complete the data table as follows:

4.

Click Save.

Configure the Hidden Component

Next, you'll create a Hidden component to store your final table. You'll reference it in your Data Workflow, so let's set it up now.

1.

Drag and drop a Hidden component onto your canvas, placing it below the Data Tables.

2.

Enter updatedTable in the Canvas Label Text and Property ID fields.

3.

Click Save.

Configure the Data Workflow Component

Next, let's create the Data Workflow. With the help of your mapping table, it'll use a Map Values operator to update the "CA" and "US" values.

1.

Drag and drop a Data Workflow component onto your canvas, placing it below the Data Tables.

2.

Enter dwfMapValues in the Canvas Label Text and Property Name fields.

Configure the Input Operators

1.

Drag and drop 2 Input operators onto your Data Workflow canvas.

2.

Configure the first Input operator's Info window as follows:

3.

Configure the second Input operator's Info window as follows:

Configure the Console Operators

Next, let's add a pair of Console operators. These will help you compare the before and after of the Data Workflow. One will show the data before using Map Values. The other will serve as a reminder of how you set up your mapping table.

1.

Drag and drop 2 Console operators onto your Data Workflow canvas.

2.

Configure the first Console operator's Info window as follows:

3.

Connect the output port (right) of the dtMapping Input operator to the input port (left) of the Mapping Table Console operator.

4.

Configure the second Console operator's Info window as follows:

5.

Connect the output port (right) of the dtData Input operator to the input port (left) of the Before Map Values Console operator.

Configure the Map Values Operator

Now you're ready to set up the Map Values operator. Notice the values you'll enter in the Info window's Source Column and Target Column fields. They match the column headers in the dtMapping Data Table, which is your mapping table. The Source Column field should always reference the column with your old values. The Target Column field should always reference the column with your new values.

TIP  The Map Values operator has 2 input ports. Always connect the data source to the upper input port and the mapping table to the lower input port.

1.

Drag and drop a Map Values operator onto your Data Workflow canvas.

2.

Complete the operator's Info window as follows:

3.

Connect the output port (right) of the dtData Input operator to the upper input port (left) of the Map Values operator.

4.

Connect the output port (right) of the dtMapping Input operator to the lower input port (left) of the Map Values operator.

Configure the Third Console Operator

Next, let's add another Console operator. This one will show the data after using Map Values, helping you compare the before and after of your Data Workflow.

1.

Drag and drop a Console operator onto your Data Workflow canvas.

2.

Configure the operator's Info window as follows:

3.

Connect the output port (right) of the Map Values operator to the input port (left) of the After Map Values Console operator.

Configure the Output Operator

For the last step of the Data Workflow, let's output your updated table to the Hidden component you created earlier.

1.

Drag and drop an Output operator onto your Data Workflow canvas.

2.

Configure the operator's Info window as follows:

3.

Connect the output port (right) of the Map Values operator to the input port (left) of the Output operator.

4.

Click Save.

Configure the Button Component

Finally, let's create a button you can click in Express View to trigger your Data Workflow.

1.

Drag and drop a Button component onto your canvas, placing it below the Data Workflow.

2.

Enter btnRunDWF in the Property ID field.

3.

Enter Run Map Values in the Label Text field.

4.

Select Event as the Button Action Type.

5.

Enter dwfMapValues in the Trigger on Click field.

6.

Click Save.

7.

Save your module.

Now you're ready to test out your Map Values operator. Preview your module in Express View and open the DevTools Console. Click the Run Map Values button and check out what appears in the Console. It should look something like this:

NOTE  It's a good idea to use the Keys setting when updating values that occur across multiple keys. Let's look at what would have occurred if you didn't add country in the Map Values operator's Keys setting. Without specifying a key to update, the operator would have replaced all instances of "CA" with "CAN"and included the "stateprovince" value "CA". This means, the abbreviation for the state of California would have also changed to "CAN". Here's what that would have looked like:

Changing a Map Values Operator's Settings

You can revisit and make changes to this operator.

1.

Click the Data Workflow component.

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

2.

Click the (Settings) button to open the Data Workflow canvas.

3.

Click the operator to open its Info Window.

4.

Make changes to the operator's settings as needed.

5.

Click Save.

6.

Save your module.

Copying a Map Values Operator

You can make a copy of your operator using familiar keyboard settings. You can copy and paste an exact copy of your operator, matching all settings.

1.

Hover over the Data Workflow component.

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

2.

Click the (Settings) button to open the Data Workflow canvas.

3.

Click the operator you want to duplicate.

4.

On your keyboard, press Command + C (Mac OS) or Ctrl + C (Windows/Linux) to copy the operator.

5.

On your keyboard, press Command + V (Mac OS) or Ctrl + V (Windows/Linux) to paste the copied operator(s) to the Data Workflow canvas.

6.

Click Save.

7.

Save your module.

TIP  Did you know you can copy an operator and paste it into a different Data Workflow? You'll use the same steps outlined above.

Removing a Map Values Operator

Lastly, you can delete this operator from your Data Workflow canvas. You can also use these same steps to delete a connection between two operators.

1.

Hover over the Data Workflow component.

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

2.

Click the (Settings) button to open the Data Workflow canvas.

3.

Click the operator you want to delete.

4.

On your keyboard, press Delete.

5.

Click Save.

6.

Save your module.

Lab

You can view the complete Map Values use case here: https://training.unqork.io/#/form/60007a204fca2002575e0d3e/edit.