Simple Mapping

(warning) PLEASE NOTE: This documentation applies to an earlier version. For the most recent documentation, visit the Pentaho Enterprise Edition documentation site.


Just like in a regular Mapping step, you can turn the repetitive, re-usable part of a transformation (a sequence of steps) into a mapping.  Compared to the Mapping step, the "Simple Mapping" step only 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.

Because it behaves perfectly to the contract of any other step, it is possible and easy to run this step in multiple copies, cluster, use in single threading mode or in any other execution model.  You can as such also use this in advanced data routing scenarios (Filter rows, switch/case, ...) or in partitioning or partitioning/clustering transformations.

A "mapping" is a regular transformation with the exception that it is possible to define mapping input and output steps as placeholders.

  • Mapping input: the placeholder where the mapping expects input from the parent transformation
  • Mapping output: the placeholder where the parent transformation is reading data from.

Note: To differentiate log lines from a mapping, you can 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 (available since PDI 5.1).




Step name

Name of the step. Note: This name has to be unique in a single transformation.

Mapping transformation

Use this section to specify the sub-transformation to execute.  You have the following options to specify the sub-transformation:

  • Use a file for the mapping transformation: when this option is enabled, you can enter the the .ktr file that is to be used as sub-transformation. The filename may contain variables (for example, you can use the built-in Internal.Transformation.Filename.Directory variable to construct a filename relative to the current transformation), or you can use the "Browse" button to select a file using a file browser.
  • Use a mapping transformation from the repository: This option is available when connected to a repository. When enabled, you can enter the name and the repository path in the two fields corresponding to this option. Alternatively you can use the "Select" button to browse the repository and point to the transformation stored in the repository.
  • Specify by reference: 
    The following two buttons in this section makes it easier to work with the mapped transformation:
  • New transformation: create a new transformation to be used as mapping. The new transformation will be opened in a new tab. The new transformation already has a Mapping Input step connected to a Mapping Output step - you will have to edit it and add any steps inbetween to create a functional sub-transformation.
  • Edit transformation: open the currently selected transformation in a new tab so you can edit it.


The grid in 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:

  • Fieldname from source step: name of a field in the incoming stream
  • Fieldname to mapping input step: name of the field as it will be known to the subtransformation
  • Mapping: use this button to open a field mapping dialog. This will conveniently list all the avaible fields in both the parent transformation and the sub-transformation, and allows you to create field to field mappings.
  • Ask these values to be renamed back on output?:  Fields get renamed before they are transferred to the mapping transformation. Enabling this options will rename them back when they reach the Mapping output step. This will make your sub-transformations more transparent and reusable.


The grid in 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.

  • Fieldname from mapping step: the name of the field as it is available in the Mapping output specification inside the sub-transformation
  • Fieldname to target step: 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.


The Parameters tab allows you to define or pass Kettle variables down to the mapping.
This will allow you to reach a high degree of customization.
Note: it is possible to include variable expressions in the string values for the variable names.

  • Inherit all variables from the parent transformation: If this option is checked, all variables available in the parent transformation will be available in the sub-transformation, even if they are not explicitly specified in the Parameters tab.
    IMPORTANT!! : Only those variables/values that are specified are passed down to the sub-transformation.