# 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:

```typescript
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

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

## Usage Examples

### Microsoft Graph Email Webhook

Transform a Microsoft Graph email webhook into a simplified format:

```typescript
// 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:

```typescript
// 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

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

## Error Scenarios

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

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

### Invalid Mapping Rules
```typescript
// 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