> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bringits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Object Mapper

> Map and transform data structures

The Object Mapper command (Command Type: 1016) enables you to map and transform data structures between different formats. This command is essential for restructuring data, mapping fields, and transforming data for downstream processing.

## Overview

The Object Mapper command provides functionality for:

* Mapping fields between different data structures
* Transforming data formats
* Restructuring nested objects
* Combining data from multiple sources
* Creating new data structures from existing data

## Command Type

**Command Type ID:** 1016

## Parameters

| Parameter         | Type   | Description                                       | Required |
| ----------------- | ------ | ------------------------------------------------- | -------- |
| **input**         | string | Input data reference (e.g., `@{PREVIOUS_OUTPUT}`) | Yes      |
| **mapping**       | object | Field mapping configuration                       | Yes      |
| **outputKey**     | string | Key name for storing mapped result                | Yes      |
| **defaultValues** | object | Default values for missing fields                 | No       |

## Mapping Configuration

The mapping object defines how input fields map to output fields:

### Basic Mapping

```json theme={null}
{
  "mapping": {
    "outputField": "$.inputField",
    "nestedField": "$.parent.child"
  }
}
```

### Array Mapping

```json theme={null}
{
  "mapping": {
    "items": "$.data.items[*]",
    "count": "$.data.items.length"
  }
}
```

## Usage Examples

### Basic Field Mapping

```json theme={null}
{
  "command": "object-mapper",
  "params": {
    "input": "@{PREVIOUS_OUTPUT}",
    "mapping": {
      "id": "$.data.id",
      "name": "$.data.name",
      "status": "$.data.status"
    },
    "outputKey": "mapped_data"
  }
}
```

### Nested Structure Mapping

```json theme={null}
{
  "command": "object-mapper",
  "params": {
    "input": "@{PREVIOUS_OUTPUT}",
    "mapping": {
      "event": {
        "id": "$.event.id",
        "title": "$.event.title",
        "date": "$.event.date"
      },
      "metadata": {
        "source": "$.metadata.source",
        "timestamp": "$.metadata.timestamp"
      }
    },
    "outputKey": "transformed_data"
  }
}
```

### Array Transformation

```json theme={null}
{
  "command": "object-mapper",
  "params": {
    "input": "@{PREVIOUS_OUTPUT}",
    "mapping": {
      "items": "$.data.items[*]",
      "total": "$.data.total",
      "page": "$.data.page"
    },
    "outputKey": "paginated_data"
  }
}
```

### Mapping with Default Values

```json theme={null}
{
  "command": "object-mapper",
  "params": {
    "input": "@{PREVIOUS_OUTPUT}",
    "mapping": {
      "id": "$.data.id",
      "name": "$.data.name",
      "status": "$.data.status"
    },
    "defaultValues": {
      "status": "unknown",
      "priority": "normal"
    },
    "outputKey": "mapped_data"
  }
}
```

## Variable Support

The Object Mapper command supports variable interpolation in:

* **Input**: Use `@{VARIABLE}` to reference previous command output
* **Mapping Paths**: Use JSONPath expressions in mapping configuration

### Common Variable Patterns

* **Previous Output**: `@{PREVIOUS_OUTPUT}` - Output from previous command
* **Extracted Data**: Reference data from Json Path command
* **Step Output**: `@{STEP_OUTPUT}` - Output from previous step

## Output Structure

The Object Mapper command creates a new data structure based on the mapping configuration:

### Output Format

```json theme={null}
{
  "mapped_data": {
    "id": "123",
    "name": "Example",
    "status": "active"
  }
}
```

### Using Mapped Data

Mapped data can be used by subsequent commands:

```json theme={null}
{
  "command": "sink",
  "params": {
    "exchange": "events",
    "routingKey": "data",
    "data": "@{PREVIOUS_OUTPUT}.mapped_data"
  }
}
```

## Best Practices

* **Use Descriptive Output Keys**: Use clear, descriptive key names for mapped data
* **Handle Missing Fields**: Use default values for optional fields
* **Test Mappings**: Test mapping configurations with sample data
* **Document Mappings**: Document complex mapping logic for maintainability
* **Validate Output**: Verify mapped data structure matches expectations

## Common Use Cases

* **Data Transformation**: Transform data structures for downstream processing
* **Field Mapping**: Map fields between different formats
* **Data Restructuring**: Restructure nested objects
* **API Response Transformation**: Transform API responses to internal format
* **Data Normalization**: Normalize data from different sources

## Related Commands

* [Json Path](/stream/commands/parse/json-path) - Extract data before mapping
* [JSON Parse](/stream/commands/parse/json-parse) - Parse JSON before mapping
* [Sink Commands](/stream/commands/sink) - Send mapped data to destinations

## Troubleshooting

### Mapping Errors

If mapping fails:

* Verify input data structure matches mapping paths
* Check JSONPath expressions are correct
* Ensure output key is unique

### Missing Fields

If mapped data has missing fields:

* Use default values for optional fields
* Verify input data contains expected fields
* Check mapping paths are correct