Request Mapper

Basic Request Mapper
Join our community

Overview

The "Request Mapper" node is designed to transform and map input data items by editing their fields according to user-defined rules. It supports two modes of operation: manual field-by-field mapping or bulk editing from a JSON object. This node is useful when you need to reshape, filter, or selectively include/exclude fields in your data before passing it on to subsequent nodes in an n8n workflow.

Common scenarios include:

  • Manually assigning or modifying specific fields in each item.
  • Applying a JSON-based transformation to update multiple fields at once.
  • Filtering output fields to include only those relevant for the next step.
  • Excluding certain fields from the output to reduce payload size or remove sensitive information.

Practical example:

  • You receive webhook data with many fields but only want to keep and rename a few key fields for further processing.
  • You have a JSON template describing how to update fields in incoming data items and want to apply it uniformly.

Properties

Name Meaning
Mode Choose between "Manual Mapping" (edit item fields one by one) or "From JSON" (edit item fields from a JSON object).
Keys to Assign When in Manual Mapping mode, specify individual field assignments to apply to each item.
Include in Output Controls which fields from the input are included in the output. Options:
- All Input Fields: include all original fields plus any changes.
- No Input Fields: include only the newly assigned/modified fields.
- Selected Input Fields: include original fields listed in "Fields to Include".
- All Input Fields Except: include all original fields except those listed in "Fields to Exclude".
Fields to Include Comma-separated list of input field names to include in the output when "Selected Input Fields" option is chosen.
Fields to Exclude Comma-separated list of input field names to exclude from the output when "All Input Fields Except" option is chosen.

Output

The node outputs an array of items where each item’s json property contains the transformed data fields after applying the mapping rules. The structure of each output item reflects the selected inclusion/exclusion settings and the applied field modifications.

If binary data were handled (not indicated here), it would be passed through or modified accordingly, but this node focuses on JSON data transformations.

Dependencies

  • No external services or API keys are required.
  • The node relies on internal helper modules for execution logic.
  • No special environment variables or credentials are needed.

Troubleshooting

  • Issue: Output does not contain expected fields.
    Cause: Incorrect "Include in Output" setting or missing field names in "Fields to Include"/"Fields to Exclude".
    Solution: Verify the inclusion/exclusion settings and ensure field names are correctly specified and match input data.

  • Issue: Manual assignments not applied as expected.
    Cause: Assignments may be misconfigured or empty.
    Solution: Double-check the "Keys to Assign" configuration in Manual mode.

  • Issue: JSON mode fails or produces errors.
    Cause: Invalid JSON syntax or incorrect expression format.
    Solution: Ensure the JSON object used for mapping is valid and properly formatted.

  • Error Messages: The node might throw errors related to invalid parameters or missing input data. These can usually be resolved by reviewing the node configuration and ensuring input data is present.

Links and References

Discussion