Mapping Columns to Attributes

Step 4 of the import wizard is where you decide how each spreadsheet column is handled. Get the mapping right and the rest of the import is mechanical; get it wrong and you'll see it in the dry run before anything is written, so don't be afraid to experiment.

The Five Column Roles

For every header in your source file, pick one of:

The mapping panel uses colour to make the picture obvious:

• Green — Match key
• Purple — Built-in (display name)
• Blue — Existing custom attribute
• Amber — New custom attribute (will be created)
• Grey — Ignored

A sample value from the first row of your sheet is shown under each header to help you pick.

Picking the Match Key

The match key is how each spreadsheet row finds its file in Forma. Without one set, every row is orphaned and the wizard blocks Next at Step 4.

The match key must be a column whose values are file names — typically the column literally called File name, Drawing number, or Document reference in your MIDP. Foreman compares each value to:

1. the file name with extension (exact match), then
2. the file name without extension if no exact hit (stripped match).

Both comparisons are case-insensitive.

If a row's value matches more than one file in the destination folder (e.g. you have two files called Plan.pdf in different sub-folders), the row is classified ambiguous, and the dry-run shows both candidate paths so you can disambiguate the source data.

Built-In: Display Name

Built-in: Display name writes to the file's display name in Forma — equivalent to renaming. Use this when your MIDP stores a "human-readable" title separate from the cryptic file name (e.g. file named BLDG-A-2-FP-001.pdf, MIDP shows Building A Level 2 Floor Plan).

Display-name writes go through ACC's version-rename API, not the custom-attribute API. The conflict policy still applies — Fill blanks only won't rename a file whose current display name is already non-empty.

Custom Attribute (Existing)

When you pick Custom attribute (existing), Foreman shows a dropdown of every custom attribute that already exists on the destination folder. Pick the one this column writes to.

For most attribute types (text, numeric, boolean, date), nothing else is needed — Foreman coerces each cell to the attribute's type at import time:

• Text / paragraph — value is trimmed and written as-is.
• Numeric — parsed as a double with invariant culture.
• Boolean — true / yes / y / 1 → true; false / no / n / 0 → false. Anything else errors.
• Date — accepts yyyy-MM-dd, yyyy/MM/dd, Excel serial numbers, or any culture-invariant date that .NET's DateTime.TryParse can handle.

Cells that fail coercion are reported as errors in the dry-run with the offending value and the reason — they don't block the wizard, but the cell will be skipped at run time.

List and Dropdown Attributes

When the picked attribute is select (single value), dropdown, multi_select, or array, Foreman reads every distinct value in the source column and shows it under the attribute's allowed list:

• Locked pills (grey) — values that already exist in the attribute's allowed list. Can't be removed.
• Amber pills — values from the spreadsheet that aren't in the list yet. By default these will be added to the attribute's list at run start (so the rows don't fail). Click the × on a pill to opt out — those source rows will then fail with "value not in list" instead of extending the list.

This means existing dropdowns gracefully accept new vocabulary from MIDPs without you having to maintain the list manually — and you stay in control if you don't want that to happen.

For multi_select / array attributes, source cells with , or ; are treated as multi-value lists and split accordingly. Each part is matched against the allowed list independently.

Custom Attribute (Create New)

If your MIDP includes columns for attributes that don't exist in Forma yet, you don't need to create them by hand. Pick Custom attribute (create new), give the attribute a name, and pick a type:

For list / dropdown create-new mappings, the allowed-values editor works like the existing list editor:

• Locked pills — values pulled from the spreadsheet column. Can't be removed (the import would fail without them).
• Editable pills — extra values you've typed in. Press Enter in the input box to add, click × to remove.

If any source cell looks multi-valued (contains , or ;), Foreman flags the column as multi-value so the new attribute is created as multi_select rather than select.

The new attribute is created when you click Run import — not before. You'll see the count of attributes-to-create in the dry-run banner, and you must tick a confirmation checkbox for each one before the run can start.

Resetting Mappings After Switching Destination

Custom-attribute mappings are scoped to the destination folder you picked at Step 3. If you go back and change the destination, mappings that referenced attributes which don't exist in the new folder are reset to Ignore automatically — and a rose-coloured banner tells you which headers were affected.

Re-pick those columns: either point them at an existing attribute in the new folder, or switch them to Create new.

Conflict Policy (Step 5)

Once the role is decided, Step 5 lets you decide what happens when the file's target attribute already has a value:

The default is Fill blanks only because the most common failure mode for spreadsheet-driven imports is overwriting carefully curated data with stale MIDP entries. If your MIDP is the source of truth and Forma is downstream, switch to Overwrite explicitly.

The "Apply to all" buttons at the top of Step 5 set every writeable column to the same policy in one click. You can still tune individual columns afterwards.

What the Dry-Run Tells You About Mapping

After the wizard reaches Step 6, the Attribute coverage table is the fastest way to sanity-check your mapping decisions. For each writeable column it shows:

A row of zeros in Will apply with a high Will skip under Fill blanks only is the classic "Forma is already fully populated" signal — your MIDP isn't going to add anything new.

A row of high Will error counts means your column's data type doesn't match the attribute's. Look at the row-detail table or the report's Errors sheet for offending values.

See Also

• Importing File Attributes
• The dry-run report
• Import history and saved mappings