Skip to main content

Configuring Field Mappings

James Herring
Updated

Configuring Field Mappings

The Fields tab is where you define how data from the source table is transformed and written into the target table. Each field mapping specifies a target field and the rule for populating it — whether that is a direct copy from a source field, a constant value, a formula, a value translation, a lookup, or an ID correlation.

Accessing the Fields Tab

  1. Open a Migrate Records step
  2. Navigate to the Fields tab
  3. You will see a table listing all configured field mappings

Each row in the table represents one mapping, showing:

  • The target field that will be populated
  • The mapping type (Source Field, Constant, Formula, etc.)
  • A summary of the mapping configuration (e.g., which source field, what formula expression)

Adding a New Field Mapping

To add a new field mapping:

  1. Click the Add Mapping button above the mappings table
  2. Select the target field from the dropdown — this lists all fields on the target table
  3. Choose a mapping type from the type selector
  4. Configure the mapping based on the selected type (see Mapping Types below)
  5. Save the mapping

The new mapping appears in the table and will be applied to every record during execution.

Editing an Existing Mapping

To edit a mapping:

  1. Click on the mapping row in the table to select it
  2. The mapping editor panel opens, showing the current configuration
  3. Modify the mapping type, target field, or mapping-specific settings as needed
  4. Save your changes

Removing a Mapping

To remove a mapping you no longer need:

  1. Select the mapping row in the table
  2. Use the delete action (trash icon or context menu)
  3. Confirm the deletion

Removed mappings are no longer applied during execution. The target field will not be populated unless another mapping is configured for it.

Mapping Types

The mapping type determines how the target field's value is derived for each record. The available types are:

Type Description When to use
Source Field Copies a value directly from a source field Simple field-to-field migrations where names or structures differ
Constant Sets a fixed value for every record Default values, migration markers, static metadata
Procedure Variable Uses the current value of a procedure variable Values determined at the procedure level (e.g., batch ID, run date)
Mapping Variable Uses the value of an intermediate mapping variable Reusing a calculated value across multiple mappings
Formula Evaluates an expression using fields, variables, and functions Data type conversions, string manipulation, conditional logic, calculations
Match Translates values using a defined set of pairs Choice fields where source and target use different value sets (e.g., priority codes)
Lookup Retrieves a value from a related table using a lookup definition Fields that reference data not available on the source record (e.g., user email from sys_user)
ID Translates a record ID using a table correlation Reference fields where the target system uses different IDs than the source

For detailed information on each mapping type, see:

Auto-Generated Mappings vs Manual Mappings

If you used the Creation Wizard to create the step, the Fields tab will already contain auto-generated mappings. These are typically Source Field mappings created by matching source and target fields by name.

Auto-generated mappings are a starting point. You will usually need to:

  • Add mappings for target fields that the wizard did not match
  • Change mapping types from Source Field to Formula, Match, or Lookup where simple copying is insufficient
  • Remove incorrect mappings where the wizard matched fields by name but the fields are semantically different
  • Add Lookup and ID mappings that require manual configuration

If you did not use the wizard, the Fields tab starts empty and all mappings must be created manually.

Bulk Mapping Tools

The toolbar above the mappings table provides two shortcuts for creating many Source Field mappings at once, alongside the Add Mapping Variable and Clear actions.

Quick Map

Quick Map appears when the source and target tables share the same adaptor and table name — for example, a ServiceNow incident table on one instance migrating to a ServiceNow incident table on another. Because the field names line up exactly in that case, Quick Map creates a Source Field mapping for every target field that has a same-named source field, in a single click.

The button label shows how many fields it will map — for example Quick Map (12 of 40 fields) — where the first number is the count of unmapped target fields that have a matching source field and the second is the total number of target fields. Quick Map:

  • Maps only target fields whose name exactly matches a source field name.
  • Never overwrites an existing mapping. Fields you have already configured are left untouched, so it is safe to re-run after deleting or editing individual mappings.
  • Becomes disabled once every matching field is mapped (the count reaches 0).

When the source and target do not share an adaptor and table name, Quick Map is hidden; use Auto-Map or add mappings manually instead.

Auto-Map

Auto-Map is always available and opens a guided dialog that matches source and target fields by name similarity rather than exact name. Use it when field names differ between systems (for example, short_description against description). The dialog has three steps:

  1. Settings — choose whether to map all target fields or only the rows currently selected in the table, whether to overwrite existing mappings, the type-conversion strictness (exact, compatible, or any), and the match threshold (how similar two names must be to count as a match; default 80%).
  2. Review Matches — review the suggested matches, change any selections, and clear matches you do not want.
  3. Complete — the chosen mappings are applied to the table.

Auto-Map is the better choice when names do not align exactly, or when you want to review matches before they are applied. Quick Map is the faster choice when names are identical because the source and target are the same table type.

On narrow panes, the toolbar collapses responsively: Add Mapping Variable moves into a vertical ellipsis (⋮) menu first, then Auto-Map, with Quick Map kept visible longest.

Filtering to Unmapped Fields

Beside the Field Mappings title, a quiet (N fields unmapped) count shows how many target fields and mapping variables do not yet have a configured mapping. Click the count to filter the table to only those unmapped rows; the count turns into an active filter with an ✕ to clear it. This is useful for working through the fields that remain after running Quick Map or Auto-Map. A row counts as mapped once it has a mapping type assigned — an empty row opened by clicking does not count.

Mapping Variables

Mapping variables are special entries in the mappings table that represent intermediate calculated fields. They are processed during execution like regular mappings, but their values are not written to the target table.

Mapping variables are useful when:

  • You need to compute a value once and reuse it in multiple field mappings (avoiding duplicated formula logic)
  • A transformation requires multiple steps that are cleaner when broken into separate calculations
  • You want to inspect intermediate values during testing without affecting the target

To create a mapping variable:

  1. Click Add Mapping Variable in the toolbar above the mappings table (on narrow panes this action is in the vertical ellipsis menu)
  2. Give it a name and configure its mapping (typically a Formula)

Once created, mapping variables appear in the mappings table alongside regular field mappings and can be referenced by other mappings using the Mapping Variable mapping type.

Mapping Execution Order

Field mappings are evaluated in the order they appear in the table. This order matters when:

  • A mapping variable is referenced by a later mapping — the variable must be calculated first
  • A formula references the result of another formula via a mapping variable

You can reorder mappings by dragging rows in the table to ensure dependencies are resolved correctly.

Previewing a Mapping

The Eye icon next to each field mapping opens a per-field preview drawer. It runs the same 100-record dry-run as the step's Preview tab, but with one column per input to that mapping (source fields, procedure variables, mapping variables) alongside the computed target value. Use it to verify a formula or lookup mapping against real source data without leaving the Fields tab. See Previewing a Migration for full details.

Options per Mapping

Every mapping type has its own Options accordion (collapsed by default) inside the mapping editor. It houses settings that are less commonly changed but still per-mapping — for example, error-handling behaviour for Formula mappings, free-text toggles for Match mappings, and the Exclude from sampling switch that applies across all types. Open the accordion only when you need to change one of these settings; the primary inputs (target field, mapping type, source/formula/lookup) remain the focal point.

AI-Assisted Formula Generation

When an LLM provider is configured and validated in Preferences → LLM Provider, Formula mappings show an inline AI panel above the formula editor. It drafts a candidate expression from a natural-language description, validates it against the live engine, and surfaces sample results before you accept. Match, Lookup, ID, and custom-validation formulas expose the same affordance via a Generate button that opens the panel in a dialog. See Formula Mappings for the full workflow.

Tips

  • Start with the wizard to auto-generate simple mappings, then refine by adding formulas and advanced types.
  • Use Quick Map when migrating between the same table type on two instances; fall back to Auto-Map when source and target field names differ.
  • Filter to unmapped fields via the count beside the title to see what still needs a mapping after running Quick Map or Auto-Map.
  • Use mapping variables to avoid duplicating complex formula logic across multiple field mappings.
  • Check data types — if a source field is a string and the target expects an integer, use a Formula mapping to convert.
  • Preview a single mapping via the Eye icon to see how each input feeds the result, instead of running the whole step.
  • Test incrementally — add a few mappings, run the step with a small sample, verify the output, then add more.

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk