ApplyMap

ApplyMap

Overview

The ApplyMap node is designed to map and optionally rename fields in incoming data items based on a provided mapping table. It is particularly useful for transforming or standardizing values (such as codes, IDs, or categories) into more meaningful representations, or for adapting data structures between systems.

Common scenarios:

  • Converting gender codes (1, 2) to readable strings (Male, Female).
  • Mapping country codes to full country names.
  • Standardizing product categories or statuses across different data sources.
  • Renaming fields after mapping to match target system requirements.

Practical example:
Suppose you receive user data with a field user.genderId containing numeric codes, and you want to convert these to human-readable gender names using a mapping table, possibly renaming the field to user.gender.

Properties

Name Type Meaning
Mappings fixedCollection A list of field mappings to apply. Each mapping specifies which field to map, which mapping table to use, what default value to use if no match is found, and whether to rename the field.
Field to Map string The name of the field to map. Supports dot notation for nested fields (e.g., level1.level2.genderId).
Mapping string The name of the mapping to apply. This must correspond to a mapping table provided on the second input.
Default Value string The value to set if the original value cannot be found in the mapping table (e.g., "unknown Gender").
Rename Field boolean Whether to rename the field after mapping.
Rename Field To string The new name for the field if renaming is enabled. Only used when "Rename Field" is true.

Output

Each output item contains:

  • json: The transformed data object, with mapped (and possibly renamed) fields according to the specified mappings.
  • pairedItem: An object indicating the index of the original item that this output corresponds to.
  • binary (optional): If the input item contained binary data, it is preserved and passed through unchanged.

Example output structure:

{
  "json": {
    "user": {
      "gender": "Male"
    }
  },
  "pairedItem": {
    "item": 0
  },
  "binary": { /* ... */ }
}

Dependencies

  • Lodash: Used internally for object manipulation.
  • Input requirements:
    • Input 0: Data items to be mapped.
    • Input 1: Mapping table(s), where each entry should have at least mapName, input, and output fields.

No external API keys or n8n environment variables are required.

Troubleshooting

Common issues:

  • Mapping not applied:

    • Ensure the mapping table (input 1) contains entries with the correct mapName matching the one specified in your mapping property.
    • Check that the field path in "Field to Map" matches the actual structure of your input data (dot notation supported).

  • Default value used unexpectedly:

    • This happens if the value in the source field does not exist in the mapping table. Double-check your mapping table contents and the input data.

  • Field not renamed:

    • Make sure "Rename Field" is enabled and "Rename Field To" is filled in.

Error messages:

  • The node may throw errors if required properties are missing or if the mapping table is not structured correctly. Review your node configuration and ensure all necessary fields are present.

Links and References

Discussion