Mapping
As you build a transformation, you may notice a sequence of steps that you want to repeat. This repetitive part can be turned into a mapping.
A mapping is a transformation with placeholder input and output steps. The mapping transformation is executed through the Mapping step in a parent transformation. Because the parent transformation runs a separate transformation through a specific step, the mapping transformation is commonly referred to as a sub-transformation.
Use mapping when you want to reuse a sequence of steps across transformations.
Before you begin
Create (or identify) the sub-transformation you want to run.
Your sub-transformation must include placeholder steps that define where the sub-transformation receives input and produces output:
You can use more than one Mapping Input/Output Specification step when you need multiple entry points.
Configure the Mapping step
Step name and transformation
Step name
Specifies the unique name of the step on the canvas. A step can be placed on the canvas several times; however, it represents the same step multiple times. Default: Mapping (sub-transformation).
Transformation
Specify your mapping sub-transformation to execute. Select Browse to locate the transformation in the VFS browser.
If you select a transformation that has the same root path as the current transformation, the variable ${Internal.Entry.Current.Directory} is inserted automatically in place of the common root path. For example, if the current transformation path is /home/admin/transformation.ktr and you select a transformation in the folder /home/admin/path/sub.ktr, then the path is converted automatically to ${Internal.Entry.Current.Directory}/path/sub.ktr.
If you are working with a repository, specify the name of the transformation. If you are not working with a repository, specify the XML file name of the transformation.
Options (tabs)
The Mapping step includes tabs for passing variables and defining data flow.
Parameters tab
Use this tab to define or pass Kettle variables to the mapping sub-transformation.
Variable name
A variable name to pass to the sub-transformation.
String value (can include variable expressions)
The value to assign to the variable name. You can include variable expressions.
Inherit all variables from the parent transformation
Makes all variables available in the parent transformation available in the sub-transformation, even if they are not explicitly listed in this tab.
If Inherit all variables from the parent transformation is not selected, only the variables listed in the Parameters tab are passed to the sub-transformation.
Input tab
Although one input entry point is available by default, you can create additional input entry points. Each input corresponds to one Mapping Input Specification step in the sub-transformation.
You can use any number of entry points, including no input entry point.
Available inputs (Add input)
Select the plus button to add an input mapping. To remove an input, select the X icon.
Main data path
Select when you have one input mapping and you want to leave Input source step name and Mapping target step name empty.
Input source step name
The step in the parent transformation to read from. This can be any step in the parent transformation with an outgoing hop connected to the Mapping step. Select Choose to select a step from a list.
Mapping target step name
The Mapping Input Specification step inside the sub-transformation that receives rows from the input source step. Select Choose to select a step from a list.
Description
A description of the input mapping.
Update mapped fields downstream
Renames fields back to their original names when they reach the Mapping Output Specification step. This can make sub-transformations more transparent and reusable. If not selected, fields are renamed before they are transferred to the sub-transformation.
Mapping
Opens the mapping dialog where you map fields from the input source step to fields in the target Mapping Input Specification step.
Add field mappings in the Input tab
Select Mapping.
Select a Source Field.
Select a Target Field.
Select Add.
To remove a mapping, select Delete.
Select OK.
Output tab
By default, one output entry is available; however, you can add more output entries. Each output corresponds to one Mapping Output Specification step in the sub-transformation.
You can use any number of entries, including no output entry.
Available outputs (Add output)
Select the plus button to add an output mapping. To remove an output, select the X icon.
Main data path
Select when you have one output mapping and you want to leave Mapping source step name and Output target step name empty.
Mapping source step name
The Mapping Output Specification step in the sub-transformation where rows are read from. Select Choose to select this step from a list.
Output target step name
The step in the parent transformation that receives rows from the mapping source step. This can be any step whose incoming hop is connected to the Mapping step. Select Choose to select a step from a list.
Description
A description of the output mapping.
Mapping
Not available in the Output tab.
Logging
To differentiate log lines from a mapping, edit the kettle.properties file and set the KETTLE_LOG_MARK_MAPPINGS variable to Y.
When KETTLE_LOG_MARK_MAPPINGS is set to Y, PDI precedes log lines with the Mapping step name and the mapping name.
Samples
Sample transformations demonstrating the Mapping step are available at:
design-tools/data-integration/samples/transformations/mapping
simple mapping.ktr(a sub-transformation)use simple mapping.ktr(a parent transformation)
Suppose you have a JavaScript step that you want to reuse in several transformations. This sample uses a simple concatenation to demonstrate mapping.
The two input fields (strings) that the script needs are leftValue and rightValue. Define these fields in the Mapping Input Specification step.
The calculated value res is a field you want to pass to the parent transformation, so add a Mapping Output Specification step.
Mapping input/output specification steps are placeholders. They do not include processing logic.
The resulting mapping looks like the following example:
In this example, there are two fields coming into the Mapping step (A and B). A mapping is made between:
AandleftValueBandrightValueresandX(the result field)
This mapping is configured with the Input and Output tabs of the Mapping step.
In this sample, only one input and one output mapping are used. However, you can specify 0, 1, or more input/output mappings in a mapping transformation.
In the sample, the Main data path option is selected. The corresponding Output tab shows the field names in the mapping and target steps.
See also
Last updated
Was this helpful?