Mapping

Integromat Support Team Updated June 03, 2020 19:12

In Integromat, mapping is the process of assigning a module's outputs (structured into items) to the succeeding modules' input fields in the module setup panel with the help of the mapping panel.

Bundles & items

The operation of a module produces zero, one, or more bundles as its output. A bundle consists of one or more items.

To explore the output of a module, execute it and click on the bubble above the module. A log containing all of the module's phases will pop up. The bundle(s) outputted by a module's operation phase can be found under the OUTPUT heading. Each bundle contains its items and their values.

The following example shows the module Email > Watch emails. You can see it performed one operation producing a single bundle with various items like Date, Email ID (UID), size, etc.:

Mapping an item

Once you have created a sequence of modules by linking two or more modules, each module can process values of items outputted by the modules that precede it. The following steps describe how to assign the items to a module's input fields:

1. Click on the module that should process the output of the preceding module(s). The module settings panel will pop up.
2. Click a field where you would like to use the value of an item outputted from the preceding module(s).
3. The mapping panel will pop up and offer various items outputted from the preceding module(s) and also display sample values next to the item's labels:
   
4. Insert an item from the mapping panel into the field by clicking on the item in the mapping panel or by dragging and dropping it into the field:
   

Formulas

You may map multiple items into a field, combine them with literals (fixed values), and employ Operators and Functions to build complex formulas:

The functions and operators can be found in the mapping panel under one of its tabs:

• Items outputted from previous modules (grouped by modules)
• General functions - see General Functions
• Math functions - see Math Functions
• Text and binary functions - see String Functions
• Date and time - see Date & Time Functions
• Functions for working with arrays - see Array Functions
• Integromat

Collections

Some items can contain multiple values of various types. These items are of the type called, Collection and can be distinguished by a small black rectangle displayed to the right of the item's label and its automatically expanded list of sub-items:

Arrays

Some items can contain multiple elements of the same type. These items are of the type, Array and can be distinguished by square brackets at the end of the item's label. Click the small black rectangle to the right of the item's label to reveal the element's items:

Mapping an array's first element

If you map the array's Recipient name item, it will appear in the field like this:

The number in the square brackets is an index that determines which element of the array will be used. It is set to one by default.

Mapping an array's n-th element

If you wish to access another element, click on the square brackets and edit the index value:

Mapping an array's element with a given key

Some arrays contain several collections with key and value items. These are typically various metadata, attributes, etc.

The following example shows the output of the WooCommerce > Get a product module that contains the item Meta data, which is an array of collections. Each collection contains the key item Meta data ID and the value item Value:

The typical requirement is to lookup an element by its given key value and obtain the corresponding value from the value item. This can be achieved with a formula employing a combination of the map() and get() functions. The following example shows how to obtain the value of the Value item of the element with key Meta data ID item value equal to 20642:

The result of the formula will be "no".

The detailed breakdown of the formula follows:

1. The 1st parameter of the map() function is the whole array item.
2. The 2nd parameter is the raw name of the value item. To obtain the raw name, hover the mouse cursor over the item in the mapping panel:
   
   All parameters are case sensitive. Even though in this particular example the item's label differs from its raw name only in capitalization, it is necessary to use the raw name, which is all lowercase value in contrast to the label Value.
3. The 3rd parameter is the raw name of the key item:
   
4. The 4th parameter is the given key value.

Because the map() function returns an array (as there could be more elements with the given key value), it is necessary to apply the get() function to get its first element:

1. The 1st parameter of the get() function is the result of the map() function.
2. The 2nd parameter is the element's index - one.

See also our Extract an item and/or its value from an array of collections video tutorial.

Converting elements to a series of bundles

Arrays can be converted to a series of bundles using the Iterator module:

Troubleshooting

Missing items in the mapping panel

For each module, the mapping panel displays all output items listed by the author of the module. In some cases, this list might be incomplete for various reasons and some items might be missing. Nevertheless, Integromat can auto-discover the missing output items. All you have to do is to execute the module in the scenario editor. The exact procedure differs slightly depending on the module's type:

Instant trigger

1. Right-click the module.
2. Choose "Run this module only" from the context menu.
3. If there are no queued webhooks, the module will be waiting for a new webhook to process.
4. Generate a webhook (e.g. if the module is Slack > Listen for new events, which is watching for new channel messages in a channel, then send a message to the channel).
5. The module should finish running.
6. Click the "bubble" above the module to explore its full output.
7. The mapping panel will now contain all the items that were discovered in the module's output.

Polling trigger

1. Right-click the module.
2. Choose "Run this module only" from the context menu.
3. If there is no output, click on the "Choose where to start" button and adjust the settings. If there is no event to be processed, create one (e.g. if the module is Gmail > Watch emails then send an email to the folder the module is watching) and go back to step 2.
4. The module should finish running.
5. Click the "bubble" above the module to explore its full output.
6. The mapping panel will now contain all the items that were discovered in the module's output.

Other modules

You may choose to execute:

• The whole scenario (or just the part containing the module). If your scenario starts with a trigger, refer to the Instant/Polling trigger section above.
• Just the single module

If you choose to execute just the single module then:

1. Right-click the module.
2. Choose "Run this module only" from the context menu.
3. Provide sample values for the input items and click on the "OK" button.
4. The module should finish running.
5. Click the "bubble" above the module to explore its full output.
6. The mapping panel will now contain all the items that were discovered in the module's output.