Skip to content

Mapper Component Overview

Mapper Component

The <mapper-component> is a visual data transformation tool that allows users to map data from input sources to output structures using a node-based interface.

Registration

import { defineCustomElement } from 'vue';
import MapperCe from '@/mapper/view/Mapper.ce.vue';

customElements.define('mapper-component', defineCustomElement(MapperCe));

Features

Visual Mapping: Drag connections between input fields and output fields
Transformation Nodes: Built-in tools for data manipulation
Preview: Test mappings with sample data
VueFlow Based: Same visual paradigm as the flow editor

Props

Prop	Type	Default	Description
`withActions`	`boolean`	`false`	Show Save/Preview buttons in the toolbar

Available Node Types

Node Type	Purpose
`source`	Input data structure (InputTool)
`target`	Output data structure (OutputTool)
`collect_extractor`	Extract nested object fields (ObjectSourceTool)
`list_iterator`	Iterate over array items (ListIteratorTool)
`substring`	Extract substring from text (SubstringTool)
`get_by_index`	Get array item by index (GetByIndexTool)
`accumulator`	Collect multiple values (AccumulatorTool)

Basic Usage

Vue
HTML

<script setup lang="ts">
import { onMounted } from 'vue';

onMounted(() => {
  // Configure mapper via hooks if needed
  // The mapper has its own workspace store
});

function handleSave(mapperData: unknown) {
  console.log('Mapper saved:', mapperData);
  // POST to backend
}
</script>

<template>
  <mapper-component
    with-actions
    style="width: 100%; height: 600px;"
  />
</template>

<!DOCTYPE html>
<html>
<head>
  <script src="./dist/mapper.js"></script>
  <style>
    mapper-component {
      display: block;
      width: 100%;
      height: 100vh;
    }
  </style>
</head>
<body>
  <mapper-component with-actions></mapper-component>
</body>
</html>

When withActions is enabled, the toolbar shows:

Plus Button (+): Opens menu to add mapper tools
- Fix Input/Mapper: Auto-fix input/output structure
- Accumulator: Add accumulator node
Preview Button: Test the current mapping
Save Mapper Button: Save the mapping configuration

Mapper Data Structure

interface MapperConfig {
  nodes: Array<{
    id: string;
    type: 'source' | 'target' | 'collect_extractor' | 'list_iterator' | 'substring' | 'get_by_index' | 'accumulator';
    position: { x: number; y: number };
    data: Record<string, any>;
  }>;
  edges: Array<{
    id: string;
    source: string;
    target: string;
    sourceHandle?: string;
    targetHandle?: string;
  }>;
}

Integration with Flow Component

The Mapper is typically used within the Flow editor for configuring node data transformations:

// In Flow component, when a node has mapping needs
const { onMapperPreview, setMapperPreviewResult } = window.$useFlowCore;

// Register preview handler
onMapperPreview(async (flow, params) => {
  // Execute mapper transformation
  const result = await api.post('/mapper/preview', {
    mapper: flow,
    inputData: params,
  });

  // Show result in mapper
  setMapperPreviewResult(result);
});

Internal Architecture

src/mapper/
├── mapper.ts              # Custom element registration
├── components/
│   └── tools/
│       ├── InputTool.vue        # Source data node
│       ├── OutputTool.vue       # Target data node
│       ├── ObjectSourceTool.vue # Object extractor
│       ├── ListIteratorTool.vue # Array iterator
│       ├── SubstringTool.vue    # String manipulation
│       ├── GetByIndexTool.vue   # Array indexing
│       └── AccumulatorTool.vue  # Value collection
├── hooks/
│   └── useMapper.ts
├── store/
│   └── workspace.ts       # Mapper state management
├── types.d.ts
└── view/
    └── Mapper.ce.vue      # Main component

Example: Simple Field Mapping

A typical mapper setup connects source fields to target fields:

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Source    │      │  Transform  │      │   Target    │
│             │      │  (optional) │      │             │
│ • name      │─────►│             │─────►│ • fullName  │
│ • email     │─────────────────────────►│ • emailAddr │
│ • items[]   │─────►│ ListIterator│─────►│ • products  │
└─────────────┘      └─────────────┘      └─────────────┘

See Also