metabuilder/workflow/plugins/utility/transform

Transform Node Plugin

Transform data using template expressions and mappings.

Installation

npm install @metabuilder/workflow-plugin-transform

Usage

{
  "id": "transform-users",
  "type": "operation",
  "nodeType": "transform",
  "parameters": {
    "mapping": {
      "id": "{{ $json.user_id }}",
      "name": "{{ $json.first_name }} {{ $json.last_name }}",
      "email": "{{ $json.email_address }}",
      "status": "{{ $json.is_active ? 'active' : 'inactive' }}"
    },
    "flatten": false,
    "format": "json"
  }
}

Operations

Basic Mapping

Transform data by mapping input fields to output structure:

{
  "mapping": {
    "userId": "{{ $json.id }}",
    "userName": "{{ $json.name }}"
  }
}

Nested Mapping

Create nested output structures:

{
  "mapping": {
    "user": {
      "id": "{{ $json.id }}",
      "profile": {
        "name": "{{ $json.name }}",
        "email": "{{ $json.email }}"
      }
    }
  }
}

Array Mapping

Transform array of objects:

{
  "mapping": [
    {
      "id": "{{ $json.id }}",
      "name": "{{ $json.name }}"
    }
  ]
}

Flatten Nested Data

Convert nested objects to flat structure:

{
  "mapping": "{{ $json }}",
  "flatten": true
}

Group by Field

Group array items by a specific field:

{
  "mapping": "{{ $json }}",
  "groupBy": "status"
}

Format Output

Convert result to different formats:

{
  "mapping": "{{ $json }}",
  "format": "csv"
}

Parameters

• mapping (required): Field mappings with template expressions
  • Can be an object for field-by-field mapping
  • Can be an array for transforming arrays
  • Can be a string template for direct transformation
• flatten (optional): Flatten nested objects to dot notation (default: false)
• groupBy (optional): Group array items by field name
• format (optional): Output format - json, csv, xml, yaml (default: json)

Template Expressions

Mapping values support full template syntax:

• {{ $json.fieldName }} - Access input field
• {{ $json.field1 + $json.field2 }} - Math operations
• {{ $json.status === 'active' ? 'yes' : 'no' }} - Conditionals
• {{ $json.name.toUpperCase() }} - String methods
• {{ $utils.flatten($json) }} - Utility functions

Output Formats

JSON (default)

Returns structured JavaScript object/array

CSV

Converts array of objects to CSV format:

name,email,status
John Doe,john@example.com,active
Jane Smith,jane@example.com,inactive

XML

Converts to XML structure:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <user>
    <id>123</id>
    <name>John</name>
  </user>
</root>

YAML

Converts to YAML format:

- id: 123
  name: John
  email: john@example.com

Features

• Template expression interpolation in mappings
• Nested object transformation
• Array mapping and transformation
• Object flattening to dot notation
• Array grouping by field
• Multiple output formats (JSON, CSV, XML, YAML)
• Flexible mapping syntax (object, array, or template string)
• Type-safe transformation

Examples

Simple Field Mapping

{
  "id": "transform-rename",
  "nodeType": "transform",
  "parameters": {
    "mapping": {
      "firstName": "{{ $json.first_name }}",
      "lastName": "{{ $json.last_name }}",
      "emailAddress": "{{ $json.email }}"
    }
  }
}

Computed Fields

{
  "id": "transform-computed",
  "nodeType": "transform",
  "parameters": {
    "mapping": {
      "id": "{{ $json.id }}",
      "fullName": "{{ $json.firstName + ' ' + $json.lastName }}",
      "initials": "{{ $json.firstName.charAt(0) + $json.lastName.charAt(0) }}",
      "isActive": "{{ $json.status === 'active' }}"
    }
  }
}

Array to CSV

{
  "id": "transform-to-csv",
  "nodeType": "transform",
  "parameters": {
    "mapping": "{{ $json }}",
    "format": "csv"
  }
}

Flatten and Group

{
  "id": "transform-flatten-group",
  "nodeType": "transform",
  "parameters": {
    "mapping": "{{ $json }}",
    "flatten": true,
    "groupBy": "department"
  }
}

License

MIT