node-red-contrib-field-mapper

This module provides a “mapper” node in Node-RED for mapping JSON data from one format (i.e. input) to another (i.e. output).

This node can be helpful in scenarios where JSON data transformation is required or while integrating two different third-party APIs.

Mapper uses JSON specification file to assign values of input fields to output fields. Input JSON field can be a simple field or an object. Input fields/objects can be mapped to expected output fields/objects.

During runtime the “mapper” node will assign input fields/objects values to corresponding output fields/objects. Transformed JSON document will contain both input and output fields/objects. Mapper node will NOT delete any fields after transforming input JSON into desired output JSON document. “Change” node may be used to delete obsolete fields after transformation, if needed.

To make it easier for a standard third party integration, a public mapper definition repository is available which allows developers to select the required mapping for a JSON transformation.

Mapper definitions can be managed both publicly and privately.

Public Mapper Definition

Public mapper definitions are standard peer-reviewed repository for community sharing and usage to help keep definitions up-to-date. Intended to be used and maintained by community.

Contributions are welcome! See the contribution guidelines.

link: Public mapper definition repository

Private Mapper Definition

If your enterprise has a specific object model that will be used in integrations and you would like to keep those definitions private then you can point to a JSON file hosted on your own web servers.

Pre-requisites

The Node-RED Mapper requires Node-RED to be installed.

Install

To install the stable version use the Menu - Manage palette option and search for node-red-contrib-field-mapper, or run the following command in your Node-RED user directory - typically ~/.node-red:

npm install node-red-contrib-field-mapper

Or else install the package directly from Manage Palette

Restart your Node-RED instance and you should have a “mapper” node available in the palette.

Get Started

After installing the mapper node, follow the below steps:

Usage

The mapper node can be utilized in any flow with input and output JSON data. Below is an example usage with an simple JSON inject node.

Example

{
  "name": "eugene",
  "age": 26,
  "info": {
    "street": "home-street"
  },
  "test": "mapper"
}

• Select Mapping dropdown to view saved custom mappers

• By default public sample.json file will be selected with sample mapper JSON object.

• You can click on Load button to load JSON to schema field and edit if required.

• Additionally you can also use private mapper definition by selecting private in dropdown and pasting the link of public S3 bucket/json file or available valid json definition.

Below is an example mapper JSON which takes sample user details as JSON input and converts it to new payload/data. We can also add new key-value pair which may or may not be present in input JSON.

{
  "input": {
    "userId": "1",
    "name": "",
    "age": "",
    "info": {
      "street": ""
    },
    "test": ""
  },
  "output": {
    "dynamic-value": "mapper-data",
    "userId": "",
    "name": "",
    "age": "",
    "address": {
      "street": ""
    }
  }
}

Once schema is set you can click on Add button available on top right side of the mapper properties panel to save custom mapper.

Example:

With Clean-Up:

{
  "address": {
    "street": "home-street"
  },
  "name": "eugene",
  "dynamic-value": {
    "street": "home-street"
  },
  "age": 26
}

Without Clean-Up

{
  "name": "eugene",
  "age": 26,
  "info": {
    "street": "home-street"
  },
  "test": "mapper",
  "address": {
    "street": "home-street"
  }
}

Doing this will create a new property address into the incoming object or input JSON object, Existing key-value pairs will not be removed unless Clean up is checked.

{
  "name": "eugene",
  "age": 26,
  "info": {
    "street": "home-street"
  },
  "test": "mapper",
  "address": {
    "street": "home-street"
  }
}

Example flow

[
  {
    "id": "7f1163f7515c5d6f",
    "type": "tab",
    "label": "Mapper Node",
    "disabled": false,
    "info": "This module provides a “mapper” node in Node-RED for mapping JSON data from one format (i.e. input) to another (i.e. output).\n\nThis node can be helpful in scenarios where JSON data transformation is required or while integrating two different third-party APIs.",
    "env": []
  },
  {
    "id": "e9e8f7b9511cdde5",
    "type": "inject",
    "z": "7f1163f7515c5d6f",
    "name": "Sample JSON",
    "props": [
      {
        "p": "payload"
      }
    ],
    "repeat": "",
    "crontab": "",
    "once": false,
    "onceDelay": 0.1,
    "topic": "",
    "payload": "{\"name\":\"eugene\",\"age\":26,\"info\":{\"street\":\"home-street\"},\"test\":\"mapper\"}",
    "payloadType": "json",
    "x": 300,
    "y": 180,
    "wires": [["68f1d823be6dcbe3", "1c5f199f9f0a6f88"]]
  },
  {
    "id": "68f1d823be6dcbe3",
    "type": "Mapper",
    "z": "7f1163f7515c5d6f",
    "name": "Mapper v1.0.23",
    "rules": [
      {
        "pi": "userId",
        "po": "dynamic-value"
      },
      {
        "pi": "userId",
        "po": "dynamic-value"
      }
    ],
    "cleanup": false,
    "mapping": "18aada988a899f9e",
    "x": 590,
    "y": 180,
    "wires": [["876649f1c4f4e161"]]
  },
  {
    "id": "876649f1c4f4e161",
    "type": "debug",
    "z": "7f1163f7515c5d6f",
    "name": "",
    "active": true,
    "tosidebar": true,
    "console": false,
    "tostatus": false,
    "complete": "false",
    "statusVal": "",
    "statusType": "auto",
    "x": 940,
    "y": 180,
    "wires": []
  },
  {
    "id": "1c5f199f9f0a6f88",
    "type": "Mapper",
    "z": "7f1163f7515c5d6f",
    "name": "Mapper with clean-up",
    "rules": [
      {
        "pi": "info.street",
        "po": "address.street"
      },
      {
        "pi": "name",
        "po": "name"
      },
      {
        "pi": "info",
        "po": "dynamic-value"
      },
      {
        "pi": "age",
        "po": "age"
      }
    ],
    "cleanup": true,
    "mapping": "18aada988a899f9e",
    "x": 600,
    "y": 260,
    "wires": [["0e32244a81ebb7ba"]]
  },
  {
    "id": "0e32244a81ebb7ba",
    "type": "debug",
    "z": "7f1163f7515c5d6f",
    "name": "",
    "active": true,
    "tosidebar": true,
    "console": false,
    "tostatus": false,
    "complete": "false",
    "statusVal": "",
    "statusType": "auto",
    "x": 950,
    "y": 260,
    "wires": []
  },
  {
    "id": "18aada988a899f9e",
    "type": "Mapping",
    "name": "User Address",
    "url-type": "public",
    "url-public": "mappings/sample.json",
    "url-private": "",
    "schema": "{\"input\":{\"userId\":\"1\",\"name\":\"\",\"age\":\"\",\"info\":{\"street\":\"\"},\"test\":\"\"},\"output\":{\"dynamic-value\":\"mapper-data\",\"userId\":\"\",\"name\":\"\",\"age\":\"\",\"address\":{\"street\":\"\"}}}"
  }
]

Demo

https://www.youtube.com/watch?v=U3YuTAf7YG4

Krysp Platform Features

Contributions

Development of Mapper Node happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving mapper node.

Contributing Guide

Read our contributing guide to learn about our development process, how to propose bugfixes and improvements.

Discussions and suggestions

Use the Krysp Forum: https://www.krysp.io/forum to ask questions or to discuss new features.