Skip to main content

Pentaho+ documentation has moved!

The new product documentation portal is here. Check it out now at


Hitachi Vantara Lumada and Pentaho Documentation

Simple Mapping (sub-transformation)

Parent article

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

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

Compared to the Mapping step, the Simple Mapping (sub-transformation) 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:

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

You can run the Simple Mapping (sub-transformation) 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 NameSpecifies 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. The Step Name is set to Simple Mapping (sub-transformation) by default.

Specify your mapping sub-transformation to execute. Click Browse to navigate to your 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} 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 then 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 (sub-transformation) step features several tabs with fields for setting parameters and defining data flow. Each tab is described below.

Parameters tab

Parameters tab in Simple Mapping               (sub-transformation)

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

Variable nameAdd 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 (sub-transformation) step are mapped to the fields of the Mapping Input Specification in the sub-transformation.

Input tab in Simple Mapping        (sub-transformation)

Fieldname from source stepSpecify the name of a field in the incoming stream.
Fieldname to mapping input stepSpecify the name of the field as it will be known to the sub-transformation.
MappingUse this button to open a field mapping dialog box. 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 downstreamSelect 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 Field or Target Field, click Delete.

  5. Click Ok.

Output tab

Output tab in Simple Mapping               (sub-transformation)

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 (sub-transformation) step.

Fieldname from mapping stepSpecify the name of the field as it is available in the Mapping Output Specification inside the sub-transformation.
Fieldname to target stepSpecify the field in output stream of the Simple Mapping (sub-transformation) step to which the sub-transformation output is mapped.
Get FieldsUse this button to populate the grid with all output fields from the sub-transformation.