The ‘Mapper’ action lets you create custom output by combining the outputs of various actions and re-structuring 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/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
To use this action, add it to your canvas, and configure it.
You will notice that it already contains a '+' link. When you first click the ‘+’ link, it creates a new empty key-value pair. You can rename the 'key' field, and enter the output of previous actions as an input in the 'value' field. Alternatively, you can also enter input data manually in the 'value' field.
By default, the data type of this key-value pair is set to String. You can change it to Array, Collection or Object by clicking the 'Settings' icon that appear when you hover over the ‘Key’ or ‘Value’ field.
If you wish to apply functions on the specified input, click on the 'Console (</>) icon. You can also delete the specified key-value pair, by clicking on 'Delete' link that appears when you hover over the ‘Key’ or ‘Value’ field.
This gives you the flexibility to create your own output such as a set of arrays, or a set of arrays within an object, or simply some key-value pairs within the main output.
Mapper Data types
Mapper accepts input values of Array, Collection, Object and String data type. Let's understand more about them:
Array: This data type is used when the specified key returns an array. To set array as a data type, click on 'Settings' icon and select 'Array' from the drop-down list. You can apply functions on arrays by clicking on 'Console (</>)' link.
Collection: This data type is used when the specified key returns an array of objects. To set collection as a data type, click on 'Settings' icon and select 'Collection' from the drop-down list. You can apply functions on collections by clicking on 'Console (</>)' link.
Object: This data type is used when the specified key returns an object. To set object as a data type, click on 'Settings' icon and select 'Object' from the drop-down list. When you set the data type to Object, only 'Key' field is displayed on the screen. Here, you need to specify a name for the object and then click on '+' 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. When you apply a function to the object, it will be applied to all the properties of the object. However, if you apply a function to a specific property, it will be applicable to only that property of the object.
String: This data type is 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 on 'Console (</>)' link.
Let’s understand this with an example:
Suppose you wish to retrieve the IDs and names of notebooks from your ‘Evernote’ and ‘OneNote’ account and send it to a specified recipient as a single object. To do this, follow the steps given below:
Step 1: Add ‘Evernote_Get Lists of Notebooks’, ‘OneNote_Get Notebooks’, ‘Mapper’, and ‘Notification_Send an Email’ actions to the canvas and connect them as shown below:
Step 2: Configure and provide inputs for both ‘Evernote_Get Lists of Notebooks’ and ‘OneNote_Get Notebooks’ actions.
Step 3: Configure the ‘Mapper’ action as given below:
- Click on ‘+’ icon. A new key-value pair will appear in ‘Mapper’ window. Hover over the ‘Key’ field and click on ‘Settings’ icon that appear. Select ‘Object’ from the drop-down list. You will be prompted to confirm the change in data type. Click on ‘Yes’.
You can now see only ‘Key’ field in the window. Provide a suitable name for the object in this field.
- You can see four options beside the ‘Key’ field; ‘ Settings’, ‘+’, 'Console (</>)', and ‘Delete’. Click on the ‘+’ link.
- Now, you can see an empty key-value pair under the object name. Provide a suitable name for the key and add the ID of the Evernote notebook from the output given on the right-hand side of the window, in the corresponding value field.
- Similarly, create key-value pairs for Evernote notebook name, OneNote notebook ID, and OneNote notebook name.
- Click on ‘Done’. This will take you back to canvas.
Step 4: Next, configure the ‘Notification_Send an Email’ action. Specify the email address of the recipient and add the output of ‘Mapper’ as an input for ‘Body’ field.
Once you have entered all the details, click on ‘Done’ and ‘Run’ the workflow. This will retrieve the selected parameters from two different action outputs and will return it as a single object to the specified recipient.
Now that we know how to customize the structure of the output, let’s try something advanced. 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.
Before we look at an example to understand how functions work, let’s glance through the list of pre-built functions for each data type.
1. _.Compact: Removes falsey values from the given array. Read more
2. _.difference: Returns an array with values that are unique to the first array from the given number of arrays. Read more
3. _.flatten: Flattens an array a single level deep. Read more
4. _.flattenDeep: Flattens an entire array. Read more
5. _.intersection: Returns an array with values that are common in all the given arrays. Read more
6. _.first: Retrieves the first element of the given array. Read more
7. _.last: Retrieves the last element of the given array. Read more
8. _.uniq: Removes the duplicate values from the given array. Read more
1. _.pick: Returns an object with elements that match the specified object property. Read more
2. _.get: Returns the value of an element present at the specified path in an object. Read more
3. _.keys: Creates an array of the enumerable property names of an object. Read more
1. _.camelCase: Changes the string case to camelCase. Read more
2. _.capitalize: Changes the first character of the string to upper case and remaining to lower case. Read more
3. _.kebabcase: Changes the string case to kebabCase. Read more
4. _.lowercase: Converts the specified string to lowercase. Read more
5. _.lowerfirst: Converts the first character of the string to lowercase. Read more
6. _.replace: Replaces the string that match the specified condition with a particular string. Read more
7. _.repeat: Repeats the given string specified number of times. Read more
8. _.escape: Converts the characters &, <, >, ', and " in string to their corresponding HTML entities. Read more
9. _.trim: Removes leading and trailing whitespaces and specified characters from the given string. Read more
10. _.unescape: Converts the HTML entities &, <, >, ", ', and ` in the given string to their corresponding characters. Read more
1. _.add: Adds two numbers. Read more
2. _.ceil: Rounds up the number to the specified precision. Read more
3. _.divide: Divides two numbers. Read more
4._.floor: Rounds down the number to the specified precision. Read more
5. _.multiply: Multiplies two numbers. Read more
6._.subtract: Subtracts two numbers. Read more
1. _filter: Returns the array with elements that meets the specified filter condition. Read more
2. _.find: Returns the first element that meets the specified condition. Read more
You can find more about these functions at lodash.com.
How to use built-in functions in Mapper
Let’s say you wish to retrieve unique values from the given lists of arrays into a single array. To do this, we will first use the ‘Array operations’ action to concat two arrays (containing a few common values). We will then use the output in Mapper, and perform ‘_.uniq’ function to filter out duplicate values.
Step 1: Add 'Array Operations', 'Mapper' and 'Send an Email' actions to your canvas and connect them as shown below:
Step 2: Configure the 'Array operations action' as shown below:
Array operation (Mandatory): Select 'Concat' from the drop-down list.
Source array 1 (Mandatory): Enter the first array that you wish to concatenate.
Source array 2 (Mandatory): Enter the second array that you wish to concatenate.
You can add more arrays by clicking the 'ADD' link.
We have used ‘R2-D2’ and ‘Han’ in both the arrays on purpose. This will create an array containing repetitive values. Click on 'Done'. This will take you back to canvas.
Step 3: Configure the Mapper action as shown below:
Key1 (Mandatory): Enter the name of the key.
Since we will be adding the output of the previous action on which we wish to apply function in the console window, leave ‘Value’ field empty and click on ‘Console (</>) link.
You will be redirected to a new console window.
Click on the ‘Expand’ icon given on the right hand side of the console window, and add the output of ‘Array Operations’ action, as an input in the console window.
You can see a 'Functions' drop-down list at the top of console window. Since we need to remove duplicate values from the array, select ‘_.uniq’ function listed under ‘Array’ data type. The selected function will be added to the console window. You can now write a basic code block that will apply the selected function on the input array as shown below:
Once you have written the code, click on 'Done'. This will take you back to Mapper configuration window. Here you can now see a 'Custom Function' tab added as an input in the ‘Value’ field.
Step 7: Configure the 'Send an Email' action as shown below:
To (Mandatory): Enter the email ID of the user to whom you wish to send the output.
Subject (Mandatory): Enter the subject of the email.
Body (Mandatory): Add the output of the 'Mapper' action given on the right hand side of the configuration window as an input for this field.
Click on 'Done' and 'Run' the workflow. This will retrieve unique values from the given lists of arrays into a single array and send it to the specified recipient.
How to add custom functions in Mapper
The Mapper action also allows you to write custom functions to perform operations on given input value. We will see how to do that in this section:
Example: Let’s continue with the earlier example. Suppose you wish to apply a custom function on the output of the _.uniq function we implemented earlier. You can do so by simply making changes in the existing code as shown below:
Once you have added the custom function in the console window,click on ‘Done’ and ‘Run’ the workflow.
You can also write only custom functions that can be implemented on the specified inputs.
- text string