Mapping

Modules in a scenario are linked to each other by item mapping. When you map an item, you are using the data retrieved using a source module in the settings of another module, or the target module.  Values from the mapped items are then used by the module to perform the desired action.

In the following example, a sender's email address and the Subject (the email subject), "items" retrieved by the "Watch email" module and then mapped in the settings of the "Send an email" module:

What is an Item?

A module in operation produces bundles as its output, and a bundle consists of items. Generally, an item is a piece of information retrieved by a module. Item is displayed in the module's output as a label and value. Click the bubble above the module to display the module's output, per the below example.

In the following example, the item's label is "Subject" and the item's value is the message that follows.

Mapping an Item

Follow these steps to map an item from one module to another:

• Open settings of the target module, which is where you want to map items to.
• Click the field where you want to map an item from a preceding module.

This will open a mapping panel offering all items from preceding modules in the scenario that are available for mapping. Sample values are usually displayed next to the item label.

To map an item to a field, click on the item or drag-and-drop the item into the module's input field. Users may search items using the search field at the top of the mapping panel. The search is performed for both item labels and item values.

When finished, click on "OK" to close the module settings. You can repeat the action (map from the module's output to another module's input fields) in other succeeding modules added to your scenario. Please note that the number of linked modules in the scenario is not limited. For advanced mapping functions, refer to this article. 

Collections and Arrays

A module's output items that contain more items are called collections (contain items of a different type) or arrays (contain items of the same type). Collections are expanded in the mapping panel in order to allow user to easily map items contained in the collection. A collection itself is usually not mapped. See below for an example of a collection in a module's output: 

Example of a collection in the module's mapping panel:

Example of an array (containing collections of the same type) in the module's output:

Example of an array (containing collections of the same type) in the module's mapping panel:

Mapping Arrays

An array is a special item type. A simple array contains one or more text values. A complex array contains one or more collections of the same type. An example of a complex array is the email attachment. The Watch emails module returns an array of attachments for every email. Every attachment represents a collection that may contain a name, content, size, etc.

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 look up an element by its given key value and to 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". Essentially, this is what the formula represents: 

1. The first parameter of the map() function is the whole array item.
2. The 2 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 first parameter of the get() function is the result of the map() function.
2. The second parameter is the element's index, whose value is one.

Converting elements to a series of bundles

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

The outputs from modules wrapped between an Iterator and Aggregator are not accessible beyond the Aggregator 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. To resolve this, 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

• 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.