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.
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:
This can be solved either by changing the field type in the mapping screen (the little pencil icon on the field) or by changing the block model.
In this screenshot, the zip code field has a string type in the source model, but a number type in the target model:
To fix this we must change the data type for this field, by clicking the pencil icon.
You are now able to map the Source zip field to the Target zip field.
Save the mappings, and then save the workflow.