Simple mapper icon

Simple mapper

Map input keys to specific values
Join our community

Overview

The "Simple mapper" node is designed to map input values from one key to another based on user-defined mappings. It allows you to transform or replace specific values in your data, either by using a simple list of key-value pairs or by providing advanced mappings in JSON format. This node is useful in scenarios where you need to standardize, translate, or reformat incoming data before passing it to subsequent nodes.

Practical examples:

  • Converting color names to their hex codes (e.g., "red" → "#ff0000").
  • Mapping status codes to human-readable statuses (e.g., "1" → "Active", "0" → "Inactive").
  • Replacing product SKUs with descriptive names.

Properties

Name Meaning
Key to Map The key in the input data whose value should be mapped. Supports dot notation for nested keys (e.g., user.status).
New Key or Replace Key if Empty If provided, the mapped value will be set under this new key; if left empty, the original key's value will be replaced.
Mappings A collection of key-value pairs specifying how input values should be mapped. Each "Map Item" has:
- Key: The value to match.
- Value: The value to map to.
Advanced Mappings (JSON) Allows you to specify mappings as a JSON object (e.g., {"red": "#ff0000", "mint": "#DDFFE7"}). If provided and valid, this overrides the standard "Mappings" property.

Output

  • The output is an array of items, each corresponding to an input item.
  • For each item:
    • If the value at "Key to Map" matches a key in the mapping, it is replaced with the mapped value.
    • If "New Key or Replace Key if Empty" is specified, the mapped value is set under that key; otherwise, the original key's value is replaced.
  • The structure of the output item remains the same as the input, except for the mapped/replaced value.

Example output:

[
  {
    "color": "#ff0000",
    "otherField": "value"
  }
]

or, if using a new key:

[
  {
    "originalColor": "red",
    "mappedColor": "#ff0000"
  }
]
  • Binary data is not handled by this node.

Dependencies

  • No external services or API keys are required.
  • No special n8n configurations or environment variables are needed.

Troubleshooting

  • Invalid JSON format for advanced mappings.
    If the "Advanced Mappings (JSON)" field contains invalid JSON, the node will throw an error:
    "Invalid JSON format for advanced mappings."
    Resolution: Ensure your JSON is properly formatted (e.g., use double quotes around keys and values).

  • No mapping applied.
    If the value at "Key to Map" does not match any key in the mapping, no change will occur for that item.

  • Empty or incorrect key paths.
    If "Key to Map" uses dot notation for nested fields, ensure the path exists in your input data.

Links and References

Discussion