Skip to content

Submittals

StatusShipped
LinearPIN-464 ↗ PIN-465 ↗
ModuleSubmittals & RFIs ↗

Track shop drawings, product data, and samples from draft through the engineer's decision. Statuses walk a fixed chain, decisions other than plain Approved require engineer notes, and non-approved decisions trigger AI follow-up-task extraction. The xlsx/CSV log import is covered in Excel Imports.

Prerequisites

  • Role: PM (full lifecycle). Also log in once as an Estimator/Exec to verify read-only.
  • Project state: a project you can access; for the Spec Section dropdown, the project should have spec sections (otherwise the form falls back to free-text entry — both paths worth testing).
  • Test data: any PDFs from docs-pdfs/ in the test-app-files Drive folder for attachments and Smart Upload.
  • Permissions cached? Relogin if action buttons are missing.

1. Open the log

Project detail → Project Controls tab → Submittals sub-tab (default one; carries a count badge). Top of the log: four KPI tiles — Total, Open / Pending, Approved (with approval-rate %), Action Needed.

Toolbar: search box, status pills All / Open / Approved / Action, view toggle Items / By Spec Section, dropdown filters (vendors, ball-in-court, impact), and permission-gated buttons: Export Log (PDF/CSV), Smart Upload, Generate Register, Import CSV, New Submittal.

2. Create a submittal

New Submittal modal:

  • Spec Section * — dropdown of {number} — {title} when the project has spec sections; otherwise a plain input (placeholder 23 73 00) with a hint to add sections in the Spec Sections tab. Immutable after create — Edit doesn't let you change it.
  • Type * — Product Data (default), Shop Drawing, Sample, Test Report, O&M Manual, Warranty, Closeout.
  • Title , Responsible Vendor (project organizations), Submit By, CC (multi-select), Required On-Site, Lead Time (days)*, attachments.

⚠ Cost Code is intentionally NOT on the create form — it appears only in Edit (dropdown of {code} — {description}). Same for Received From. "Cost code missing on create" is intended behavior, not a bug.

3. Walk the status chain

Statuses: Draft, In Preparation, Ready to Submit, Submitted, Under Review, Approved, Approved as Noted, Revise & Resubmit, Rejected, Void. The detail header offers exactly one forward action per status:

Start Preparation → Mark Ready to Submit → Submit to GC → Mark Under Review → Log Response. Any non-terminal status also offers Void (danger). Approved and Void are terminal — Edit and lifecycle buttons disappear.

Log Engineer Response panel: Decision dropdown (Approved / Approved as Noted / Revise & Resubmit / Rejected) + notes textarea. Notes are required for every decision except plain Approved. Response files attach in the same panel. A non-Approved decision toasts "Analyzing comments for follow-up tasks…" and follow-up tasks appear after a few seconds.

Post-decision paths:

  • Approved as Noted → Acknowledge & Proceed or Hold for Review (a "Review Notes" chip shows in the log until acknowledged).
  • Revise & Resubmit / Rejected → Create Revision (REV column increments; revision history renders at the bottom of the detail).

Concurrency: edit the same submittal in two tabs — the second save must show "Submittal was changed by another user — reloading", not silently overwrite.

4. Attachments

Shared drop-zone on create, edit, and the decision panel: PDF, PNG, JPG only, max 25 MB — oversize and wrong-type files are rejected with explicit messages. On the detail view files list under Documents with Preview / Download / Remove.

5. AI paths

  • Generate Register — scans uploaded specs/drawings and bulk-creates entries ("…this can take up to a minute"). With no specs uploaded it must warn, not spin forever.
  • Smart Upload — upload a PDF → Analyze → AI extracts Spec Section / Type / Title / Vendor with a confidence chip, then: attach to a matched submittal, pick from an ambiguous candidate list, or Create new submittal. Try a docs-pdfs/ PDF that matches nothing — the create-new path must work.

Verification Checklist

  • Create form: Spec Section required, Cost Code absent (appears in Edit only)
  • Status chain enforces one forward action at a time; Approved/Void hide Edit
  • Non-Approved decision without notes is blocked with "Engineer notes are required…"
  • Approved as Noted shows the Review Notes chip until acknowledged
  • Create Revision bumps REV and keeps history
  • Attachment limits enforced (type + 25 MB) with readable errors
  • Two-tab concurrent edit surfaces the reload-conflict message
  • Read-only role sees the log but no New/Edit/lifecycle buttons
  • No console errors throughout

Known Issues / Current Gaps

  • ⚠ Detail↔log is an internal view switch (only ?submittal=<id> deep-link) — browser Back may behave unexpectedly; known charter caveat, not a new bug.
  • ⚠ Smart Upload attach can fail after creating the submittal — the toast says to open it and attach manually; that recovery path working is the test.
  • Excel Imports — the xlsx/CSV submittal log import
  • RFIs — the sibling Project Controls flow
Updating this walkthrough

Run the full flow yourself end-to-end. If it passes, bump last_verified: in the frontmatter to today's date. If any step fails, fix the doc or the code in the same PR — drift is the enemy.