From 1f6c397894f022201f7c3daa29c41f79ab0df2e5 Mon Sep 17 00:00:00 2001 From: Aleksei Serednev <161342151+alex-serednev@users.noreply.github.com> Date: Thu, 26 Feb 2026 01:30:49 +0100 Subject: [PATCH 1/3] Update README.md (Offline mode in renderer as a web component) The README.md file has been reviewed and slightly improved from QA side. Reproduced the scenario, added missing steps, links and data. --- .../README.md | 59 ++++++++++++++++--- 1 file changed, 51 insertions(+), 8 deletions(-) diff --git a/aidbox-forms/aidbox-forms-renderer-offline-mode/README.md b/aidbox-forms/aidbox-forms-renderer-offline-mode/README.md index d5ab8598..e2c6f983 100644 --- a/aidbox-forms/aidbox-forms-renderer-offline-mode/README.md +++ b/aidbox-forms/aidbox-forms-renderer-offline-mode/README.md @@ -1,6 +1,17 @@ # aidbox-forms-renderer-offline-mode -Example of using the Aidbox Forms Renderer web component with offline support via request interception (`enable-fetch-proxy` + `onFetch`). +## Overview + +### What this example is +This is a minimal, single-page demo that shows how to render and fill Aidbox Forms with offline support using the web component and a custom fetch interceptor (`enable-fetch-proxy` + `onFetch`). + +### Who it’s for +Teams building caregiver apps where a form can be opened and filled without internet, and then synced to Aidbox when connectivity returns. + +### Offline behavior +Previously loaded forms can be opened from the local cache +Changes are autosaved locally while offline +Save and submit requests are queued and synchronized when connectivity is restored ## How it works @@ -66,9 +77,14 @@ When the interceptor returns `null`, the renderer handles the request itself (us | `offline-pending-changed` | Pending ops queue updated | ## Prerequisites - -- An Aidbox instance with FHIR resources loaded (Patient, Questionnaires, and pre-created QuestionnaireResponses) -- A JWT token with access to the FHIR and SDC APIs +- An Aidbox instance is running localy (e.g. at `http://localhost:8081`). +- FHIR resources (Patient, Questionnaires, and pre-created QuestionnaireResponses) are added to the Aidbox instance +- A JWT token with access to the FHIR and SDC APIs is created (see [Aidbox Client Credentials documentation](https://www.health-samurai.io/docs/aidbox/tutorials/security-access-control-tutorials/client-credentials-grant): + Go to /ui/console#/iam/sandbox/client. + Check the JWT checkbox. + Specify the Client ID and Client Secret. + In the sandbox console, execute the API requests by clicking Run for each call sequentially. + Copy the JWT from the Access token field. - QuestionnaireResponses must be created upfront on the server with: - `status: in-progress` - `questionnaire` reference pointing to a Questionnaire canonical URL @@ -80,19 +96,20 @@ When the interceptor returns `null`, the renderer handles the request itself (us 2. Set `AIDBOX_BASE_URL` to your Aidbox instance URL (e.g. `http://localhost:8081`) 3. Set `AIDBOX_TOKEN` to a valid JWT token 4. Set `PATIENT_ID` to the patient whose assigned forms should be loaded -5. Load the fixture data into Aidbox: +5. Replace `[AIDBOX_BASE_URL]` with your Aidbox instance URL in link to `renderer-webcomponent.js` (example: `http://localhost:8081/static/aidbox-forms-renderer-webcomponent.js`) +6. Load the fixture data into Aidbox: ```bash ./fixtures/load-fixtures.sh http://localhost:8081 basic:secret ``` -6. Serve `index.html` via any HTTP server (e.g. `npx serve .`) and open in a browser +7. Serve `index.html` via any HTTP server (e.g. `npx serve .`) and open generated link in a browser (e.g. `http://localhost:3000`) ## Usage 1. **First load (online)** — the app fetches assigned QuestionnaireResponses and their Questionnaires, caches them in `localStorage` -2. **Select a form** — click on a form in the sidebar; status shows "in-progress" or "completed" +2. **Select a form in left panel** — click on a form in the sidebar; status shows "in-progress" or "completed" 3. **Fill out forms** — changes auto-save to both `localStorage` and the server 4. **Submit a form** — status changes to "completed" in the sidebar -5. **Go offline** (e.g. DevTools Network → Offline) — forms render from cache; saves are queued +5. **Go offline** (e.g. DevTools Network → Offline) — forms render from cache; saves and submits are stored locally and added to a pending queue. 6. **Come back online** — pending changes sync automatically The header status bar shows online/offline state, pending change count, and sync progress. @@ -110,3 +127,29 @@ The header status bar shows online/offline state, pending change count, and sync The `onFetch` callback is set as a JS property via the `ref` callback. See the [Aidbox Forms documentation](https://docs.aidbox.app/modules/aidbox-forms/aidbox-ui-builder-alpha/embedding-renderer) for the full list of attributes. + +### Limitations & data safety notes +1. Local-only storage: this demo stores cached data and pending operations in localStorage on the current device/browser. +2. Multiple devices: changes made on one device are not shared with another device. Only the first successful submission will be accepted — avoid filling the same form on multiple devices. +3. Clearing browser data: if the user clears site data (history/storage) or uses private/incognito mode, offline drafts and cached forms may be lost. + +### Troubleshooting + +1. I don’t see any forms in the sidebar: + - Confirm fixtures are loaded and the patient has assigned QuestionnaireResponses. + - Confirm PATIENT_ID matches the subject.reference in those QuestionnaireResponses. + - Confirm your JWT token has permissions to read QuestionnaireResponses and Questionnaires. + - Confirm you didn't include "Bearer" to the name of the token (`Bearer `). +2. The form works online but not offline + - Make sure you opened the page online at least once before going offline. + - Open the browser devtools and check that cached resources exist in localStorage. + - Submission requires connectivity; go back online and click Submit again (or wait for auto-sync). +3. The ./fixtures/load-fixtures.sh http://localhost:8081 basic:secret command stalls + - Verify the client_id and the client secret in basic:secret are correct. + - Verify the Aidbox base URL is correct and reachable (e.g. `http://localhost:8081`). + - Ensure you run the script from the correct working directory — the one that contains `index.html` (so relative paths used by the script resolve correctly). +4. The renderer doesn't load + - Ensure the Aidbox instance URL is correctly specified in `index.html` (line 9) and points to the renderer bundle (e.g. `http://localhost:8081/static/aidbox-forms-renderer-webcomponent.js`) + - Validate the URL format: + It should be the full absolute URL with the correct scheme (http) and port. + Make sure that the link to the renderer bundle contains the correct http type. From b8aa03e124739b921d4e46fcddf589aff45899ff Mon Sep 17 00:00:00 2001 From: Aleksei Serednev <161342151+alex-serednev@users.noreply.github.com> Date: Thu, 26 Feb 2026 12:18:12 +0100 Subject: [PATCH 2/3] [#6845] Update bundle.json Remove unnecessary item elements with empty arrays that failed FHIR validation --- .../fixtures/bundle.json | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/aidbox-forms/aidbox-forms-renderer-offline-mode/fixtures/bundle.json b/aidbox-forms/aidbox-forms-renderer-offline-mode/fixtures/bundle.json index 92899db9..1cd33135 100644 --- a/aidbox-forms/aidbox-forms-renderer-offline-mode/fixtures/bundle.json +++ b/aidbox-forms/aidbox-forms-renderer-offline-mode/fixtures/bundle.json @@ -181,8 +181,7 @@ "subject": { "reference": "Patient/pt-1" }, - "authored": "2026-02-20T10:00:00Z", - "item": [] + "authored": "2026-02-20T10:00:00Z" }, "request": { "method": "PUT", @@ -198,8 +197,7 @@ "subject": { "reference": "Patient/pt-1" }, - "authored": "2026-02-20T10:05:00Z", - "item": [] + "authored": "2026-02-20T10:05:00Z" }, "request": { "method": "PUT", @@ -215,8 +213,7 @@ "subject": { "reference": "Patient/pt-1" }, - "authored": "2026-02-20T10:10:00Z", - "item": [] + "authored": "2026-02-20T10:10:00Z" }, "request": { "method": "PUT", From af36cca8f9ffce14132bde2be9bc33c8d4afde88 Mon Sep 17 00:00:00 2001 From: Aleksei Serednev <161342151+alex-serednev@users.noreply.github.com> Date: Thu, 26 Feb 2026 12:40:17 +0100 Subject: [PATCH 3/3] Update README.md [#6845] Changed basic:secret to client:secret, added explanation of client:secret concept, merged 2 interrelated setup steps into one --- .../README.md | 29 +++++++++---------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/aidbox-forms/aidbox-forms-renderer-offline-mode/README.md b/aidbox-forms/aidbox-forms-renderer-offline-mode/README.md index e2c6f983..256b9144 100644 --- a/aidbox-forms/aidbox-forms-renderer-offline-mode/README.md +++ b/aidbox-forms/aidbox-forms-renderer-offline-mode/README.md @@ -80,28 +80,27 @@ When the interceptor returns `null`, the renderer handles the request itself (us - An Aidbox instance is running localy (e.g. at `http://localhost:8081`). - FHIR resources (Patient, Questionnaires, and pre-created QuestionnaireResponses) are added to the Aidbox instance - A JWT token with access to the FHIR and SDC APIs is created (see [Aidbox Client Credentials documentation](https://www.health-samurai.io/docs/aidbox/tutorials/security-access-control-tutorials/client-credentials-grant): - Go to /ui/console#/iam/sandbox/client. - Check the JWT checkbox. - Specify the Client ID and Client Secret. - In the sandbox console, execute the API requests by clicking Run for each call sequentially. - Copy the JWT from the Access token field. + - Go to /ui/console#/iam/sandbox/client. + - Check the JWT checkbox. + - Specify the client id and client secret. The default credentials are `client_id=basic`, `secret=secret` (you may replace them with any other valid values. Throughout the documentation, this pair is referred to as client:secret. Use the values you provided in the request) + - In the sandbox console, execute the API requests by clicking Run for each call sequentially. + - Copy the JWT from the Access token field. - QuestionnaireResponses must be created upfront on the server with: - - `status: in-progress` - - `questionnaire` reference pointing to a Questionnaire canonical URL - - `subject` reference pointing to the patient (e.g. `Patient/pt-1`) + - `status: in-progress` + - `questionnaire` reference pointing to a Questionnaire canonical URL + - `subject` reference pointing to the patient (e.g. `Patient/pt-1`) ## Setup 1. Open `index.html` in a text editor -2. Set `AIDBOX_BASE_URL` to your Aidbox instance URL (e.g. `http://localhost:8081`) +2. Set `AIDBOX_BASE_URL` to your Aidbox instance URL (e.g. `http://localhost:8081`) and adjust `renderer-webcomponent.js` link on line 9 (example: `http://localhost:8081/static/aidbox-forms-renderer-webcomponent.js`) 3. Set `AIDBOX_TOKEN` to a valid JWT token 4. Set `PATIENT_ID` to the patient whose assigned forms should be loaded -5. Replace `[AIDBOX_BASE_URL]` with your Aidbox instance URL in link to `renderer-webcomponent.js` (example: `http://localhost:8081/static/aidbox-forms-renderer-webcomponent.js`) -6. Load the fixture data into Aidbox: +5. Load the fixture data into Aidbox: ```bash - ./fixtures/load-fixtures.sh http://localhost:8081 basic:secret + ./fixtures/load-fixtures.sh http://localhost:8081 client:secret ``` -7. Serve `index.html` via any HTTP server (e.g. `npx serve .`) and open generated link in a browser (e.g. `http://localhost:3000`) +6. Serve `index.html` via any HTTP server (e.g. `npx serve .`) and open generated link in a browser (e.g. `http://localhost:3000`) ## Usage @@ -144,8 +143,8 @@ See the [Aidbox Forms documentation](https://docs.aidbox.app/modules/aidbox-form - Make sure you opened the page online at least once before going offline. - Open the browser devtools and check that cached resources exist in localStorage. - Submission requires connectivity; go back online and click Submit again (or wait for auto-sync). -3. The ./fixtures/load-fixtures.sh http://localhost:8081 basic:secret command stalls - - Verify the client_id and the client secret in basic:secret are correct. +3. The ./fixtures/load-fixtures.sh http://localhost:8081 client:secret command stalls + - Verify the client_id and the client secret in client:secret are correct. - Verify the Aidbox base URL is correct and reachable (e.g. `http://localhost:8081`). - Ensure you run the script from the correct working directory — the one that contains `index.html` (so relative paths used by the script resolve correctly). 4. The renderer doesn't load