Working with the Mapping Editor

The Mapping Editor is the primary tool in Etlworks for aligning source fields with destination fields. Whether you’re building a simple 1:1 mapping or a complex nested transformation, the Mapping Editor makes it easy to visualize, edit, and manage the field-level mappings.

Opening the Mapping Editor

To open the Mapping Editor:

1. Navigate to a source-to-destination transformation inside a flow.

2. Click the Configure button

3. The Mapping Editor (part of the Flow Builder) will open in a full-screen.

Flat vs Nested view mode

At the top of the editor is a Flat / Nested view-mode toggle. The toggle controls how the mapping is interpreted and how the destination panel is rendered:

• Flat — for simple flat-to-flat mappings. Each row maps one source field to one destination field. Default mapping behavior applies for unmapped fields.
• Nested — for any transformation that involves hierarchical structure on either side. This is the unified mechanism for flat → nested, nested → flat, and nested → nested transforms. Nested mode automatically enforces the nested mapping engine and renders source and destination as expandable trees with indent/outdent controls.

Switching modes. Switching from Nested to Flat clears the current mapping (you are warned first). Switching from Flat to Nested keeps your existing rows and treats them as level 0.

For more on the nested engine, see Nested mapping.

Interface Overview

The Mapping Editor is a dual-panel layout:

Each row represents a mapping between a source field and a destination field.

You can also define:

• Calculated fields
• Nested mappings (for JSON/XML)
• Excluded fields
• New fields added to the destination

Key Columns and Controls

(left to right)

Binding modes

Each destination field has a binding that determines where its value comes from. The binding is shown as a pill on the destination row and can be edited in a modal.

A destination row without a binding (no Direct source, no Expression, no Constant) is unmapped and will be skipped on save.

Create Flat Mapping Automatically 

The Create Mapping button at the top of the editor opens a dialog where you choose how the initial mapping is generated. You can switch the editor between Flat and Nested views any time after.

Note: Creating a mapping replaces any existing mappings.

Flat

1:1 field mapping. Best when both sides are tabular or you want AI assistance.

Flat has two sub-modes selectable as Flat mapping mode inside the dialog:

Match destination fields

Matches source fields to existing destination fields. When the destination has fields that do not line up with the source by name, or when you supply an AI prompt, the built-in AI agent (Simba) is invoked to suggest mappings.

Without a prompt, Simba:

• Matches fields by name similarity and type.
• Applies common naming conventions (for example, first_name → fname, user_id → user).
• Marks any unmatched source fields as excluded.
• Marks any unmatched destination fields as added (does not exist in the source, exists in the destination).

With an optional prompt entered in the Optional prompt for AI box, Simba uses your instructions to refine the mapping. Common prompts:

• Exclude fields — for example, "Exclude audit columns".
• Add new fields — for example, "Add created_at and updated_at with nulls".
• Rename or normalize fields — for example, "Convert camelCase to snake_case".

Simba first builds a complete 1:1 mapping, then applies your prompt on top.

Recreate destination from source

Rebuilds the destination structure to mirror the source — a clean 1:1 copy with no name-matching against an existing destination. Useful when the destination is empty or you want to start fresh from the source schema. AI is not used in this mode and the Optional prompt for AI box is hidden.

Nested

For transformations where the source, the destination, or both are hierarchical (JSON, XML, etc.).

• Source and destination fields are populated as expandable trees mirroring the parsed structure of each side.
• Fields are not automatically mapped — you map them manually using the indent/outdent, add child / add sibling, and drag-to-reorder controls.
• The AI prompt is not used in this mode (the box shows the placeholder "AI prompt is Flat only").

When AI is disabled

If AI features are disabled for your user, tenant, or customer, the Optional prompt for AI box is unavailable and Match destination fields creates only the deterministic 1:1 portion of the mapping — no AI suggestions. Recreate destination from source and Nested work unchanged because neither uses AI.

Create Flat Mapping manually

If you prefer full control over the mapping process, you can build your field mappings manually using the Add field mapping button.

To do this:

1. Click the ➕ Add field mapping icon (next to the Create Mapping button).
2. A new empty row will appear in the mapping grid.
3. Manually enter or select a Source field (if it exists) and a Destination field.
   • If your source or destination is linked to a live Connection, dropdowns will auto-populate with available fields.
4. Optionally, set additional properties:
   • Mark as Add Field (for constants or new fields)
   • Set Exclude to skip this field
   • Apply a Field Function (for calculated fields)
   • Adjust Data Type, set as Nullable, or define nested structure

Repeat the process for each field you want to map. This approach is ideal when:

• You’re mapping only a few fields
• You want to include constants or calculated fields
• You need full precision over what gets mapped and how

Filtering and bulk actions

The Mapping Editor includes tools to quickly work with large mappings.

Filter fields

You can filter fields in both source and destination panes.

• Use the Search box under Source or Destination
• Results update as you type
• Only matching fields remain visible

This makes it easier to work with large datasets.

Select mapping pairs

You can select one or multiple mapping rows.

• Use the checkbox next to each row
• Use the header checkbox to select all visible rows

Selected rows can be modified together using bulk actions.

Delete selected mappings

To remove multiple mappings:

1. Select one or more rows
2. Click the Delete icon

All selected mappings will be removed at once.

Bulk rename mappings

You can rename multiple fields at the same time using patterns.

1. Select one or more mapping rows
2. Click Bulk rename
3. Configure options and click Apply

• Source regex rename – rename source fields
• Destination regex rename – rename destination fields
• Pattern – text or regex to match
• Replacement – new value
• Ignore case – optional

Notes

• Bulk rename uses pattern-based matching and supports regular expressions
• Changes are applied only to selected mappings

Bulk update field functions

You can apply or update field functions for multiple mappings at once.

1. Select one or more mapping rows
2. Click Bulk update field function
3. Enter or modify the function
4. Click Apply

This is useful when:

• Applying the same transformation logic to multiple fields
• Standardizing calculations across mappings

Bulk update data type

You can update data type overrides for multiple destination fields.

1. Select one or more mapping rows
2. Click Bulk update data type
3. Select data type and options
4. Click Apply

Options include:

• Data type
• Database-specific type
• Nullable behavior

What's Next?

Learn about Mapping Fields Between Source and Destination.

Use templates to define fields

Overview

When Etlworks connects to the data sources, it samples the data and automatically discovers the fields in the dataset. The fields can be used in a Mapping editor for per-field Mapping. It is, however, not always possible to connect to the data source during the design stage. 

Example

A good example of when connecting to the data source during the design stage is impossible is this — when the data source is a POST or PUT endpoint returning a response after updating the database. 

Also, the automatic sampling is not always 100% accurate as it drills down to only one record for each nested data set; thus, it can miss some of the elements which appear in some of the records.   

Important: Process

In such cases, when configuring the file Format which is going to be used for the source or the destination, use the Template field to specify columns and data types. 

For example:

{
  "HostName": "string",
  "DomainName": "string",
  "FullyQualifiedDomainName": "string",
  "Description": "string"
}  

Important: For the template, you must use the same file Format as in the designated file: JSON for JSON files, CSV for CSV files, etc. Etlworks is actually parsing the template using the parameters configured for that Format.