> ## 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.

# Offline forms

> Design a constrained field-work form that stores work and files locally, then synchronizes an auditable submission when connectivity returns.

## Offline is a deliberate form type

An offline KayanOS form is for field work that must continue through a connectivity gap. It is not a regular form that happens to be opened without a network. Before the field visit, an authorized member downloads/prepares the form package while connected. The device then keeps the form definition, local sessions, attached files, and synchronization queue locally until it can send a submitted session to KayanOS.

Use it for a Field Inspection Team recording repeatable observations and photographs at a Service Centre locality. Do not use it when the work needs live entity lookups, public access, a prefilled link, dynamic workflow actions, or a data-dependent authorization decision at the point of entry.

![KayanOS offline form for a field inspection.](https://kayanos.app/docs-images/en/build/offline-forms.png)

## Decide whether the form is suitable

Choose an offline form only after answering these questions:

| Question                                              | Offline-safe answer                                                                 | Choose a regular form when…                                                                          |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Can the worker complete the fields without live data? | Yes—labels, local values, fixed options, and deterministic calculations are enough. | The worker must query a changing entity, selected session, live option source, or permission result. |
| Can the workflow use the standard submit/sync path?   | Yes—the submission can be reviewed after it reaches KayanOS.                        | It must call a custom action or another online workflow at the moment of submission.                 |
| Is the audience an authorized field member?           | Yes—the package is prepared for controlled field work.                              | The form is a public intake channel or needs a public/prefilled URL.                                 |
| Can the device retain the work safely?                | Yes—the organization has device, storage, and loss/return procedures.               | The data must never reside locally or needs immediate central visibility.                            |

An offline form should be small, clear, and self-contained. If a requirement cannot be tested without connectivity, make it a regular form or move the review step to the synchronized workflow.

## What KayanOS stores locally

The device’s local offline store keeps four related kinds of data:

| Local item      | What it contains                                                                                                                                     | Operational implication                                                                                                 |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Form package    | Form ID/version, downloaded and updated times, title, and the form structure.                                                                        | A field worker needs the intended package before leaving connectivity. Verify the version during preparation.           |
| Local session   | Draft/submitted status, saved form state, device timestamps, local submission ID, scopes, sync state, and a possible server session ID/receipt time. | A locally submitted session is not yet centrally received until it reaches `synced`.                                    |
| Local file      | File blob, field path, name/type/size, and later the uploaded file ID.                                                                               | A photo may exist only on the device until upload succeeds. Preserve it while investigating a failed sync.              |
| Sync queue item | Session ID, state, attempts, next retry time, and last error.                                                                                        | The queue is evidence of what still needs attention; do not create a duplicate form merely because one item is waiting. |

This design allows the app to replace local file references with uploaded KayanOS file references before it commits the server session. It also means a lost, wiped, or inaccessible device can contain the only copy of an unsynchronized submission. Establish a device-handling and incident process before relying on offline work.

## Sync states: what they actually mean

Every offline session and queue item moves through these states:

| State     | Meaning                                                                                                             | What the field worker or coordinator should do                                                                          |
| --------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `pending` | A submitted local session is waiting for a due synchronization attempt.                                             | Keep the device available; confirm connectivity and do not resubmit as a new request.                                   |
| `syncing` | KayanOS is uploading files and starting/committing the server session.                                              | Keep the app/device online and avoid deleting files or closing evidence unexpectedly.                                   |
| `failed`  | The last attempt failed; the queue records an error and the next retry time.                                        | Read the error, restore connectivity/authentication/storage as needed, and wait for or trigger the approved retry path. |
| `synced`  | The server session has been created/committed and the local session records the server session ID and receipt time. | Verify the received session and required files in KayanOS before closing the field-work task.                           |

The synchronization worker avoids parallel cycles, waits for the browser to be online, checks due items on an interval, and runs when connectivity returns. Failed attempts use increasing backoff starting at about five seconds and capped at five minutes. These timings are a recovery mechanism, not a promise that a submission will reach the server without review.

## Build an offline inspection form

Use the Citizen Service Request inspection scenario to configure a first version:

1. Create an **Offline** form for the Field Inspection Team while connected.
2. Add only local-friendly fields: request reference, site address, inspection date/time, safety status, a repeatable Observation section, a note, and a file field for photographs.
3. Set fixed select options such as `safe`, `unsafe`, and `follow_up_required`. Do not use an entity-backed option source for a list that must work without the server.
4. Give the Observation section a sensible minimum/maximum count and test one row, multiple rows, an empty optional row, and an unsafe row that requires a note.
5. Add deterministic local expressions only. For example:

```jexl theme={null}
$.safety_status.value == "unsafe" && isNotEmpty($.site_address.value)
```

6. Save and validate the offline structure. Resolve every offline capability warning before distributing the package.
7. Download/prepare the tested version on a controlled device. Record the form version and field-work owner in the visit plan.

Do not use a form expression as a hidden approval gate. The synchronized server-side process must still validate any policy, scope, status transition, or final decision.

## Capabilities intentionally unavailable offline

The offline form builder blocks features that require current server data or an online workflow. This is a safety boundary, not a missing configuration switch.

| Unavailable or restricted capability           | Why it is restricted                                                      | Design alternative                                                                      |
| ---------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Form actions                                   | An action can require an online target, permission check, or side effect. | Submit the inspection, then let a reviewer perform the released next action after sync. |
| Form variables                                 | Variables can depend on context the device cannot reliably obtain.        | Use explicit local fields/defaults that the worker can review.                          |
| Entity selection fields                        | The device cannot rely on live entity records/permissions.                | Capture a reviewed reference or fixed local option; reconcile centrally after sync.     |
| Form-session selection fields                  | Another live session and its context may not be available locally.        | Link/review the resulting sessions after synchronization.                               |
| Entity-backed option sources                   | Options can change and require live access control.                       | Use a deliberately maintained fixed option list where appropriate.                      |
| Public and prefilled links                     | Offline packages are controlled field tools, not public entry points.     | Use a published regular form for public intake.                                         |
| Data/permission-dependent expression functions | They require a service/data path that is not available offline.           | Use local values and deterministic general helpers only.                                |

The offline validator can reject expressions that the general editor suggests. Treat that rejection as the contract for the form type; do not work around it with a different client-side expression.

## Field workflow: from device to received session

### Before departure

* Confirm the worker is signed in and has the intended assignment/scope while online.
* Prepare the current form package and check its version, title, repeatable bounds, required fields, and fixed option values.
* Test the device’s available storage, camera/file selection, battery plan, and time/date settings.
* Open a controlled non-production session, save a draft, attach a non-sensitive test file, submit it, and verify it reaches `synced` before relying on the device for live work.
* Agree how the worker records the Citizen Service Request reference without placing personal data in an unsecured note or filename.

### In the field

1. Start or continue the local session and save meaningful progress as the visit proceeds.
2. Add one Observation instance per actual observation. Keep individual notes and photos attached to the right row/field.
3. Before submission, check mandatory fields, repeatable rows, and file names. A field labelled “optional” may still be required by an unsafe/specific local rule.
4. Submit once when the inspection is complete. Note the local reference/time and retain the device until synchronization is confirmed.

### When connectivity returns

1. Connect the device and keep the app/session available.
2. Watch the state move from `pending` to `syncing`, then to `synced`, or capture the `failed` error and retry timing.
3. The client uploads each pending local file, replaces its local reference in saved state, starts the server session, and commits the saved state.
4. Open the server-side form submission using the resulting session/reference and confirm observation rows, file attachments, timestamps, and required values.
5. Only then let the Decision and Records Unit use the synchronized evidence in a review or status decision.

## Test matrix

| Test                  | Expected result                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Package version       | The intended offline form/version opens on the controlled device.                                                    |
| Draft recovery        | A saved local draft survives an app restart without becoming a duplicate server submission.                          |
| Repeatable inspection | One, several, and boundary-count observation rows keep their local field values.                                     |
| Local file            | A non-sensitive photo/file remains associated with the correct field and uploads on sync.                            |
| No connection         | A submitted session stays `pending` rather than claiming it was centrally received.                                  |
| Interrupted sync      | A failure records `failed`, error text, attempts, and a future retry time; it does not silently discard the session. |
| Reconnected sync      | A due session becomes `synced` and has a server session ID/receipt time.                                             |
| Server verification   | The coordinator can see the expected saved state and uploaded files in the synchronized session.                     |
| Restricted feature    | A blocked online-only feature is rejected by the offline builder/validator.                                          |

## Recover safely from a failed sync

| Symptom                                    | Likely cause                                                                          | Safe response                                                                                                                                                    |
| ------------------------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `failed` with no active session            | The device has no usable sign-in token for the sync request.                          | Re-authenticate through the approved account flow, then retry; do not share credentials or copy a token.                                                         |
| File upload fails                          | Connectivity, storage, file availability, or upload service problem.                  | Preserve the local file/session, restore connectivity/storage, and retry through the queue. Do not delete the file to make the error disappear.                  |
| Start or commit fails                      | The form/version, server validation, or service request could not accept the payload. | Record the error, local submission ID, form/version, time, and non-sensitive screen evidence; have an authorized coordinator inspect the server-side conditions. |
| It stays pending                           | No connectivity yet or retry time is not due.                                         | Keep the device online and allow the worker to run; check the queue state rather than creating a duplicate session.                                              |
| Server session exists but looks incomplete | A file or state reconciliation needs review.                                          | Compare local and server values before resubmitting anything; escalate with the server session ID and local submission reference.                                |
| Device is lost before sync                 | The only copy may be local.                                                           | Follow the organization’s device incident procedure immediately; do not claim the inspection was submitted.                                                      |

## Permissions and data-quality limits

The offline package does not relax normal governance. The member still needs the intended form access when preparing/synchronizing work; the resulting server session is subject to the form, entity, scope, and workflow rules that apply after it arrives. Do not collect sensitive citizen data simply because the device can store it locally. Minimize fields, set a retention/return procedure for devices, and use a reviewed non-production record for testing.

## Related guides

* [Forms, fields, and repeatables](/build/form-fields-and-repeatables)
* [Form submissions](/build/form-submissions)
* [Form builder context](/reference/forms/form-builder-context)
* [Form expressions and lookups](/reference/expressions/forms-and-lookups)
* [Permissions and availability](/reference/permissions-and-availability)
* [Troubleshooting](/reference/troubleshooting)