Importing File Attributes from a Spreadsheet

Overview

Attribute Import is the inverse of Attribute Extract. Instead of pulling metadata out of Forma, it pushes a spreadsheet (your MIDP, document register, or any Excel file) into Forma — writing each row's values onto matching files as built-in display names and custom attributes.

It's designed to be safe by default:

• Match-key-driven. Each row finds its file via a single "match" column (typically the file name). Rows that don't match are reported, never guessed at.
• Dry-run first. Every wizard ends on a preview that shows exactly what would change — and what wouldn't — before any value is written.
• MIDP gap report. The same dry-run computes coverage in both directions: rows that don't have a file, and files that don't have a row. The downloadable XLSX is also a stand-alone audit deliverable.
• Configurable conflict policy. Per-attribute choice between Fill blanks only (default), Overwrite, or Skip if existing.
• Auto-create attributes. Columns that map to attributes that don't exist yet can create them at run start (with explicit confirmation in the dry-run step).
• Multi-sheet. A single import can pull rows from several sheets in the same workbook (e.g. an MIDP that splits content by stage or discipline).

Navigate to Import from the sidebar (under Files & Folders) to get started. The page is also reachable as /attribute-import and /attribute-import/{HubId}/{ProjectId}.

The 6-Step Wizard

The import process follows a six-step wizard. The step indicator lets you click any completed step to jump back and adjust.

Step 1: Source

Drop or browse for a spreadsheet. Accepted: .xlsx, .xls, .csv. Maximum 50 MB.

After upload Foreman parses every sheet, caches the first 100 rows of each as a preview, and shows a summary card with sheet and row counts. Use Replace file to upload a different one without leaving the wizard.

Step 2: Sheet and Header Row

Choose the sheet you want to import and tell Foreman which row contains the column headers. Row 1 is the top of the sheet — increase this if your file has a banner, logo, or metadata block above the actual headers.

The preview table redraws as you change either field, so you can verify by eye. Cells with a blank header are highlighted in red — those columns are unmappable until you fix the header in the source file or pick the right header row.

Multi-sheet imports

If your MIDP splits content across several sheets that share the same columns (e.g. one tab per stage), click Add another sheet to add it to the import. Each tab can have its own header-row position, and the same column mapping is applied to every selected sheet. Sheets that turn out to be empty at the chosen header row are skipped with a warning rather than blocking the run.

Step 3: Destination

Pick the hub, then the project, then the destination folder from the folder tree. The folder is the root from which Foreman resolves files recursively — every file under that folder is in scope for matching.

Selection is single-select: clicking another folder switches the destination. The currently selected folder is shown beside the tree with its full path so you can verify before continuing.

Step 4: Map Columns to Attributes

For each column header in the source file, pick what it should do:

Each row in the mapping list shows the column's first sample value to help you choose. Coloured pills make the role visible at a glance: green for match key, purple for built-in, blue for existing, amber for create-new, grey for ignored.

See Mapping columns to attributes for a deep dive on list/dropdown attributes, allowed-value extension, and auto-create.

Step 5: Conflict Policy

For each writeable column (built-in display name, existing custom attribute, new custom attribute), pick what happens when the destination already has a value:

A row of "Apply to all" buttons at the top of the table sets every mapping to the same policy in one click.

Step 6: Dry-Run Report

The final step builds a full preview without writing anything to Forma. You can:

• Read the MIDP coverage hero (% of files in the folder that the spreadsheet references) and the counter pills (matched / orphaned / ambiguous / files-not-in-sheet / cells to apply).
• Expand the Attribute coverage table to see, per attribute, how many rows will apply / skip / error and how many target files are already populated vs blank.
• Expand Show row details to inspect every row's classification and per-cell action.
• Filter rows by source sheet (multi-sheet imports only).
• Confirm any new attributes that the run will create (the run cannot start until every new attribute is ticked).
• Click Download report (XLSX) for a 9-sheet workbook you can hand to your team — see Dry-run report deep dive.
• Click Save mapping… to reuse this configuration later.
• Click Run import → when you're ready.

See The dry-run report for what each section means and how to use the XLSX as a stand-alone MIDP audit.

Running the Import

Clicking Run import opens a live progress dialog with:

• A circular progress ring and percentage.
• Counters for Applied, Skipped, and Failed (updated row-by-row).
• A note when new attributes are created in Forma.
• The current file being processed.
• A scrolling list of recent errors if any.
• A Cancel button at any point — the run stops gracefully and is recorded as Cancelled in History.

The dialog is non-blocking — you can leave the page; the run continues server-side. Re-opening the page or the History tab will show the in-flight run.

What Counts as a Match

For each row, Foreman compares the value in the match column to file names in the destination folder (recursive):

1. Exact match on full file name (including extension). One match → row classified ok. Multiple → ambiguous.
2. Stripped match — if no exact match, retry against the file's name without extension. Same disambiguation as above.
3. No match → row classified orphaned.

Rows where the match column is blank are also classified as orphaned and skipped.

Ambiguous rows are reported in the dry-run with the folder paths of every candidate so you can disambiguate at the source — typically by adding a folder column or making file names unique.

History and Saved Mappings

Two additional tabs sit alongside the wizard:

• History — your last 50 runs with their counts and status. Click any row for a slide-out with the full mapping, destination, source details, and recent errors.
• Saved Mappings — configurations saved from the dry-run step. Load one at any time to pre-fill the wizard for the next run.

See Import history and saved mappings for details.

Plan Limits

Attribute Import is part of the File Operations module on Foreman. Tenants on plans where this module is enabled can use the feature; tenants where the module is disabled will see a 403 from the API and the page will be hidden in the sidebar.

There is no per-run quota — the limiter is your destination project's tolerance for write traffic.

See Also

• Mapping columns to attributes
• The dry-run report
• Import history and saved mappings
• Extracting File Attributes