Added by Matt Casters, last edited by Jens Bleuel on Mar 21, 2012  (view change)

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

Description

When you want to re-use a certain sequence of steps, you can turn the repetitive part into a mapping. 
A "mapping" as such 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.

Options

Option Description
Step name Name of the step. Note: This name has to be unique in a single transformation.
Mapping transformation
Specify the name of the mapping transformation file to execute at runtime. 
You can specify either a filename (XML/.ktr) or a transformation from the repository.

There is an "Edit" button that will open the specified transformation in a separate tab in Spoon.
Parameters
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.

IMPORTANT!! : Only those variables/values that are specified are passed down to the sub-transformation.
Input tabs
Each of the input tabs (can be absent as well) correspond to one "Mapping Input" step in the mapping- or sub-transformation.
That means you can have a number of these tabs in a single Mapping step.  Adding one is possible with the "Add Input" button.
  • Input source step name : the name of the step in the parent transformation (not the mapping) to read from
  • Mapping target step name : the name of the step in the mapping (sub-transformation) to send the rows of data from the input source step to.
  • Is this the main data path? : check this if you only have one input mapping and you can leave the 2 fields above empty.
  • 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.
  • Step mapping description : you can add a description to this input step mapping here
  • Source - mapping transformation mapping : you can enter the required field name changes here.
Output tabs
Each of the output tabs (can be absent as well) correspond to one "Mapping Output" step in the mapping- or sub-transformation.
That means you can have a number of these tabs in a single Mapping step.  Adding one is possible with the "Add Output" button.

  • Mapping source step : the name of the step in the mapping transformation (sub-transformation) where we will read from
  • Output target step name : the name of the step in the current transformation (parent) to send the data from the mapping transformation step to.
  • Is this the main data path? : check this if you only have one output mapping and you can leave the 2 fields above empty.
  • Step mapping description : you can add a description to this input step mapping here
  • Mapping transformation - target step field mapping : you can enter the required field name changes here.

    Note: The 'Mapping' button is only enabled in the Output Mapping fields tab when multiple Output paths are available and the 'Is this the main data path?" option is disabled so that both steps (Mapping source step and Output target step) are given for the mapping.
Add input / Add output
Add an input or output mapping for the specified sub-transformation

Example

You can find the sample described below in your distribution over here: 

samples/mapping/Mapping - simple mapping.ktr
samples/mapping/Mapping - use simple mapping.ktr

Suppose we have a JavaScript step that we want to re-use over and over in several transformations (a simple concatenation to demonstrate the point) :

As you can see, the input fields that the script needs are: leftValue and rightValue, 2 Strings.
What we can then do is define those in a "Mapping Input" step:


The calculated value "res" is a field we want to pass to the parent transformations, so we add a "Mapping Output" step as well.
Remember, Mapping Input and Output are placeholders, there is no actual logic in them.  
The resulting mapping looks like this:

Now that our mapping is done, let's try to use it...

In this example, there are 2 fields coming into the Mapping step "X=A+B": A and B.
That means that there is somehow a "mapping" to be made between

  • "A" and "leftValue"
  • "B" and "rightValue"
  • "res" and "X" the result field

This can be achieved in the "Input" and "Output" tabs of the Mapping dialog.  Here is a screen shot of the Input tab:
*NOTE:* In our sample, we only use one input and output mapping.  It is possible however to use 0, 1 or more of either input or output mappings in a mapping transformation.
That means that we need to be able to specify which input or output we're addressing in the various tabs.  That is where the various step name choices come from in the screenshot.
In our simple case, we simply checked the "Is this the main data path" option.
 Here is a screen shot for the output tab: