Map Values Operator

The Map Values operator updates multiple values in a table. Using a mapping table, you can quickly modify many values across multiple keys in a single step. This process is known as data normalization, which enables you to introduce consistency and accuracy across module data.

Use the Map Values operator to:

• Update values before presenting them to your end-user. For example, convert text from camel case title or sentence case.

• Refresh values imported from external or outdated sources.

• Standardize data across multiple data sets.

• Align similar values within a single data set, such as correcting spelling variations or abbreviations.

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

Similar Data Workflow Operators

The Map Values, Map Keys, and Create Field operators are closely related but serve different purposes.

Here are the comparisons:

• Map Keys operator: The Map Keys operator updates the keys in a set of key/value pairs. In comparison, Map Values updates the values in a set of key/value pairs.

• Create Field operator: Similar to Map Values, Create Field can also update values in key/value pairs. However, Create Field lets you use conditional logic with if statements and doesn’t rely on a mapping table. Instead, you define the value changes directly in the operator’s Info window.

About the Info Window

Here's a breakdown of each setting in the Map Values operator’s Info window:

Adding a Map Values Operator

In this example, you'll use 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. Because the Map Values operator updates table-based data, begin by configuring a Data Table component.

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.

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

Configure the First Data Table Component

Configure a Data Table component that you can use as a data source. It will include location data with the same value in two columns. In this case, the value CA refers to both the country Canada and the state California.

1. In the Module Builder, drag and drop a Data Table component onto your canvas.

2. In the Label and Property Name fields, enter dtData.

3. In the data table, enter the following:

   #	A	B
   1	country	stateprovince
   2	US	CA
   3	US	NY
   4	CA	ON
   5	CA	NS
   6	CA	BC
   7	US	AZ
   8	CA	AB
   9	US	CA

   

4. Click Save.

Configure the Second Data Table Component

The second Data Table component is an essential part of using the Map Values operator. Here, you'll create a two-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 update. In the second column, newValue, you'll list the new values you want to use. 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 dtData Data Table component.

2. In the Label and Property Name fields, enter dtMapping.

3. Complete the data table as follows:

   #	A	B
   1	oldValue	newValue
   2	CA	CAN
   3	US	USA

   You don't need to include quotation marks around your values.

   You can list the values you want to change in any order in the oldValue column. As long as the values exist in the data source, the Map Values operator will know to update them.

   

4. Click Save.

Configure the Hidden Component

Next, you'll configure a Hidden component to store your final data and reference it in your Data Workflow.

1. Drag and drop a Hidden component onto your canvas, placing it below the dtData and dtMapping Data Table components.

2. In the Property ID and Canvas Label Text fields, enter updatedTable.

   

3. Click Save.

Configure the Data Workflow Component

Next, let's configure 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 updatedTable Hidden component.

2. In the Canvas Label Text and Property Name fields, enter dwfMapValues .

Configure the Input Operators

1. Drag and drop two Input operators onto your Data Workflow canvas.

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

   Setting	Value
   Category	Input
   Component	dtData
   Required	Yes
   Source	Default

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

   Setting	Value
   Category	Input
   Component	dtMapping
   Required	Yes
   Source	Default

Configure the Console Operators

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

1. Drag and drop two Console operators onto your Data Workflow canvas.

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

   Setting	Value
   Category	Console
   Label	Mapping Table

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:

   Setting	Value
   Category	Console
   Label	Before Map Values

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 that the values you'll enter in the Info window's Source Column and Target Column fields match the column headers in the dtMapping Data Table component, 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.

The Map Values operator has two 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:

   Setting	Value
   Category	Map Values
   Label	Map New Value
   Source Column	oldValue
   Target Column	newValue
   Keys	country

   You need to add country in the Keys field to avoid updating all instances of the value CA to CAN. Remember, your data includes the value CA as a reference to California  as well.

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

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

Configure the Third Console Operator

Next, let's add another Console operator to display the data after using the Map Values operator, 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:

   Setting	Value
   Category	Console
   Label	After Map Values

3. Connect the output port (right) of the Map New Value 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:

   Setting	Value
   Category	Output
   Component	updatedTable
   Action	value

3. 1. Connect the output port (right) of the Map New Value Map Values operator to the input port (left) of the updatedTable Output operator.

   

4. Click Save.

Configure the Button Component

Lastly, configure a Button component that 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 dwfMapValues Data Workflow component.

2. In the Property ID field, enter btnRunDWF.

3. In the Label Text field, enter Run Map Values.

4. To the left of the component’s configuration window, click Actions.

5. Set the Action Type as Event.

6. From the On Click drop-down, select dwfMapValues.

   

7. Click Save & Close.

8. Save your module.

Here's how the completed example looks in the Module Builder:

Here's how the completed example works in Express View. Preview your module in Express View and open the DevTools Console. Click the Run Map Values button and view how the data displays in the console.

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: