Field Mappings
Every column on the target table that should receive a value needs a mapping. The Field mappings section of the Migrate Data screen lists the target table's columns and lets you decide, for each one, what to write into it.
| Column | Meaning |
|---|---|
| Source field | The field on the source record the value comes from. It applies when the transformation is Source Field, Lookup User Via Email Address or Lookup Requester Via Email Address; otherwise the cell shows a placeholder describing the transformation instead. |
| Transformation | How the value is produced - see the table below. |
| Target field | The column on the target system being filled. |
Target fields are read from the target system, so the list always reflects that table's current columns. When a saved configuration is loaded, columns added to the target since it was saved appear with no mapping.
Transformations
| Transformation | What it writes |
|---|---|
| Source Field | The value of the chosen source field, copied as-is. |
| Value | A fixed value you type in. When the target column has a defined list of values, the cell becomes a dropdown of those values instead. |
| Expression | A value built with Cortex's expression editor - useful for combining fields or formatting text. An extra Default value when blank box provides a fallback when the expression produces nothing. |
| Lookup User Via Email Address | Resolves a user on the target system by email address, for agent/user fields. The chosen source field must contain the email address. |
| Lookup Requester Via Email Address | The same lookup for requester (end-user) fields. |
| Output All Field Values | Writes all of the source record's field values as one block of text, rather than a single field. |
| Summarize Related Items | Summarizes related items from a relationship you pick, for example several child rows condensed into one text field. |
| Don't Map | Leaves the target column untouched. |
The two email lookups are only offered on target fields that Cortex recognises as user fields.
When an email address does not match a user on the target, the lookup writes the mapping's Default value if one is set, and otherwise leaves the field blank.
Formatting date and time values
A source system and a target system rarely agree on how a date is written, and some targets reject anything that is not in their own shape. Cortex's expression editor - the Expression transformation here, and the same editor is used elsewhere in Cortex including Cortex Actions - includes three modifiers that reformat a date, a date/time or a time value as it is written out:
| Modifier | Output with no other settings |
|---|---|
| Format Date | 2026-01-23 |
| Format Date/Time | 2026-01-23T15:04:05Z |
| Format Time | 15:04:05 |
Each of the three keeps its own default, so they behave differently out of the box, while any of them can be pointed at any output format.
Output formats available on all three include ISO 8601 UTC (2026-01-23T15:04:05Z), ISO 8601 with a time zone offset (2026-01-23T15:04:05+00:00), ISO 8601 without one (2026-01-23T15:04:05), ISO 8601 date only (2026-01-23) and time only (15:04:05); US date (01/23/2026) and US date and time (01/23/2026 03:04:05 PM); European date (23/01/2026) and European date and time (23/01/2026 15:04:05); long date (January 23, 2026) and long date and time; compact (20260123150405); 24-hour (15:04:05) and 12-hour (03:04:05 PM) time; RFC 1123 (Fri, 23 Jan 2026 15:04:05 GMT); epoch seconds (1769174045) and epoch milliseconds (1769174045000); and a custom .NET format string.
How the incoming value is read is left on auto-detect by default, and can be pinned to month-first (US), day-first (European), ISO 8601, epoch seconds or milliseconds, or a custom .NET format string. A date copied out of a query that wraps values in single quotes is still read.
Also worth knowing:
- A value that cannot be read as a date is written unchanged, with a warning in the log, so one unexpected value does not break the rest of the mapping.
- A value carrying no time zone of its own is read as UTC. A value with its own offset converts to the matching UTC instant for ISO 8601 UTC output, while the date-only and time-only outputs use the value's own calendar date.
- Auto-detect only treats a run of 9 to 13 digits as an epoch, so an unrelated short number is not silently reinterpreted as a date. Selecting the epoch input handling explicitly lifts that guard. Ten digits or fewer are read as seconds, eleven or more as milliseconds.
- There is an optional target time zone, which converts the value before it is formatted - useful when the target's own date fields are expected in a particular zone. A time zone id that cannot be resolved logs a warning and formats without conversion.
- A custom format string that is not a valid date format leaves the value unchanged and logs a warning.
Value translations
The button beside the Transformation dropdown (the translate icon) opens the value translation editor for that mapping, where source values are translated into target values. A warning icon means that mapping needs a default value before it can translate. See Value Translations.
Blank results
- Any transformation that produces a blank value falls back to Default value when blank if you supplied one; a non-blank value is always used as-is.
- A target column that has no mapping, or whose mapping produced nothing, is simply not filled in - and if the target system requires that field, the record fails and is reported back to you (see Running and Monitoring a Migration).
Where mappings live
The grid on the Migrate Data screen maps the parent record. Mappings for related child rows are configured separately, on the relationship's own Field mappings… dialog - see Related Record Transfers. That dialog has the same options plus Parent Record Id, which writes the ID the target gave the new parent record.
Click Save once the mappings are right. Saved mappings reappear the next time you migrate that table, and can be managed from Utilities → Migration configurations.
The whole mapping set can also be exported to a file and imported back later, or on another Cortex instance - see Mapping Bundles.