> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Form submissions

> Understand a KayanOS form submission as a versioned session with an owner, saved state, actions, signatures, status, and access boundary.

## A submission is a session, not just a button click

KayanOS records a form interaction as a **form session**. The session ties the values entered by a participant to the form, the form version, its initiator, status, scopes, saved state, actions, and reference/code where configured. This is why a reviewer should not treat a screenshot or an emailed field value as the authoritative submission: the session is the traceable record.

Use Form submissions to review the Citizen Service Request lifecycle: start intake, save a draft, complete repeatable evidence, perform an allowed action/signature where required, submit, and let the right unit review the saved session.

![KayanOS submissions for Citizen Service Request records.](https://kayanos.app/docs-images/en/build/form-submissions.png)

## Core terms

| Term                    | Meaning                                                                         | Why it matters                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Form                    | The reusable service interaction design.                                        | It defines the form type, publication, access model, and current/released versions.                                           |
| Form version            | A specific saved structure for the form.                                        | A session should remain interpretable against the version that supplied its fields/rules.                                     |
| Session                 | One participant’s instance of a form.                                           | This is the record opened, saved, submitted, reviewed, and audited.                                                           |
| Saved state             | The stored field values and form state for that session.                        | Review the saved values, not only what a participant says they entered.                                                       |
| Draft                   | A session that is still being completed.                                        | It can be resumed only through the relevant ownership/permission boundary.                                                    |
| Submitted               | A session that has reached its submission state.                                | It is ready for the next approved review/workflow step; it is not automatically a final decision.                             |
| Code / reference number | A human-facing identifier when the form’s numbering configuration provides one. | Use it to communicate about a session without exposing internal IDs unnecessarily.                                            |
| Action                  | A configured form operation with a recorded call/state when it is used.         | An action can change the session experience or invoke a reviewed outcome; it still follows its runtime permissions and rules. |
| Signature               | A form item that captures a required signing step where configured.             | A visible signature control does not replace reviewing who may sign and what state/action it governs.                         |

The form ID, version ID, session ID, and reference/code serve different purposes. Use the human-facing code in operational communication where appropriate; retain technical IDs only in controlled support/audit records.

## Who can start, open, and change a session

Session access follows the form’s audience and KayanOS permissions:

* **Authenticated members** start a normal session only when they have the form’s `initiate` permission. The selected form/version must belong to the active organization.
* **Public participants** use the public-session route for an eligible published form; they do not use the member session-start endpoint.
* **Member reviewers** open a session when they are explicitly shared on it or have an appropriate `open` permission whose scope intersects the session scopes.
* **Public participants** are limited to their own public sessions. A public session does not make other public submissions browseable.
* **Offline submissions** follow their separate synchronization path. Once an offline session is submitted, a non-starter or unauthenticated client is read-only; only the starter can synchronize that offline submission.

Opening a session in a list does not grant a later change. Field editability, action rules, session ownership, form state, scope, and server-side validation are evaluated for the requested operation.

Submission is not a universal read-only switch. A field or repeater in a submitted session remains editable only when its configured editability expression and every relevant ancestor expression evaluate to true for the current member; server-side membership, render, and permission checks still apply. Builders can deliberately allow a correction role with a status-and-verb expression while leaving the same submitted content read-only for everyone else. Signatures retain their separate action and authorization rules.

An initiator can delete their own draft submission only when the form/session is still eligible for draft deletion and the dedicated delete capability allows it. Submitted sessions, another participant’s drafts, protected/system sessions, and records with blocking references are not covered by that convenience. Confirm the reference and draft state before deleting; deletion is not a correction workflow for submitted evidence.

## Find the correct form before reviewing submissions

The top-level **Form submissions** page at `/submissions` is now a temporary directory, not an aggregate cross-form submissions table. It groups the forms available to the current member by application and section, shows form counts, and lets the member collapse those groups. The former aggregate **New submission** action is not available on this page.

The directory includes a form only when the member has a non-empty `list`, `create`, or `initiate` grant for it. A directory link does not grant permission to open every session: session sharing, `open` scope, ownership, field rules, and action permissions are still enforced at the destination. If no forms appear, confirm the active organization and the member's form grants before changing access. If the directory fails to load, use its retry action and preserve the sanitized error for support.

Select a regular form to open its form-scoped submissions destination. An **Offline** card opens that form's separate offline submissions path. Run table filters, row review, and Excel exports at the form-scoped destination rather than expecting an organization-wide queue on `/submissions`. Prefer the form's application/section navigation for normal work: the temporary directory announces its retirement and should not become a bookmarked operating dependency.

## Lifecycle: start, save, submit, review

### 1. Start the correct version

For a member-facing regular form, start from the released form/version selected for the service. A preview session is for authoring/verification and must not be used as evidence of a real request. For a public service, use the published public-form path and its configured account, date, and submission conditions. For field work, use the separate offline package/runtime rather than attempting to start an offline form through the normal online session endpoint.

### 2. Save meaningful state

Saving preserves the session’s values so the participant can continue the request. Build forms so a partial draft is understandable: required evidence should be clearly marked, repeatable rows should keep their local meaning, and a resume path should not rely on someone remembering an unstructured note.

Example: a Registry clerk starts `CSR-2026-00042`, saves the applicant’s service category and Service Centre, then the inspector later adds repeatable observation rows and supporting files in the same controlled process.

### 3. Complete actions and signatures deliberately

An action or signature can be part of a form’s required journey, but it is not an automatic approval. Before relying on one:

1. Confirm the action/signature belongs to the current form version.
2. Confirm who can perform it and what server-side policy/status rule applies.
3. Test its positive result and a denied member/session.
4. Review the recorded action/session state after it completes.

Do not tell a citizen or field worker that a task is approved merely because an action button was pressed. The next authorized unit must review the resulting session/state.

### 4. Submit once, then review the session

Submission moves the session to the submitted state used by the form workflow. It may receive numbering according to the form’s configuration. The reviewer should open the server session and check:

| Review item            | What to confirm                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| Identity and ownership | Initiator type, intended participant/member, organization, and allowed scope.                                |
| Version                | The form/version is the one approved for this service process.                                               |
| Status and timestamps  | Draft/submitted state and created/submitted/received times make operational sense.                           |
| Saved values           | Required values, repeatable rows, calculations, and conditional fields are complete and coherent.            |
| Files                  | Files belong to the expected field/session and are readable only through the authorized session boundary.    |
| Actions/signatures     | Required action/signature records are present and their outcome matches the procedure.                       |
| Related work           | The correct Citizen Service Request, inspection, decision, or queue item is linked by the approved workflow. |

### 5. Preserve the audit path

Do not “fix” a questionable submission by changing values through an unrelated record or copying data into a new form. Record the review decision and use the released correction/reopen/next-step procedure for that form. If the version or session boundary is wrong, stop and resolve it with the form owner before creating a duplicate case.

## Submission status and approval proof

A form can use a configured submission status template. Its statuses and permitted transitions describe the submission lifecycle—for example, received, under review, returned for correction, or completed. They do not replace the request action, signature, or response evidence required for a formal decision. A submission labelled **Completed** is not necessarily **Approved** unless the configured approval workflow recorded that outcome.

When a form enters a formal approval round, KayanOS can expose a versioned PDF snapshot of the submitted state covered by that round. Use that document to review the exact labels, values, and evidence projection presented for the decision. The snapshot is immutable evidence for that version; it is not an editable working copy.

If an in-scope value changes, the old PDF and its responses remain evidence of the old round. Resubmission creates a new proof boundary and, when configured, a new versioned PDF. Compare the round number and snapshot version before relying on a downloaded copy. Never treat an older PDF, signature, or status as authorization for changed content.

## A complete Citizen Service Request example

1. A Registry member with the `initiate` permission starts the published **Citizen Service Request** form in the correct Service Centre scope.
2. The member saves a draft after recording non-sensitive intake values and receives the form/session reference according to the configured numbering policy.
3. The form’s repeatable Supporting Document or Observation section is completed with the correct number of rows. Each row is checked independently; an empty row is removed or explicitly handled according to the form rule.
4. If an inspection is required, the Field Inspection Team works through the approved form/session path. If connectivity is unreliable, it uses the offline form and waits for `synced` before the decision team treats evidence as received.
5. A required signature/action is performed by the appropriate role. The reviewer confirms the session record rather than relying on a verbal assertion.
6. The Decision and Records Unit opens the submitted session through its scope/permission boundary, verifies the saved state and files, then performs the separate authorized decision/status transition.
7. The service manager can report on the submitted session/reference without giving a public participant access to internal sessions or other citizens’ records.

## Public, member, and offline sessions are different boundaries

| Session path        | Start condition                                                            | Access boundary                                                         | Important caution                                                               |
| ------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Member regular form | Member has the form’s initiate permission.                                 | Member/reviewer permissions, scopes, sharing, and field/action rules.   | A member can be able to start a form but still be unable to open every session. |
| Public form         | A published regular form is eligible and public settings permit a session. | Public participant’s own session identity.                              | Public access is not internal record browsing or a general member permission.   |
| Offline form        | Authorized member prepared the offline package.                            | Starter/synchronization boundary plus later server-session permissions. | Local submission is not centrally received until synchronization succeeds.      |
| Preview             | Builder verification context.                                              | Authoring/preview context.                                              | Never use a preview as a production submission or audit record.                 |

## Export a multilingual submissions workbook

From the submissions table, use **More options → Export all** for rows matching the active search and filters, or select rows and choose **Export selected rows**. The export follows the current member's submission-list access and active organization; it does not expose another public participant's session or grant permission to open or change a session. Treat the downloaded Excel file as a new controlled copy of the submission data, and verify its purpose, recipient, approved storage, and deletion date.

Multilingual form fields and variables expand into one workbook column per configured organization language, identified by a language-code suffix such as `(en)` or `(ar)`. Select fields export a stable `(key)` column plus a label column for each configured language. A missing translation remains blank rather than falling back to another language. Keep the key for reconciliation, and review every required language before using labels in a report or handoff.

Check one authorized test submission before distribution: compare its session reference, each language-specific value, and each Select key/label with the live session. The workbook is a table export, not a versioned approval PDF or signature snapshot, and does not replace the session audit trail. If a language column is missing, verify the organization's configured languages and the form field's multilingual setting; if a label is blank, correct the option translation rather than guessing from another language.

## Repeatables, values, and files in review

Repeatables are not a single blob of “extra information.” Each instance contributes its own field values and validation outcomes. When reviewing a Citizen Service Request inspection:

* Count the Observation instances against the required/allowed bounds.
* Confirm the row-specific safety status, note, date, and attachment line up with the right observation.
* Check conditional fields in both the condition-met and condition-not-met cases; a hidden field is not necessarily valid or meaningful.
* Verify that a file is attached to the intended field path/session and has not been copied from a different request.
* For a calculated or expression-derived value, compare inputs and expected result rather than accepting a surprising output.

File download/upload URLs are issued for the authorized session boundary and expire. Do not copy a signed URL into a long-lived case note, public message, or external system. Link through the approved KayanOS record/session workflow instead.

## Test before publishing a service form

| Test                       | Expected result                                                                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Initiate permission        | Intended member can start the form; a member without it is refused.                                                                               |
| Version                    | A new session uses the approved version; a preview is visibly separate from a real session.                                                       |
| Draft/resume               | Saved values reopen coherently for the authorized participant.                                                                                    |
| Submitted editability      | Only fields/repeaters whose item and ancestor editability rules pass can be changed; an otherwise similar member remains read-only.               |
| Draft deletion             | The eligible initiator can delete a controlled draft, while submitted or out-of-scope sessions remain protected.                                  |
| Repeatable rows            | First, later, removed, and maximum-boundary rows behave as configured.                                                                            |
| Conditional/required field | Both branches save/submit according to the designed rule.                                                                                         |
| Action/signature           | Authorized path records the expected outcome; denied path does not bypass it.                                                                     |
| Form discovery             | Authorized member sees the regular or Offline form in its application/section and the temporary directory; unrelated member does not.             |
| Submission status          | Only configured transitions are available; a lifecycle status does not create approval proof by itself.                                           |
| Approval snapshot          | The PDF version matches the round being reviewed; a later correction produces a new proof boundary.                                               |
| Multilingual Excel export  | The filtered/selected workbook contains every configured language column, stable Select keys, and no substituted translation for a missing value. |
| Public access              | A public participant reaches only their own permitted session and sees no internal data.                                                          |
| Offline path               | Submitted local work becomes a server session only after a successful sync and is then reviewed centrally.                                        |
| File access                | Unauthorized participant cannot use a session/file URL to browse another submission.                                                              |

## Troubleshooting

| Symptom                                                              | Likely cause                                                                                                                                       | What to check                                                                                                                  |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| The top-level submissions page has no table or New submission action | `/submissions` is the temporary form directory, and aggregate controls were retired from that page.                                                | Choose the permitted form under its application/section, then review or start work in that form's scoped destination.          |
| The directory is empty or fails to load                              | No form has a non-empty `list`, `create`, or `initiate` grant for this member, the organization context is wrong, or the navigation bundle failed. | Confirm the organization and narrow form grants; use **Retry** for a load error and do not use a direct link to bypass access. |
| Cannot start a member form                                           | Missing `initiate` permission, wrong organization, no valid released version, or form type mismatch.                                               | Member role/scope, form ID/version, and whether the form is regular versus offline.                                            |
| “Form session not found”                                             | Wrong/expired reference, session ownership/load issue, or deleted/invalid session.                                                                 | Exact session/reference, organization, time, and whether the session was preview, public, member, or offline.                  |
| Can see a session but cannot edit                                    | Read-only field/session rule, submitted offline session, non-starter, or action/state restriction.                                                 | Session type/status, initiator, item editability, required action/signature, and server error.                                 |
| Public participant sees denial                                       | Public session identity does not match the session or the form is not eligible/published.                                                          | Public account/session context and portal/public settings; do not try a member endpoint with a public account.                 |
| An Excel export omits a language column or Select label              | The language is not configured for the organization, the field is not marked multilingual, or the option has no value in that language.            | Check organization languages and form field/option metadata; do not substitute a translation or broaden submission access.     |
| File is missing/unreadable                                           | Upload did not finish, field path/session mismatch, expired signed URL, or access denial.                                                          | Session saved state, file field, sync state if offline, and authorized session access.                                         |
| Duplicate request suspected                                          | A retry or new session was created instead of reconciling the existing session.                                                                    | Reference/code, session ID, initiator, local submission ID for offline work, and timestamps before creating another.           |

## Permissions and data-quality limits

Form submissions can contain sensitive citizen, staff, location, and operational data. Give each unit only the initiate/open/update/action scope it needs. Do not share a public link, session ID, file URL, or screenshot as a substitute for controlled access. Use approved non-production data for testing, preserve the form version with the test evidence, and include the session/reference and sanitized error in a support escalation.

## Related guides

* [Forms](/build/forms)
* [Forms, fields, and repeatables](/build/form-fields-and-repeatables)
* [Form actions, logic, and signatures](/build/form-actions-logic-and-signatures)
* [Offline forms](/build/offline-forms)
* [Public portal](/build/public-portal)
* [Form builder context](/reference/forms/form-builder-context)
* [Permissions and availability](/reference/permissions-and-availability)