Value Translations
Source and target systems rarely use the same list of values. A Cherwell incident may close with Solved, while the target system only accepts Resolved. Value translations map those lists onto each other.
Translations belong to a single field mapping: open the Field mappings section of the Migrate Data screen and click the translate button beside the transformation you want to translate. If the mapping needs a default value before it can translate, the button shows a warning icon instead.
Translation rows
Each row is one source value and the destination value it becomes:
| Field | Meaning |
|---|---|
| Source value | The value as it appears on the source record. Matching is case-insensitive. |
| Destination value | What is written to the target instead. When the target field has a defined list of values, this becomes a dropdown of those values. |
| When… | An optional condition for the row - see below. |
Use Add translation row to add rows, the delete button on a row to remove it, Import CSV… to load a list of pairs, and Clear all to start again. Adding and removing rows is available whether or not Cortex resolved a list of source values, and rows you add by hand are kept when the dialog is reopened.
A row matches when its source value equals the record's value. The first matching row wins.
Checking the ids that will be exported
The lookup dropdowns on a translation row show a value's display text, which is not always what gets written. Tick Show IDs at the top of the Translations section to reveal the underlying id under each row's Source value and Destination value, and under the default value as well.
This is a reading aid only - it is never saved with the mapping - and it is worth using before a large run, because two values can carry the same display name while being different ids.
The id is shown quoted and reproduced exactly as it will be saved and exported, with nothing trimmed, so a stray leading or trailing space is visible instead of being hidden. A value that is empty reads as (none).
Entering source values manually
When the source field has a lookup list, Cortex lists every one of its values for you and shows each row's source value as a fixed name. If the values it resolved are wrong or incomplete, tick Enter source values manually (ignore the lookup list).
The source values then become editable text boxes, so you can type each value yourself and add or remove rows freely. This is the escape hatch for a lookup whose values Cortex cannot list properly - you decide what is written rather than accepting the resolved list.
Turn the option off and Cortex rebuilds the rows from the lookup list again, keeping the destination values you set and the extra rows you added by hand.
Conditions: "When…"
The When… button on a row opens a condition editor with the same comparison options used when building a search - field, operator, and a value control that changes with the operator (equals, not equals, contains, starts with, like, greater than, between, is empty, and so on).
A row with a condition applies when that condition matches the source record, and its Source value is ignored for that row. This lets one target field be filled from several different conditions rather than from one exact value. Evaluation continues down the rows in order, and the first matching row wins. If no row matches, the default value is used.
Saved conditions are edited on a copy, so cancelling the dialog leaves the existing row untouched.
Importing translations from CSV
Import CSV… reads translation rows from a comma-separated file. A Pick CSV columns dialog then asks which column holds the source values, which holds the destination values, and - optionally - which holds a When condition.
- Values are matched against the relevant lookup list by its displayed text or by the value id, case-insensitively, so a CSV can contain either form.
- A row whose source value is already listed updates that row; every other row is added. Values outside the lookup list are added as extra rows rather than dropped.
- While Enter source values manually (ignore the lookup list) is ticked, imported source values are used exactly as written.
Conditions in a CSV column
If you nominate a When condition column, each row's value is a written-out condition:
| Example value | Meaning |
|---|---|
(Status) equal (New) | Status is New. |
(Priority) is not empty | Priority has any value at all. |
(Created) between (2026-01-01) and (2026-12-31) | Created falls inside the range. |
(Status) in list (New, Open, Pending) | Status is one of the listed values. |
The name in the first parentheses is matched against the source table's fields by field id, internal name or display name. Operators may be written as words or symbols: equal, not equal, contains, starts with, like, not like, greater than, less than (each also available as or equal to), between, in list, is empty and is not empty.
A condition read this way behaves exactly like one set with the When… button above, and is honoured when the export runs.
The column is optional, and a row whose condition cannot be recognised is still imported - without a condition. Afterwards a CSV import: unrecognised When conditions list names every value that could not be read, with its row number and the reason, so those rows can be set by hand.
Default value
The Default value is written when a source value matches no row - blank values and unexpected values included. Cortex warns when it is missing ("A default value is required for blank or unexpected source values during export"), because a required target field populated from an unmapped value would otherwise be rejected by the target system.
Ignoring unexpected values
Tick Ignore any other values not specified here when only the listed values should ever be written. Any other value - including one that matched a row whose destination is blank - is written as blank instead of falling through to the default value. The default value input is disabled while the option is on.
This is what you want when one source field is splintered across several target fields: each target field receives only its own subset of the source values, and everything else is deliberately left empty.
What "blank" means depends on the target. For API targets that omit empty fields, the field is not sent at all; for database targets it is written as an empty value.
What translations do not apply to
The Lookup User Via Email Address and Lookup Requester Via Email Address transformations resolve the final user ID on the target, including their own default fallback, so value translations are not applied on top of them.
See also
- Field Mappings - choosing a transformation
- Running and Monitoring a Migration - what happens when a value is rejected by the target