The Mapper block
- Arild Fylling (Unlicensed)
Please note that both the documentation for the Mapper block and the Mapper block itself are under development. You can expect the Mapper block to gain more features and improve going forward.
As you build workflows, you will often find that data coming out of one application will need to be reformatted before it is transferred to the destination application. That is what the Mapper block is for.
The Mapper block lets you transform data and map fields between two data formats, so that the data coming from one app is transformed for use in another app.
It is certainly possible to do the mapping completely in code, without using the Mapper block. But it will generally be preferable to use the Mapper block, as it is purpose-built for mapping and easier to maintain.
Using the mapper block
The Mapper block is a generic block type, and can be added to any integration project, regardless of apps involved.
To use it, simply drag the Mapper block onto the Canvas and configure the source and target blocks (in the “Working Area” tab):
Click the “Map model” button to begin configuring the mapping table used by the Mapper block.
When the Map Model button is clicked the Mapper block will ask the source and target blocks to give examples of the data formats that they use, referred to as the model. (You may see a green checkmark appear next to the source block as a data sample is pulled, before the mapping screen appears.)
A block model is a JSON object describing the data format that the block accepts as input or returns as output. It is essentially a list all the fields and the field types, used by the mapper block to create a mapping table.
For most ready-made blocks you will find that the block model is already setup. The block model is defined in the block template settings.
The model of the source and target blocks are used to create the mapping table, with all the field names ready to be mapped.
For the source block, the Mapper block try to construct the model dynamically, by asking the block to provide a data sample. Alternatively it will use the output model defined in the block template.
For the target block, the Mapper block will use the input model defined in the block template.
If a model is not found for a block, the field names must be entered manually into the mapping table.
The mapper block will use the block models to construct a mapping screen:
The mapping screen can be thought of as a spreadsheet with two columns – one for the source application, and one for the target application. By connecting corresponding fields, you are building a map for how data should be transformed. And like in a spreadsheet, you also have the possibility to use functions, to concatenate fields, put text to upper case, date manipulation, etc.
Expand the area on the left, and the Target column on the right, as shown in the screenshot.
You can now drag and drop fields from the area on the left into the Source column, to specify how fields will be mapped to the Target column.
When you are done, press “Save mappings” and then save the workflow.
About types
The fields will have types specified (as defined in the block models) which will prevent for example a string to be mapped directly to a number field:
If you need to map fields of different types you can either:
Change the field type in the mapping screen (the little pencil icon on the field)
Change the block model definition
Apply a function in the Mapper block to transform the field type
Here is an example where the zip code field has a string type in the source model, but a number type in the target model:
See the following article for more information about types: Mapper types