Pushing Files to the Cloud

Why push files?

You ran QA on a local PDF or a file already in the cloud. The next manual step has always been to open the destination, find the right folder, upload the file, and re-key the metadata. Pushing files closes that loop: Foreman uploads the file to the destination folder you pick, fills in custom attributes from PDF zone values and filename segments, and stamps Foreman QA Status — all from the run-detail page.

This is the file equivalent of pushing findings to Forma Issues: findings give your team something to fix, files give them the approved version to publish.

Different from issue push. Push files publishes the file itself to a destination folder. Push issues creates issues for violations. The two work side-by-side on the same check run.

Where files can go

The push dialog is multi-cloud. The destination tab strip at the top of step 1 shows every cloud your tenant has the module for and you have a connected account for:

Cloud	Module	What it creates
Forma (ACC / BIM 360)	Always available	New items / new versions in a Forma folder, with ACC custom attributes filled
SharePoint	File Operations + SharePoint connection	New / replacement files in a document library, with library columns filled
Box	File Operations + Box connection	New / new-version files in a Box folder, with Box metadata filled

If only one destination is available, the tab strip is hidden and the dialog goes straight to the folder picker.

What can be pushed

Two source types both work — and they can both go to any cloud:

Source	Where the bytes come from	Typical workflow
Local upload	A PDF you uploaded into a QA run (stored under admin retention)	Review the file in Foreman, push to Forma / SharePoint / Box when approved
Cloud file	A file already in a cloud project (downloaded then re-uploaded to the destination)	Promote a file from one folder to another (e.g. WIP → Shared) — same cloud or across clouds

For same-cloud copies, every existing custom-attribute value on the source version is carried over to the new file, then your zone- and filename-derived mappings overlay on top.

How to push

From a completed check run's detail page:

1. Top action bar — click Push all files (the button shows the count of eligible files in the run). The split button on the right opens a destination menu so you can pick Forma, SharePoint, or Box. Choosing nothing defaults to the run's source cloud.
2. Sticky selection bar — tick checkboxes next to specific files, then click Files to Cloud in the bar that appears at the bottom. Only the selected files are sent to the dialog.

The dialog has three steps: Pick the destination, Map the attributes, Push & publish.

Step 1 — Pick the destination

The dialog header shows the destination cloud's logo and the project / hub / site / folder you're pushing into. Below it:

• Destination cloud tabs (when more than one is available). Click a tab to switch — the folder tree below reloads from that cloud.
• Folder tree for the chosen cloud. Click a folder to select it as the destination.
• Refresh icon (top-right of the folder tree) — re-fetches the entire tree from the cloud, clearing any cached node lists. Useful when a teammate has just created a folder you can't see yet.
• The destination defaults in this order: hub/project from the run's URL → hub/project on the run record → your last successful push target (cached locally so the next push starts where you left off) → your only project, when there's exactly one → the first project, otherwise.

The "Push files to cloud" header is always visible across all three steps, so you see where files are going right up to the moment of upload.

Same name vs unique name

When you preview the push, every file is checked against the destination folder:

• Unique name → creates a new item (a new file in the folder).
• Same name as an existing file → uploads as a new version of that item.

The decision is shown next to each file before you commit, so there's no surprise at execute time. A blue banner at the top of step 2 totals up how many files will become new versions, with a reminder that previous versions are preserved in version history.

Duplicate-name preflight

When you click Push N files, Foreman runs a preflight check against the composed names — the actual names that will land at the destination after your filename mapping is applied. If any names collide, a confirmation dialog opens before the upload starts:

Conflict type	What it means
Shared in push	Two or more files in the same push will compose the same destination name. They merge into one item and only the last upload's content is the visible tip. Earlier ones are kept in version history.
Merges into existing	The composed name matches a file already at the destination. The upload becomes a new version of that existing item.

Each conflict row shows the source file name, the composed name it produces, and the resulting effect. Click Push anyway to proceed (when the consolidation is intentional — e.g. you're rolling several revisions into one canonical file) or Cancel — adjust composition to go back to the mapping table and split them apart.

Step 2 — Map the attributes

The dialog renders one row per destination custom attribute (or column, on SharePoint). For each row you choose what to write:

Source	What it is
— Don't write —	Skip this attribute.
Zone value	Extracted text from a named PDF zone (e.g. DrawingNumber, RevisionStamp).
Filename segment	A segment of the filename, split by your configured separator (filename mapping).
Carryover from source	The existing value on the source version (same-cloud copies only).
File name (with/without extension) or File extension	Built-in source — the file's own name, sliced as you like.
Combine values…	Compose multiple sources + literal text into a single value — see Composite attribute mapping.
Custom value…	A literal you type once, applied to every file in the push.

Foreman auto-suggests a source for each attribute by name match across every file's available sources, with priority Zone (mapped) → Zone (matching field name) → Filename segment → Carryover. Tick the Write checkbox to include a row; untick to skip.

Splitting a source value

Any source can be split before writing. Set a separator (e.g. _ or -) in the Split by column, then choose All, First, Last, or a Specific segment number. Useful for ISO 19650 filenames where each underscore-delimited segment carries different metadata.

Foreman resolves the split per file at execute time, so the same row can produce ACE for one file and BKR for another from the matching segment.

Filename mappings (saved separator + segment definitions)

For convenience, you can save a named filename mapping — a delimiter plus an ordered list of segments (e.g. Originator_Volume_Level_Type_Role_Number) — and attach it to a folder via the run's per-folder rule-set mapping. When set, every file in that folder offers a labelled Filename segment 1 (Originator), Filename segment 2 (Volume) etc. as available sources, on top of the unlabelled split column above.

Saved mappings (presets + auto-memory)

The mapping action bar has a Mapping ▾ menu that lets you save the current row configuration as a named preset, apply a saved one, or open the management page. Foreman also silently remembers your last successful mapping per (folder, cloud) and offers to restore it next time you push to the same place. See Attribute mapping presets & auto-memory for the full flow.

Type-aware writes

Numbers, dates, and dropdown / array attributes are validated before push:

• A number attribute mapped to a free-text source flags a Must be a number warning.
• A dropdown or array attribute (like Foreman QA Status) shows the allowed values; mapping a source whose resolved value isn't in the list shows a won't be applied warning, and the row is skipped client-side rather than letting the cloud reject it.

The preview value column shows the resolved value for the highlighted file in the file list above. Click another row to switch which file the preview is rendered against.

Filename sanitization warnings

Cloud platforms have different rules about which characters are legal in file names. Foreman previews the cleaned name and surfaces an amber warning underneath the File name (display name) row when characters will be stripped or replaced:

Cloud	Stripped/replaced characters (typical)
Forma	\ / : * ? " < > \|
SharePoint	~ # % & * { } \ : < > ? / + \| " (also leading/trailing spaces and dots)
Box	very permissive — only the platform-reserved few

The push uploads the cleaned name. The warning shows what the resolved value started as, what changed, and the final cleaned form. If you don't want a character stripped, edit the source value (or change the composition) before pushing.

Manual / literal values

Pick Custom value… in the source dropdown to type a value by hand. The input changes shape based on the destination type — a date picker for date, a number input for numeric, a dropdown of allowed options for array / dropdown, a textarea for paragraph, plain text otherwise. SharePoint columns get matching types (currency, hyperlink, yes/no, etc.).

Built-in display name

A row at the top of the table called File name (display name) is auto-suggested to File name (with extension). Map it differently (e.g. File name (without extension) + Split by - + Specific 1, or Combine values… to build a name from zone values) to rename the file at upload time. The original extension is always re-appended automatically — your composition becomes the file's name, the extension is added on upload. This works the same for Forma, SharePoint, and Box.

Inline "Create attribute / column"

If the destination is missing an attribute you want to write, click + Create attribute / column in the action bar to add one without leaving the dialog. The form picks the right attribute types per cloud — Forma offers Text / Paragraph / Numeric / Date / Dropdown list; SharePoint offers Single line / Multiple lines / Choice / Number / Currency / Yes/No / Date and time / Hyperlink. The new attribute appears as a row in the mapping table immediately and you can wire it to a source.

Bulk actions

• Mapping ▾ → Apply preset — overlay a saved preset on top of suggestions.
• Mapping ▾ → Save current as preset… — save the current mapping as a named preset.
• Mapping ▾ → Manage presets… — open /settings/attribute-mappings in a new tab.
• Reset to suggestions — restore every row to the source the system suggested when the preview loaded.
• Uncheck all — tick nothing; files still upload, just without metadata.

Step 3 — Push & publish

Click Push N files to start. After the duplicate-name preflight passes (or you confirm), step 3 is a live progress view:

• A progress bar with percent complete.
• The current file name and phase (Uploading, Creating in destination, Writing attributes).
• Live tallies for Succeeded, Partial, and Failed.
• A collapsible "Completed so far" list showing each file's status as it finishes.

Click Cancel push to stop after the file currently in flight finishes. Files already pushed stay in the cloud — cancellation never reverses uploads.

When the run finishes, the per-file results table shows:

Column	Meaning
File	The file's display name (the override you mapped, if any)
Status	Success, Partial, or Failed
Action	New item or New version
Attrs	Attributes written / attributes attempted
Note	Action label, or the error message on failure

Foreman QA Status — stamped automatically

If the destination project has QA writeback enabled, every pushed version is tagged with the source check result's verdict on the configured custom attribute (default: Foreman QA Status):

Check result	Verdict written
Passed	Pass
Failed	Fail
Warning	Warning
Skipped	Not Checked

The verdict travels with the file — auditors see it next to the document in the cloud rather than in a separate report. The push uses the same vocabulary as the end-of-check writeback, so a file pushed manually and a file tagged at end-of-run end up with identical values.

If writeback is enabled but the configured attribute isn't visible in your destination folder (folder-scoped attribute), the writeback is skipped silently and noted in the push record. The file still uploads.

Same-cloud metadata carryover

When you push a cloud-resident file into the same cloud (rather than a local upload or a cross-cloud copy), Foreman:

1. Reads every existing custom-attribute value on the source version.
2. Resolves each one by name against the destination folder's attribute definitions (in case folder-scoped attribute IDs differ).
3. Carries forward every value that resolves; logs the rest as definition_missing_in_destination in the push record.
4. Overlays your zone and filename mappings on top — your explicit mappings win on key collisions.

Net result: copying a file from one folder to another preserves its metadata. The only attributes that change are the ones you explicitly mapped.

Auto-push on pass

Each per-folder rule-set mapping supports three optional fields that turn the manual push into an automatic step at the end of the check run:

Field	Effect
Auto-push on pass	When a file in this folder passes QA, push it to the destination folder automatically at the end of the run.
Auto-push destination folder	Where to push — typically the Shared folder paired with this WIP folder.
Include warnings	When on, files with Warning status are auto-pushed too; otherwise only Passed files.

Auto-push uses the same engine as the manual dialog. Failures are recorded on each push record but never block QA completion — your check run finishes regardless of cloud-side issues.

Auto-push is off by default. Turn it on per folder when you want a hands-off WIP → Shared lifecycle.

Where teams use it

Pattern	What it looks like
Promote on pass	Designers work in Work in Progress. Auto-push is on for that folder, paired with a Shared destination. The moment a file passes naming, metadata, and title-block checks, it lands in Shared.
Submission packs	Run QA across the latest revisions, then push the approved files into a Stage 4 — Submission folder. Foreman QA Status stamped on each file means the auditor can see the verdict beside the document.
Project templates	A master project holds canonical templates (site logistics plans, company details, drawing-issue-sheets). Push them into every active project's 03 Standards folder. Same file, many homes — and metadata travels with each copy.
Cross-cloud handover	Run QA on a Forma project; push the approved deliverables into a SharePoint document library or Box folder for a client that doesn't use Forma. Filename / metadata translation happens at the mapping step.
Resubmit a fix	A reviewer flagged an issue. You fix the file, re-run QA, then push — the destination recognises the same name and uploads it as a new version of the original. The version history tells the story.

Push records and audit trail

Every push (manual or auto) writes a QAFilePushRecord with:

• Source type (LocalUpload / CloudFile) and source path/version
• Destination cloud, folder, item, and version IDs
• Action (NewItem / NewVersion)
• Attributes written, with per-attribute success / failure / source (Zone, FilenameSegment, Carryover, Manual, Composite, QaWriteback)
• Status (Success / PartialSuccess / Failed) and any error

Two audit events fire per file: QA.FilePushed (always) and QA.FileAttributesWritten (when at least one attribute landed). Both appear in the Organization Activity feed with the actor, file name, destination, and counts — useful for evidence of when and how a file reached the cloud.

Permissions and cloud requirements

To push to a destination folder you need edit permission on that folder in the target cloud. Foreman calls each cloud using your own connected account, so any restriction your role enforces applies here too.

Cloud	Required scopes / permissions
Forma	APS connection with data:write, data:create, bucket:read
SharePoint	Microsoft 365 connection with Sites.ReadWrite.All (or site-scoped equivalent)
Box	Box connection with file write permission on the destination folder

The dialog surfaces a clear Reconnect hint if any scope is missing.

The push respects the File Operations module gate. If your tenant has File Operations disabled, the Push files button is hidden and the API endpoint returns a module_disabled response. SharePoint and Box destinations require their respective tenant modules to be enabled.

Limits

• Up to 100 files per push in a single run. Larger selections need to be split.
• Up to ~100 MB per file with the current single-part upload. If you hit a failure on a large file, split the push or switch to an existing version.
• Foreman QA Status must already exist on the destination folder (enabled via QA writeback) — the push doesn't create the attribute.

Next steps

• Composite attribute mapping — combine multiple sources + literals into one value
• Attribute mapping presets & auto-memory — save and reuse the row configuration
• Understanding Check Results — where the run-detail Push button lives
• Managing Violations — bulk-update violation statuses on the same page
• Running QA Checks — set per-folder rule sets and auto-push destinations
• Pushing Findings to Forma Issues — push violations as issues alongside files