Attribute Mapping Presets & Auto-Memory

What problem does this solve?

The push dialog is powerful but the mapping table can take a few minutes to set up — pick the right source for each attribute, set splits, build composite values for the display name. If you push to the same folder every Friday, redoing all that from scratch is friction. Presets and auto-memory remove it:

• Auto-memory silently remembers your last successful mapping per (folder, cloud) and restores it next time.
• Named presets let you save a mapping with a name and apply it on demand. Default scope is User (only you see it); you can promote it to Tenant so the rest of your team picks it up.

Both layers store the mapping by attribute name (not destination ID), so saved data is portable across folders, projects, and even across clouds where the attribute names line up.

Auto-memory — the silent layer

Every time a push succeeds, Foreman writes the mapping you used to a small per-user record keyed by (your user, feature, cloud, target folder). Last write wins; there's no version history.

Next time you open the push dialog and pick the same destination folder, the dialog overlays that remembered mapping on top of the auto-suggestions. A small slate chip appears in the action bar:

✓ Restored from your last push to this folder · ×

Click the × to clear the chip and revert to suggestions. Editing any row also clears the chip — once you change the mapping, the "restored" badge is no longer accurate.

Auto-memory is per-user, per-cloud, per-folder. It doesn't follow you across teammates and it doesn't touch tenant presets. It's the cheapest layer — zero clicks to save, zero clicks to reuse.

Auto-memory writes are not audited — they'd be too noisy. If you need an audit trail (who applied what, when), use a named preset instead.

Named presets — the explicit layer

The push dialog's attribute mapping action bar has a Mapping ▾ menu:

Mapping ▾
├─ Apply preset
│   ├─ ─ My presets ─
│   ├─ Drawings — standard      [user]
│   ├─ ─ Tenant presets ─
│   ├─ Office Project Defaults  [shared]
│   └─ — none —
├─ + Save current as preset…
└─ Manage presets…

Saving a preset

1. Configure the mapping table the way you want it.
2. Click Mapping ▾ → + Save current as preset….
3. Type a name (e.g. Drawings — standard) and an optional description for teammates.
4. Click Save preset.

The preset is saved with User scope — only you can see and apply it. The mapping is captured by attribute name, so it works against any folder that has attributes with matching names.

Applying a preset

Open Mapping ▾, click any entry under My presets or Tenant presets. The preset overlays on top of the suggestions — explicit mappings in the preset win over auto-suggestions for matching attribute names. A chip appears in the action bar:

✓ Applied: Drawings — standard · ×

Attributes that don't exist in the current destination are silently dropped. Source tokens that don't resolve on a given file produce empty values — which the existing skip-empty path handles, so the file still uploads.

Clearing the applied preset

Click the × on the chip, or pick Reset to suggestions in the action bar.

User scope vs Tenant scope

Every preset has a scope that controls who can see and use it:

Scope	Who sees it	Who can edit it	Who can delete it
User	Only the owner	Owner only	Owner only
Tenant	Everyone in the tenant	Owner or any tenant admin	Owner or any tenant admin

New presets default to User scope. The owner can promote their User-scoped preset to Tenant — it then becomes available to every teammate in the dropdown. A tenant admin can demote a Tenant preset back to User scope; it reverts to the original owner's private list.

Demoted presets keep their original OwnerUserId. If the original owner has been deleted, the preset stays (the tenant still owns it) — display falls back to Unknown user gracefully.

Managing presets — /settings/attribute-mappings

Click Mapping ▾ → Manage presets… in the push dialog, or open Settings → Attribute Mappings from the sidebar.

The management page has two tabs:

• My presets — every preset where you're the owner, regardless of scope
• Tenant presets — every Tenant-scoped preset visible to your tenant

Each row shows the preset's name, description, feature kind (currently always Push; future: Transfer, Extract), provider hint, last-used timestamp, and an action cluster of icon buttons on the right — all on one line:

Icon	Action	Visible when
⇈	Promote to tenant	You're the owner and the preset is User-scoped
⇊	Demote to user	You're a tenant admin and the preset is Tenant-scoped
👁	View mapping JSON	Always — opens a modal with the pretty-printed mapping payload + Copy JSON
✏	Rename	You can edit the preset (owner, or admin for Tenant-scoped)
🗑	Delete	You can edit the preset

Promote, demote, and delete each open a confirmation dialog. The browser's default window.confirm() is not used — it's a styled in-app modal so the action and its consequences are clear.

View mapping JSON

The eye icon opens a modal showing the preset's stored payload, pretty-printed. The format is:

{
  "Drawing Number":  { "selectedSourceToken": "Zone:DrawingNumber", "include": true, ... },
  "Revision":        { "selectedSourceToken": "FilenameSegment:Rev", "splitSeparator": null, "segmentIndex": 0, "include": true },
  "__displayName__": { "selectedSourceToken": "composite", "include": true,
                       "parts": [ { "kind": "token", "sourceToken": "Zone:DrawingNumber" },
                                  { "kind": "literal", "literalText": " - " },
                                  { "kind": "token", "sourceToken": "FilenameSegment:Rev" } ] }
}

Click Copy JSON to copy the payload to your clipboard — handy for debugging, support requests, or copy-pasting into a teammate's tenant.

The __displayName__ sentinel is the built-in File name (display name) row — same as in the push dialog. Source tokens reference source-side names (zone field, filename segment key, carryover attribute name), not destination IDs. That's what makes a preset portable across folders.

Quotas

Active tiers and their per-user preset limits:

Tier	User-scoped presets per user
Starter	5
Business	unlimited
Enterprise	unlimited

Tenant-scoped presets are unlimited — admins decide what to share. Promote frees a user-slot; demote re-consumes one.

A Starter user who tries to save a sixth preset gets a 402 response with a tier-upgrade hint shown in the dialog: You've reached your preset limit (5). Upgrade to Business for unlimited presets, or delete an existing preset to make room.

Audit events

Every preset action writes an audit event visible in the Organization Activity feed:

• attribute_mapping.preset.created
• attribute_mapping.preset.updated (rename or mapping change)
• attribute_mapping.preset.deleted
• attribute_mapping.preset.promoted (User → Tenant)
• attribute_mapping.preset.demoted (Tenant → User)

Auto-memory upserts are not audited.

Cross-feature design

Presets and auto-memory are deliberately feature-agnostic. The data model uses a FeatureKind enum (Push, Transfer, Extract) and the management page lives at /settings/attribute-mappings rather than under QA. Today only the QA push dialog reads and writes them; future capabilities (cross-cloud file transfer, attribute extract jobs, scheduled pushes) will share the same store and the same management UI.

That's why the management page is in the Settings sidebar group, not the QA one — and why a preset saved against a Forma push can be applied to a SharePoint or Box push, as long as the attribute names line up.

Cross-cloud applicability

Presets are stored against a ProviderHint that records the cloud you saved the preset on, but the payload is portable. Applying a Forma-saved preset to a SharePoint push works for any attribute whose name matches a SharePoint column — the rest are silently skipped, exactly like cross-folder application within one cloud.

If a preset routinely needs to apply to multiple clouds, leave the ProviderHint empty when you save it. Foreman will show it under both clouds' "My presets" lists in the dropdown.

Where teams use it

Pattern	What it looks like
Project standard	The doc controller sets up a mapping that fills Discipline, Originator, Volume, Type, Number, Revision from filename segments and Status from the title-block zone. Saves as Project Standard, promotes to Tenant. Every teammate's push dialog now applies it in one click.
Per-discipline	Architecture team has a mapping that pulls Drawing Number and Sheet Title from zones; Structures team has one that pulls Calc Sheet Reference from a different zone. Both saved as User-scoped presets; no cross-team noise.
Forma → SharePoint handover	A preset called Client Handover (SP) maps the canonical Forma values into the client's SharePoint column names. Applied automatically by auto-memory after the first push to that library.

Permissions

• Save / rename / delete your own preset — no special role required.
• Promote your own preset — no special role required (you're sharing your own work).
• Demote a Tenant preset — requires tenant admin.
• Edit / delete a Tenant preset you don't own — requires tenant admin.

The endpoints under api/attribute-mappings/* enforce these rules server-side; the management page UI just hides the icons that don't apply.

Next steps

• Pushing Files to the Cloud — where presets are applied
• Composite attribute mapping — preset payloads include composite definitions
• Running QA Checks — per-folder rule sets pair well with per-folder auto-push