Save flow, what happens when the user clicks Submit

The two-phase save pipeline, validation, primary write, then post-save writers for attachments, signatures, images, and child rows.

When the user clicks Submit, SharePoint Forms365 runs a deterministic, two-phase save pipeline:

Phase 1, Pre-flight

  1. Declarative validation. Every field with required, pattern, requiredIf, or any other schema rule is checked. The first invalid field gets focus and shows an inline error.
  2. Author validation. Per-field onValidate handlers and the form-level onValidate hook run. Any returning a string is treated as a validation error.
  3. onBeforeSave. The form-level hook fires. Authors can cancel submission by returning { cancel: true }. This is the right place for confirmation prompts, threshold checks, or last-minute data shaping.

Phase 2, Write

  1. Field mapping. Every visible, writable field's value is shaped into the payload the SharePoint REST API expects. Type-specific quirks (Lookup expects {Field}Id; MultiChoice expects { results: [...] }; a Taxonomy column with several terms is written to its hidden note column) are handled by the per-type field mappers.
  2. Read-only stripping. SP-managed columns (Created, Modified, ID) and Calculated columns are dropped from the payload, sending them would cause SharePoint to reject the whole write. Sealed columns are kept: Sealed locks the column definition, not its value.
  3. Primary write. PnPjs writes the item. If this fails, the save flow short-circuits and onSaveError fires.

Phase 3, Post-save writers

Some field types can't write in the primary phase because they need the new item's id first. They register post-save writers that run after step 6:

  • Attachments, upload files via the SP Attachments endpoint
  • Image fields, upload to the Image column with the item id in the URL
  • Signature, upload the captured PNG
  • LinkedList children, write child-list rows with the parent's id

Taxonomy is not on this list: it saves entirely in the primary write, and SharePoint keeps the hidden TaxCatchAll column up to date itself.

If a post-save writer fails, the item still exists, just without that particular asset. Authors handling regulated workflows should monitor for items where a required signature/attachment is missing.

Phase 4, onSave

  1. onSave. The form-level hook fires with the item id. Authors can show a confirmation toast, redirect somewhere, kick off a flow, etc.

Cancellation

Submission can be cancelled at three points:

  • A declarative validation failure (step 1), surfaced inline next to the bad field
  • An author onValidate failure (step 2), same treatment
  • An onBeforeSave returning cancel: true (step 3)

After step 4 begins the write is committed; cancellation is no longer possible.

Related articles

  • Submit button

    The form's primary action button, triggers validation, the save flow, and any onBeforeSave / onSave handlers.

  • Signature field

    Canvas-based signature capture, finger, stylus, or mouse. Saves as a PNG image to a SharePoint Image column or the item's Attachments.

  • Attachments field

    Upload files attached to the SharePoint list item, and print attached photos as pictures in the PDF report.

  • Validation, schema, expression, and author-defined

    Three layers of field validation, when each runs, and how errors surface in the UI.