Skip to main content
Pentaho Documentation

Simple Mapping

As you build a transformation, you may notice a sequence of steps you want to repeat. This repetitive part can be turned into a mapping.

Just like the Mapping step, you can use the Simple Mapping step to turn the repetitive, re-usable part of a transformation into such a mapping.  

Compared to the Mapping step, the Simple Mapping step accepts one and only one input and output step.  As such, it behaves like any other regular step which reads and writes rows of data.

Also, as with the Mapping step, input and output are defined by the following placeholder steps:

  • Mapping input step: a placeholder where the mapping expects input from the parent transformation.
  • Mapping output step: a placeholder from where the parent transformation can read data.

The mapping executed by the parent transformation through the Simple Mapping step is known as the sub-transformation.

You can run the Simple Mapping step in multiple copies, clusters, in single threading mode, or in any other execution model.  You can also use this step in advanced data routing scenarios (filter rows and switch/case for example) or in partitioning or partitioning/clustering transformations.


Enter the following information in the transformation step fields.

Field Description
Step Name Specifies the unique name of the transformation on the canvas. A transformation can be placed on the canvas several times; however, it represents the same transformation. The Step Name is set to 'Simple Mapping (sub-transformation)' by default.

Specify your sub-transformation to execute by entering its path or clicking Browse.

If you select a transformation that has the same root path as the current transformation, the variable ${Internal.Entry.Current.Directory} will automatically be inserted in place of the common root path. For example, if the current transformation's path is /home/admin/transformation.ktr and you select a transformation in the folder /home/admin/path/sub.ktr than the path will automatically be converted 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. 

Transformations previously specified by reference are automatically converted to be specified by the transformation name within the Pentaho Repository.

Log Lines in Kettle

To differentiate log lines from a mapping, edit the file and set the KETTLE_LOG_MARK_MAPPINGS variable to Y.  

Set this variable to Y to precede log lines with the mapping step name and the mapping itself.


The Simple Mapping step features several tabs with fields for setting parameters and defining data flow. Each tab is described below. 

Parameters Tab

You can use the following fields in the Parameters tab to define or pass Kettle variables down to the mapping sub-transformation.

Option Description
Variable name Add a string you want to assign as a variable.
String value (can include variable expressions) Add the value you want to assign to this variable name. It is possible to include variable expressions in the string values for the variable names.
Inherit all variables from the parent transformation:

Select to make all the variables that are available in the parent transformation available in the sub-transformation, even if they are not explicitly specified in the Parameters tab. 

When this option is not checked, only those variables/values that are specified are passed down to the sub-transformation. 

Input Tab

The Input tab allows you to specify how fields from the incoming stream of the Simple mapping step are mapped to the fields of the Mapping Input specification in the sub-transformation.

Option Description
Fieldname from source step

Specify the name of a field in the incoming stream.

Fieldname to mapping input step Specify the name of the field as it will be known to the sub-transformation.
Mapping Use this button to open a field mapping dialog. This will conveniently list all the available fields in both the parent transformation and the sub-transformation, and allow you to create field to field mappings.
Update mapped fieldnames downstream Select this option to rename fields back to their original names when they reach the Mapping output step (fields get renamed before they are transferred to the mapping transformation). This will make your sub-transformations more transparent and reusable.

To add inputs into the table, perform the following steps:

  1. Click the Mapping button.
  2. Click a Source Field you want to map.
  3. Click a Target Field to associate with the Source Field.
  4. Click Add. If you need to edit or change the Source or Target fields, click Delete.
  5. Click Ok

Output Tab

The Output tab allows you to specify how fields from the Mapping output specification in the sub-transformation are mapped to the fields of the stream going out of the Simple mapping step. 

Option Description
Fieldname from mapping step

Specify the name of the field as it is available in the Mapping output specification inside the sub-transformation.

Fieldname to target step Specify the field in output stream of the Simple mapping step to which the sub-transformation output is mapped.
Get Fields Use this button to populate the grid with all output fields from the sub-transformation.