Title: Data Mapper Action Block

Description: Transform input data by mapping values from source paths to target paths

Tags: actions, blocks, data-mapper, transformation

---

Data Mapper Action Block

The Data Mapper action block enables transformation of input data by mapping values from source paths to target paths using configurable mapping rules.

Overview

The Data Mapper block is particularly useful for:
Microsoft Graph webhook data transformation
API response restructuring
Data format standardization
Complex object mapping scenarios

Configuration

Mapping Rules

The block accepts an array of mapping rules, each containing:

interface DataMappingRule {
  fromPath: string;  // Source path in dot notation (e.g., 'data.mail.to')
  toPath: string;    // Target path in dot notation (e.g., 'recipient.email')
}

Configuration Schema

{
  mapping: DataMappingRule[];  // Array of mapping rules
}

Usage Examples

Microsoft Graph Email Webhook

Transform a Microsoft Graph email webhook into a simplified format:

// Input data from Microsoft Graph webhook
const webhookData = {
  data: {
    mail: {
      to: "recipient@example.com",
      from: "sender@example.com", 
      subject: "Important Update"
    }
  }
};

// Mapping configuration
const config = {
  mapping: [
    { fromPath: "data.mail.to", toPath: "to" },
    { fromPath: "data.mail.from", toPath: "from" },
    { fromPath: "data.mail.subject", toPath: "subject" }
  ]
};

// Output result
{
  to: "recipient@example.com",
  from: "sender@example.com", 
  subject: "Important Update"
}

Complex Object Restructuring

Transform nested API responses into flattened structures:

// Input: Complex customer data
const customerData = {
  customer: {
    personalInfo: {
      firstName: "John",
      lastName: "Doe",
      email: "john@example.com"
    },
    address: {
      street: "123 Main St",
      city: "Anytown"
    }
  }
};

// Mapping configuration
const config = {
  mapping: [
    { fromPath: "customer.personalInfo.firstName", toPath: "profile.name.first" },
    { fromPath: "customer.personalInfo.lastName", toPath: "profile.name.last" },
    { fromPath: "customer.personalInfo.email", toPath: "contact.email" },
    { fromPath: "customer.address", toPath: "contact.address" }
  ]
};

// Output: Restructured data
{
  profile: {
    name: {
      first: "John",
      last: "Doe"
    }
  },
  contact: {
    email: "john@example.com",
    address: {
      street: "123 Main St",
      city: "Anytown"
    }
  }
}

Features

Nested Path Support

The block supports complex nested paths using dot notation:
user.profile.settings.theme
response.data.items.0.name (array access)
metadata.timestamps.created

Error Handling
Missing paths: Logged as warnings, processing continues
Invalid configuration: Returns error socket with details
Null/undefined values: Skipped with warnings
Empty mappings: Processes successfully with empty output

Logging

The block provides detailed logging for all operations:
Successful mappings with source/target paths and values
Warnings for missing or invalid paths
Summary of processed vs skipped fields
Error details for configuration issues

Sockets

Input Sockets
input: Accepts any object data to be mapped

Output Sockets  
output: Mapped data according to configuration rules
error: Error information when mapping fails

Block Template

The block appears in the Actions editor with:
Label: "Data Mapper" (EN) / "Daten-Mapper" (DE)
Icon: 🔄
Description: Maps data using configurable mapping rules

Best Practices
Use descriptive paths: Clear source and target paths improve maintainability
Handle missing data: Expect some source paths may not exist
Test with real data: Validate mappings with actual webhook/API data
Monitor logs: Review execution logs for mapping issues
Start simple: Begin with basic mappings and add complexity gradually

Error Scenarios

Invalid Socket
// Wrong socket name will return error
socketName: "invalid" → Error: "Invalid socket: invalid. Expected 'input'."

Missing Configuration
// Missing or invalid mapping config
configuration: {} → Error: "Configuration mapping is required and must be an array"

Invalid Mapping Rules
// Empty paths are skipped with warnings
{ fromPath: "", toPath: "result" } → Warning: "Skipping invalid mapping rule"

Performance Considerations
The block processes mappings sequentially
Complex nested object creation is optimized
Large arrays are handled efficiently
Memory usage scales with output object size

Integration with Other Blocks

The Data Mapper block works well with:
HTTP Request blocks: Transform API responses
Email blocks: Prepare email data from webhooks  
Database blocks: Format data for storage
Conditional blocks: Route based on mapped data