# 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:
* [Mapping Input Specification](/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping-input-specification.md)
* [Mapping Output Specification](/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping-output-specification.md)
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
| Field | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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.
| Option | Description |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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. |
{% hint style="info" %}
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.
{% endhint %}
#### 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](/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping-input-specification.md) step in the sub-transformation.
You can use any number of entry points, including no input entry point.
| Option | Description |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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](/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping-input-specification.md) 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](/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping-output-specification.md) 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**
1. Select **Mapping**.
2. Select a **Source Field**.
3. Select a **Target Field**.
4. Select **Add**.
5. To remove a mapping, select **Delete**.
6. 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](/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping-output-specification.md) step in the sub-transformation.
You can use any number of entries, including no output entry.
| Option | Description |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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](/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping-output-specification.md) 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](/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping-input-specification.md) step.
The calculated value `res` is a field you want to pass to the parent transformation, so add a [Mapping Output Specification](/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping-output-specification.md) step.
{% hint style="info" %}
Mapping input/output specification steps are placeholders. They do not include processing logic.
{% endhint %}
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:
* `A` and `leftValue`
* `B` and `rightValue`
* `res` and `X` (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
* [Simple Mapping (sub-transformation)](/pdia-data-integration/pdi-transformation-steps-reference-overview/simple-mapping-sub-transformation.md)
* [Mapping Input Specification](/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping-input-specification.md)
* [Mapping Output Specification](/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping-output-specification.md)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.pentaho.com/pdia-data-integration/pdi-transformation-steps-reference-overview/mapping.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.