feature: CCP-4997 Implement Offline Submission Queue and Sync

[gary-jipp]

Description

Type of Change

feat (a new feature)

Checklist

• I have read the CONTRIBUTING doc
• I have checked that unit tests pass locally with my changes
• I have run the npm script lint on the frontend and backend
• I have added tests that prove my fix is effective or that my feature works
• I have added necessary documentation (if appropriate)
• I have approval from the product owner for the contribution in this pull request

Testing Offline Form Submissions

What you need

• A CHEFS account you can log in with.
• Firefox is recommended for testing because its "Work Offline" toggle is a single menu click. Chrome and Edge also have an Offline toggle (inside DevTools > Network); instructions for both browsers are below.
• A form to test against. Create a simple form with an input and maybe a few other componense and ensure "Enable Offline Submission" has been enabled.

Limitations

• Signed-in users only. Anonymous / public forms do not support offline; the toggle is disabled in Form Settings.
• No file upload components. Forms that use a file/attachment component cannot be enabled for offline; the toggle is disabled with a note explaining why.
• Same browser session only. If you close the tab or restart the browser, saved offline entries are still there when you come back, but you need to be signed in again before they will send.
• One device. Entries saved offline on your laptop are not visible on your phone; each device has its own queue.

---

Options for Turning "offline" on and off during testing

Firefox (recommended)

• Go offline: menu bar > File > Work Offline (or the hamburger menu > More Tools > Work Offline).
• Go online: same menu, untick Work Offline.

You do not need to unplug anything. Firefox blocks its own network traffic; the rest of your machine stays online.

Chrome / Edge

Chrome and Edge have an offline toggle inside DevTools:

1. Press F12 (or right-click the page > Inspect) to open DevTools.
2. Go to the Network tab.
3. In the throttling dropdown near the top of the panel (usually reads "No throttling" or "Disabled"), choose Offline.
4. To come back online, set the same dropdown back to No throttling.

Keep DevTools open the whole time you are testing; closing it turns the throttling off. Only network requests made by that browser tab are blocked, so the rest of your machine stays online.

Windows / Mac Network

If you would rather actually cut the network (useful if you want to test what happens when the whole machine loses connectivity):

• Windows: press Win + R, type ncpa.cpl, press Enter. Right-click every active adapter (Wi-Fi, Ethernet) and choose Disable. Right-click > Enable to restore.
• Mac: toggle Wi-Fi off in the menu bar (and unplug Ethernet if you have it plugged in).

Simply turning Wi-Fi off while an Ethernet cable is still plugged in is not enough for the machine-level approach; the browser still thinks it is online. Disable every active adapter.

---

The core scenarios

Please try each of these and note anything unexpected. There is a short checklist under each one.

1. Enable offline for a form (designer)

1. Open a form in the designer.
2. Go to Form Settings.
3. Find "Enable Offline Submission" and tick it. Save the form.
4. Publish the form if it isn't already.

Check:

• The checkbox is enabled and easy to find.
• If your form has a file upload component, the checkbox is disabled with a helper note explaining why.

2. Submit while offline

1. Open the form's submit URL while online and signed in. Wait for the form to render fully.
2. Look at the CHEFS header bar (the blue bar at the top with the BC logo and Logout button). While online you should see an "ONLINE" status button (green cloud icon with a checkmark) sitting near Logout / language.
3. Go offline (Firefox: File > Work Offline).
4. Within a few seconds, the status button in the header changes to say "Offline" with a warning-coloured cloud-with-slash icon.
5. Fill the form in and click Submit.
6. A confirmation dialog appears explaining that the submission will be saved on your device and sent when you are back online. You can optionally type a short note to help you find this submission later. Click Save.
7. You are taken to a confirmation page that says "Submission Saved".

Check:

• The header status button flips from ONLINE to Offline within 20 seconds of going offline.
• Submitting does not produce a red error toast.
• The success page says "Submission Saved" (not the normal green Success screen with a Confirmation ID; that comes later).
• After queuing, a small red number badge appears on the corner of the header status button showing how many submissions are waiting to send.

3. Come back online and watch it sync

1. Still on the "Submission Saved" page (or back on the form), go back online (Firefox: File > Work Offline again to untick it).
2. Within a few seconds, a "You are back online" modal appears listing the submission(s) it is sending. Each row shows a green check mark once sent.
3. When it finishes, close the modal.

Check:

• The sync modal opens on its own; you did not have to click anything.
• Every queued entry gets a green check.
• After closing the modal, if you look up your submissions in CHEFS (Manage > Submissions on the form), your offline entry is there with the data you entered.
• The header status button flips back to ONLINE and the red number badge disappears (nothing left waiting).

4. Queue multiple submissions, then sync them all

1. Go offline.
2. Submit the form 3 or 4 times, using different data each time. Add a note on one of them ("test entry with note") so you can spot it in the list.
3. Click the header status button (or its red number badge). A modal appears listing your queued entries.

Check:

• The red number badge on the header status button matches the number of entries you queued.
• The list shows each entry with either your note (if you typed one) or a default like "Offline Submission for <Form Name>".
• Each row shows the date/time it was queued.
• The submission's internal ID is not shown (it is meant to be a friendly list).
• The list caps its height and scrolls if you queue more than about 5 entries.
• Close the modal with either the X in the title bar or the Close button at the bottom.

4. Go back online. The sync modal appears and processes them in order.

5. Edit a queued submission before it syncs

1. While offline, queue a submission (as in scenario 2).
2. Open the saved-submissions list by clicking the header status button.
3. Click Edit on the entry.
4. The form re-opens with your queued data pre-filled and an info banner across the top of the form saying you are editing a queued offline submission. The banner has a Save button and a Close Edit button.
5. Change something and click Save on the banner.

Check:

• The form opens with the values you originally entered.
• While the edit banner is showing, the normal print / save-draft / submit buttons are disabled (they should look greyed out); the banner's Save is the only way to save.
• The header status button is also disabled while editing (you cannot open the saved-submissions list from inside an edit).
• Saving updates the queued entry (a toast confirms it was updated) and returns you to the normal form view.
• Clicking Close Edit instead exits without modifying the queued entry.
• When you go online, the edited version is what gets sent.

6. Discard a queued submission

1. While offline, queue a submission.
2. Open the pending list.
3. Click Discard on the entry. Confirm the dialog.

Check:

• The entry disappears from the list.
• When you go back online, nothing is sent for that entry (verify by checking Manage > Submissions on the form).

7. Save a draft while offline

Only applies if the form has "Enable Draft" turned on.

1. Go offline on the form.
2. Fill in a couple of fields.
3. Click Save Draft.
4. A confirmation dialog appears explaining the draft will be saved on your device and sent when you are back online. Click Save.
5. Go back online and let the sync modal run.

Check:

• The Save Draft button is available (not disabled) while offline.
• A toast confirms the draft is saved to the device.
• After sync, the draft appears under "View my Drafts" on the form as a normal CHEFS draft.

8. Sign back in when your session has expired

This one is easiest to see if you leave the browser offline for a long time (an hour or so), or come back the next day.

1. Queue at least one submission while offline.
2. Close the tab or the browser.
3. Later, go online, open CHEFS, and navigate to the form (or anywhere in CHEFS).
4. If your login has expired, you will be prompted to sign in again before the queued entries can send. Sign in.

Check:

• You get a clear prompt asking you to sign in, not a silent failure.
• After signing in, the sync modal appears and sends your queued entries.

8. Wait for your login session to expire, then sync

This scenario tests what happens when the queue tries to drain but your CHEFS login has expired in the background. Please do it in one sitting so the timing is deliberate.

How long to wait. Keycloak sessions in CHEFS typically expire after roughly 30 minutes of inactivity (the exact number depends on the environment; if you're unsure, ask a developer for the current session-idle timeout on the environment you're testing). Waiting longer than that is fine; waiting less will not exercise the code path.

1. While online and signed in, open the form.
2. Go offline.
3. Queue at least one submission (a second one with a note is helpful so you can tell them apart in the modals).
4. Stay in the tab. Do not close it, do not refresh, do not click Logout. Just leave it sitting for at least the session-idle timeout (e.g. 30 minutes; longer is safer, an hour is a good target).
5. When you're ready, go back online.

What should happen next:

• Within a few seconds of reconnecting, the queue tries to drain, hits a 401 from the backend, and pops the "Sign in to send saved submissions" modal. It says: "You have N submission(s) saved on this device. Your session has expired; please sign in again to send them." Buttons: Not now and Sign In.

Test the "Not now" path first:

1. Click Not now.

Check:

• The modal closes and does not re-open on its own (it is snoozed until you next act).
• Your queued entries are still in the saved-submissions list (unchanged).
• The header status button still shows the red badge with the pending count.

Now test the real Sign In path:

1. Click the header status button to re-open the saved-submissions list, then close it (this un-snoozes the prompt on the next queue tick). Alternatively wait for the next drain tick.
2. When the reauth modal comes back, click Sign In.
3. You are redirected through the normal CHEFS login. Sign in as the same user who queued the entries.
4. After login, you land back in CHEFS. A "Sign-in successful" confirmation modal appears asking "Send N saved submission(s) now?" with Cancel and Send buttons.
5. Click Send.

Check:

• The Sign In button routes you through Keycloak login (not a silent retry).
• After login, the "Sign-in successful. Send N saved submission(s) now?" confirmation appears; it does not silently drain the queue behind your back.
• Clicking Send opens the normal sync modal (as in scenario 3) and pushes every queued entry through to CHEFS.
• After sync, entries land where you'd expect (Manage > Submissions for submissions, View my Drafts for drafts).
• Clicking Cancel on the confirmation leaves the queue untouched and the badge count still visible; the drain does not run.

Bonus check (different user):

• If you sign back in as a different user (a colleague, or a second test account), the queued entries do not sync silently under the wrong identity. The saved-submissions list should either still show them (locked to the original submitter) or surface a clear "queued by another account on this device" message when you try to send.

9. Log out attempt while offline

1. Go offline.
2. Try to click your account menu > Logout.

Check:

• Logout is disabled or shows a hint like "Reconnect to log out" (we intentionally block logout while offline so you don't lose access to your queued entries).

10. Start a new offline submission from the success page

1. While offline, submit the form (as in scenario 2). You land on the "Submission Saved" page.
2. Click Return to Form.

Check:

• The form re-opens blank, ready for another entry.
• The red number badge on the header status button still reflects everything you have queued so far.

---

Things to look out for

While running the scenarios, please flag anything like:

• The header status button taking a very long time to flip to Offline (more than about 30 seconds after you go offline), or not flipping at all.
• The header status button still showing Offline after you are back online for more than about 30 seconds.
• Red error toasts on the offline path (queuing, editing, discarding, syncing).
• The "This service is temporarily unavailable" popup appearing while offline. On offline-enabled forms this should be suppressed; the Offline header button is what you should see instead.
• Sync modal getting stuck (spinner never finishes, or a row never turns green or red).
• Data mismatch: what you typed while offline is not what appears in Manage > Submissions after sync.
• Anything you found confusing about the wording, button labels, or where things are placed.

---

Testing Offline Form Submissions

What you need

• A CHEFS account you can sign in with.
• Firefox recommended for quick offline toggling. Chrome / Edge also work (instructions below).
• A form with "Enable Offline Submission" ticked in Form Settings, published.

Limitations

• Signed-in users only (public forms don't support offline).
• No file-upload components (toggle is disabled with a note if the form has one).
• Same browser session only; queue is per-device.

---

Toggling offline

Firefox: menu > File > Work Offline (untick to go back online).

Chrome / Edge: F12 > Network tab > throttling dropdown > Offline. Keep DevTools open! Set back to No throttling to go online.

Cut the machine's network (harder test): Windows Win+R > ncpa.cpl > right-click each active adapter > Disable. Enable to restore. Mac: turn Wi-Fi off and unplug Ethernet.

---

Scenarios

1. Enable offline on a form

1. Open the form in the designer > Form Settings > tick "Enable Offline Submission" > Save > Publish.

Check:

• Checkbox is easy to find.
• If the form has a file-upload component, the checkbox is disabled with a helper note.

2. Submit while offline

1. Open the submit URL online. Wait for it to render.
2. Header shows an "ONLINE" button (green cloud).
3. Go offline; within ~20s the header button flips to "Offline" (warning cloud-with-slash).
4. Fill the form and click Submit.
5. Confirmation dialog appears (optional note field). Click Save.

Check:

• Success toast appears; no red error.
• The page reloads into a fresh, empty form (ready for another entry).
• A red number badge appears on the header status button showing how many are waiting.

3. Come back online and watch it sync

1. Go back online.
2. Within a few seconds a "You are back online" modal opens listing the sending submissions; rows get a green check as they succeed.
3. Close when done.

Check:

• Sync modal opens on its own.
• Every entry gets a green check.
• Entries appear in Manage > Submissions on the form.
• Header button returns to ONLINE; badge disappears.

4. Queue multiple, then sync all

1. Offline. Submit 3-4 times with different data; add a note on one.
2. Click the header status button to open the queued list.

Check:

• Badge count matches queued count.
• Each row shows the note (if typed) or a default like "Offline Submission for <Form Name>".
• Each row shows the saved date/time.
• The submission UUID is not shown.
• List caps its height and scrolls past ~5 entries.
• Modal closes via title-bar X or bottom Close.

3. Go back online; sync modal processes them in order.

5. Edit a queued submission before it syncs

1. Offline. Queue a submission.
2. Open the queued list from the header button.
3. Click Edit on the entry. Form reopens pre-filled with an info banner reading "Editing a queued offline submission. Sync is paused while editing." with Save and Close Edit buttons (standard blue primary / outlined style).
4. Change something and click Save.

Check:

• Form opens with your original values.
• The normal submit / save-draft buttons and the header status button are disabled while the banner is showing.
• Save toasts an update confirmation.
• Close Edit exits without changing the queued entry.
• After going online, the edited version is what gets sent.

5a. Sync while editing is blocked

1. Offline. Queue at least one submission.
2. Open the queued list, click Edit on any entry.
3. While in the edit banner, go online.

Check:

• An info toast appears: "Saved offline submissions will not be sent while you are editing a queued entry. Sync will resume when you close the editor."
• The sync modal does not open; no entry is sent.
• The info toast does not nag repeatedly (only appears once per edit session).
• Click Save or Close Edit. The sync modal opens immediately and drains the queue.

6. Discard a queued submission

1. Offline. Queue a submission.
2. Open the pending list. Click Discard. Confirm.

Check:

• Entry disappears.
• Nothing is sent for it when you go back online.

7. Save a draft while offline

Only if the form has "Enable Draft" turned on.

1. Offline. Fill in a couple of fields. Click Save Draft.
2. Confirmation dialog with an optional note. Click Save.
3. Go back online; let the sync modal run.

Check:

• Save Draft is available (not disabled) while offline.
• Toast confirms the draft was saved to the device.
• Page reloads into a fresh blank form.
• After sync, the draft shows under "View my Drafts" on the form.

8. Sign back in after session expiry

Keycloak sessions expire after roughly 30 min idle (varies by environment; ask a dev if unsure).

1. Online + signed in, open the form.
2. Offline. Queue at least one submission (adding a note helps).
3. Stay in the tab. Leave it for at least the session-idle timeout (an hour is safer).
4. Go back online.

Expected: within a few seconds the queue tries to drain, hits 401, and the "Sign in to send saved submissions" modal appears with Not now / Sign In.

Test Not now:

• Modal closes and doesn't re-open on its own.
• Queue and badge count unchanged.

Test Sign In:

1. Click the header status button to reopen the list, then close it (un-snoozes the prompt), or wait for the next tick.
2. When the modal re-appears, click Sign In. Sign in as the same user.
3. Back in CHEFS, a "Sign-in successful. Send N saved submission(s) now?" confirmation appears with Cancel / Send.

• Sign In routes through Keycloak (not a silent retry).
• The confirmation appears; it does not silently drain.
• Send opens the sync modal and pushes everything through.
• Submissions land in Manage > Submissions; drafts in View my Drafts.
• Cancel leaves the queue untouched.

9. Logout blocked while offline

1. Offline. Try the Logout button.

Check:

• Logout is disabled or hints "Reconnect to log out" (block is intentional so you don't lose access to queued entries).

---

Things to flag

• Header button doesn't flip to Offline within ~30 s of going offline, or doesn't flip back to ONLINE within ~30 s of coming online.
• Red error toasts on any offline path (queue, edit, discard, sync).
• Sync modal getting stuck (spinner never resolves; rows stay grey).
• Data mismatch between what you typed and what shows up in Manage > Submissions.
• Confusing wording, labels, or placement.

[github-actions]

Coverage Report (Application)

Totals
Statements:	78.61% ( 10065 / 12803 )
Methods:	77.25% ( 1056 / 1367 )
Lines:	81.41% ( 6173 / 7583 )
Branches:	73.6% ( 2836 / 3853 )

[github-actions]

Coverage Report (Frontend)

Totals
Statements:	67.94% ( 11213 / 16504 )
Methods:	61.8% ( 1964 / 3178 )
Lines:	73.43% ( 6235 / 8491 )
Branches:	62.34% ( 3014 / 4835 )

[github-actions]

Coverage Report (Application)

Lines	Statements	Branches	Functions
	80.96% (6476/7999)	73.76% (2857/3873)	77.31% (1060/1371)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

Release b5de628 deployed at https://chefs-dev.apps.silver.devops.gov.bc.ca/pr-1916