Chapter 5
5. Field mappings
Open Settings, then Field Mappings. Each source column belongs to one of three columns on the page.
| Column | Purpose |
|---|---|
| Unmapped | Ignore this source column during processing |
| Search By | Use its value to find existing assets |
| Write To | Write its value to matched or created assets |
5.1 Import source headers
Open Import headers. Select Choose a file to import, or paste comma-separated column names and select Import pasted names.
Imported columns start in Unmapped with no CatDV field selected. Importing headers does not stage the file for a run.
Use file import when a header contains commas or quoted text. The file reader handles the header row as a table.
5.2 Choose the CatDV target
Select Edit on a source card. Use the CatDV field picker to search by name or identifier.
| Category | Meaning | Example |
|---|---|---|
| User | Custom metadata | An administrator-defined field identifier |
| Media | Values on the media object | media.filePath |
| Native | Built-in asset metadata | name, notes, tape |
The picker starts with User. Change Field type to find a media or native field. Refresh the CatDV field list if the server's fields changed. Loading the list signs out after reading it.
Choose a target before moving a card into Search By or Write To. Completed edits save automatically after a short pause. Wait for All changes saved and check for any error before continuing.
Drag the card handle to change its column or order. For keyboard placement, focus the handle and use the arrow keys.
5.3 Search rules
At least one source column must be in Search By. Every configured search column needs a nonblank value in each row.
| Match rule | Meaning |
|---|---|
| Is exactly | Match the complete value |
| Starts with | Match values with this prefix |
| Contains | Match values containing this text |
Use Is exactly with a unique identifier when possible. Prefix and contains searches can return several assets.
For several search cards, set the same Combine rule on every card. AND requires every condition. OR allows any condition and can find more assets. Test with a small known file.
In version 0.5.1, the AND or OR label between search cards can show the wrong rule. Check Combine rule inside each card.
Search values identify assets. They are not written back as source metadata. Select Apply path rules only when that source value needs rewriting before the search.
5.4 Write fields
Place source metadata in Write To. Nonblank values replace the mapped CatDV field value. Blank source values are omitted; they do not clear existing metadata.
Source column matching ignores case. Active mapped columns must exist in the file. Leave columns in Unmapped when the file does not need them.
Select Apply path rules on a write card to rewrite its value before writing. Chapter 6 explains the rule order.
5.5 Special fields
Select Add special field in Write To to write a value that does not come from a source column.
- Choose its Field identifier.
- Select Current date and time, Current date, or Static text as the Value source.
- Enter the fixed text when using Static text.
- Select Save, or Cancel to discard the new field.
Special fields apply to updates and creates. Dates use YYYY-MM-DD; date and time values include a timezone offset.
Select Delete on a special field and confirm to remove it. Data Wrangler also writes data.wrangler.last.touch automatically on every update and create.
5.6 Target conflicts and reset
A CatDV target can have one active instruction across search, write, and enabled special fields. Equivalent media identifiers count as the same target. Case and surrounding spaces do not distinguish targets.
A conflicting edit is rejected and names the target's current owner. Move one source card to Unmapped, choose another target, or delete the special field.
Reset field mappings permanently deletes all imported headers, source mappings, and special fields after confirmation. It cannot be undone. Import headers again to rebuild the configuration.