Full Offline Support

Summary

The Buendia client is meant for low-connectivity, low-power environments, and was designed to mostly work without access to the server. Currently, however, patient forms (encounter form, test results) only work while online. In addition, users and patients cannot be added while offline. This document describes the work that would be necessary to enable these operations while offline.

Enabling Offline Form Entry

Caching Charts

Currently, whenever the user requests a form, the client goes through a multi-step process for fetching the form:

1. Query the server for the list of charts and check that list for a known chart UUID (the PCR form and encounter form UUID's are hardcoded on the client)

2. Check for the existence of that form locally

a. If the form is already present and up-to-date, immediately load FormEntryActivity with a reference to that form

b. If the form is not present (or the form is out-of-date), download it from the server, save it locally, then load FormEntryActivity with a reference to that form

Both of these steps could potentially require a connection to the Buendia server module. Currently, if the module is unavailable, the user will not be allowed to open the chart, as the client has no way of knowing if the local form is available or up-to-date. Even if the user were able to determine this, the chart may not yet be present locally

Solutions

Since the client already knows hardcoded UUID's for the forms it needs, it can just use the hardcoded UUID's and make the assumption that all local forms are up to date. This saves a network call, but results in the possibility of local data not matching a new version of the form on the server. In this case, this data will need to be deleted or somehow migrated to match the new version.

If the forms need to be downloaded from the server, opening the form will still fail. To fix this, the form can be download as part of initial sync, so we can assume that the form is available as long as patients are. This makes initial sync a bit slower but reduces the need for network connectivity later on.

Caching Form Entry

Even if the form can be opened while offline, currently the app does not locally cache form entry. ODK does allow for local caching, however--ODK can save partial form entry for cases in which the user has entered data and is not ready to submit. The application could make use of this, treating a form submitted offline as partial data entry, which would save the form entries locally.

In cases where form entry is stored locally and not sent to the server, the user should be notified very clearly so that there is no surprise when the data is not visible on the server.

Note a very possible corner case: the user could submit an encounter for a patient, return to the form, and submit yet another encounter. The locale cache should allow for this, treating each encounter as separate. In other words, when reloading a form, it should generally not be pre-filled with the previous data.

Replaying Form Entry

If form entry is cached locally, there needs to be a mechanism for periodically replaying the submission when the server is connection is restored. The form entry should remain in cache until the submission is successful, at which point it can be deleted. It is unclear at what interval these should be sent and what, if any, messaging should be given to the user about this process.

Managing Local Data

If a local form entry cache is added, the user should have some visibility into form entries that still need to be sent to the server--if a user has entered 30 test results and no data has been sent to the server, the current user should know, especially if the user has changed since those test results were added. The local patient charts should also display this data, in case the server is unavailable for an extended period of time.

Enabling Offline Patient Creation

Currently, patient creation fails if a new patient is submitted while the server is unavailable. This is okay in the short-term, but may be worth fixing in the long-term. To enable offline patient creation, new patients would need to be cached in the local database when the network request fails, giving the user some notification that the patient will be added later.

When the client subsequently performs a sync (which happens periodically, every 5 min), the SyncAdapter could make requests to the server for each of the patients added locally but not present on the server (we already compare the two sets of data in sync/SyncAdapter#updatePatientData(SyncResult)). It may make sense to change the server to allow for batch creation of patients, or this could be a very slow operation.

Enabling Offline User Creation

Currently, user creation acts like patient creation in that user creation fails if the server is unavailable. In this case, it may make sense to keep this functionality online-only, as it is fairly low-impact. Clinician names are embedded in the encounter and PCR forms, and these are actually prepopulated by the server. If the user is local-only, their name will not be listed under clinicians in the form, so the app will default to Guest User.

If it still makes sense to enable offline user creation, all of the instructions under "Enabling Offline Patient Creation" apply, except that changes would be made in user/UserManager#onUsersSynced(Set<User>) rather than sync/SyncAdapter.