Mapper
The Mapper action creates custom output by combining the outputs of various actions and restructuring the objects, collections, arrays, or strings of the output as per your needs. You can also perform various functions on the output. This eliminates the need to write complex Node.js codes to retrieve and combine particular field values or outputs from multiple actions. Mapper provides a number of modular functions that help you achieve the following:
• Combine outputs
• Iterate objects, arrays, strings, and collections
• Manipulate and test values
Using Mapper Action
To use this action in your workflow, connect it to ThingWorx Flow. To connect to the flow, do the following:
1. Click 
, drag the Mapper action under the Developer Tools utility to the canvas, place the pointer on the action, and then click 
or double-click the action. The Mapper action window opens.
, drag the Mapper action under the Developer Tools utility to the canvas, place the pointer on the action, and then click or double-click the action. The Mapper action window opens.2. Edit the Label name, if needed. By default, the label name is same as the action name.
3. Click 
to create a new key value pair.
to create a new key value pair.a. Rename the key field and enter the value. You can map the output of the previous actions as an input to the value field.
b. Click </> to add functions on the specified input.
Click to add multiple key value pairs.
to add multiple key value pairs.4. Click Done.
Mapper Data Types
Mapper accepts input values of Array, Collection, Object and String data type.
• Array—Used when the specified key returns an array. To set array as a data type, click and select Array from the list. You can apply functions on arrays by clicking </>.
and select Array from the list. You can apply functions on arrays by clicking </>.• Collection—This data type is used when the specified key returns an array of objects. A collection from a previous action can be directly mapped to the value field as the collection key or Key-Value pairs can be added separately under the collection key.
To set collection as a data type, click and select Collection from the list. You can apply functions on collections by clicking </>.
and select Collection from the list. You can apply functions on collections by clicking </>.• Object—Used when the specified key returns an object. An object from a previous action can be directly mapped to the value field as the object key or Key-Value pairs can be added separately under the object key.
To set object as a data type, click and select Object from the list. Here, you need to specify a name for the object and then click the '+' link given beside the Key field to add key-value pairs. You can then select any data type for each of these properties.
and select Object from the list. Here, you need to specify a name for the object and then click the '+' link given beside the Key field to add key-value pairs. You can then select any data type for each of these properties.The console (</>) link through which you can apply functions, is located beside the 'Object name' field as well as beside each 'Property name' field of that object.
• String—Used when the specified key returns a String value. By default, all the key-value pairs are of String data type. You can apply functions on strings by clicking </>.
Using Built-in Functions in Mapper
Mapper lets you perform various functions on the output of previous actions. The action provides a number of pre-built functions (taken from 'lodash' library) that you can use. Alternatively, you can write your own custom functions.
• Array functions:
◦ _.Compact—Removes falsely values from the given array. Read More
◦ _.difference—Returns an array with values that are unique to the first array from the given number of arrays. Read More
◦ _.flatten—Flattens an array a single level deep. Read More
◦ _.flattenDeep—Flattens an entire array. Read More
◦ _.intersection—Returns an array with values that are common in all the given arrays. Read More
◦ _.first—Retrieves the first element of the given array. Read More
◦ _.last—Retrieves the last element of the given array. Read More
◦ _.uniq—Removes the duplicate values from the given array. Read More
• Object functions
◦ _.pick—Returns an object with elements that match the specified object property. Read More
◦ _.get—Returns the value of an element present at the specified path in an object. Read More
◦ _ keys—Creates an array of the enumerable property names of an object. Read More
• String functions
◦ _.camelCase—Changes the string case to camelCase. Read More
◦ _.capitalize—Changes the first character of the string to upper case and remaining to lower case. Read More
◦ _.kebabcase—Changes the string case to kebabCase. Read More
◦ _.lowercase—Converts the specified string to lowercase. Read More
◦ _.lowerfirst—Converts the first character of the string to lowercase. Read More
◦ _.replace—Replaces the string that match the specified condition with a particular string. Read More
◦ _.repeat—Repeats the given string specified number of times. Read More
◦ _.escape—Converts the characters &, <, >, ', and " in string to their corresponding HTML entities. Read More
◦ _.trim—Removes leading and trailing whitespaces and specified characters from the given string. Read More
◦ _.unescape—Converts the HTML entities &, <, >, ", ', and ` in the given string to their corresponding characters. Read More
• Number functions
◦ _.add—Adds two numbers. Read More
◦ _.ceil—Rounds up the number to the specified precision. Read More
◦ _.divide—Divides two numbers. Read More
◦ _.floor—Rounds down the number to the specified precision. Read More
◦ _.multiply—Multiplies two numbers. Read More
◦ _.subtract—Subtracts two numbers. Read More
• Collection functions
◦ _filter:—Returns the array with elements that meets the specified filter condition. Read More
◦ _.find—Returns the first element that meets the specified condition. Read More
Example: Using the Built-in Functions in Mapper
You want to retrieve unique values from the given lists of arrays into a single array. To do this, use the Array Operations action to concat two arrays (containing a few common values). Then use the output in Mapper, and perform _.uniq function to filter out duplicate values.
1. Add Array Operations, Mapper and Send an Email actions to your canvas and connect them as shown below:
2. Configure the Array operations action as follows:
◦ Select Array Operation—Select Concat from the list.
◦ Source Array 1—Enter the first array that you want to concatenate.
◦ Source Array 2—Enter the second array that you want to concatenate.
Click Add to add more arrays.
We have used ‘R2-D2’ and ‘Han’ in both the arrays on purpose. This creates an array containing repetitive values. Click Done. This takes you back to the canvas.
3. Configure the Mapper action as follows:
◦ Key1—Enter the name of the key.
◦ Click to select the Array Data Type, and then click 
to add function.
to select the Array Data Type, and then click to add function.
◦ Click 
, and then click 
to add the output of the Array Operations action as an input in the console window.
, and then click to add the output of the Array Operations action as an input in the console window.
◦ Click Functions, and then select _.uniq function to remove duplicate values from the array.
◦ Click SAVE. The Custom Function tab is added as an input in the Value field.
4. Configure the Send an Email action as follows:
◦ To—Enter the email ID of the recipient.
◦ Subject—Enter the subject of the email.
◦ Body Type—Select the Text body type of the email.
◦ Body—Add the output of the Mapper action given on the right hand side of the configuration window as an input for this field.
5. Click Done and Execute the workflow. This retrieves unique values from the given lists of arrays into a single array and send it to the specified recipient.
Adding Custom Functions in Mapper
The Mapper action also allows you to write custom functions to perform operations on given input value. See the following example to understand the custom function:
Example
Continuing with the earlier example. Suppose you want to apply a custom function on the output of the _.uniq function implemented earlier.
1. Make the following changes in the existing code as in the figure that follows:
2. After adding the custom function in the console. Click SAVE, and then Execute the workflow.
 | You can also write only custom functions that can be implemented on the specified inputs. |
Output Schema
The Mapper action returns an output schema depending on key value pairs that you enter. See a sample output schema in the figure that follows:
