InnerWeb
Skip to main content

Best practices for an offline queue in a field app

An inspector on a round loses signal in the basement, on the roof and in a hall with steel structure, and the entries from the form must not be lost. Below are practices for designing an offline queue, one that keeps duplicates off the server and shows the user what has already arrived and what is still waiting.

13 days
default clean-up of idempotency records
Source: spec card
4
save states visible to the user
Source: spec card

What an offline queue does in a web app

A web app stores failed requests that modify data (POST, PUT, PATCH) in the browser's IndexedDB queue when there is no network, and replays them when the network returns. The user fills in the form, presses save and can keep working, and the app delivers the data later.

This is the solution for tasks that cannot wait for signal: a round, an inspection, a report, a photo of a defect. The queue also handles files and forms, not only simple text data.

Seven design practices

The practices in the order in which the team usually makes its decisions.

1. Give every request an idempotency key

Every request that modifies data gets an idempotency key in its header. Sending it again after a partial network failure does not create a duplicate on the server, because the server recognises the key.

2. The server remembers only success

The server stores results that ended in success (2xx). After a 4xx or 5xx error the key is released, so the corrected request can be sent again. Idempotency records are cleared after 13 days by default.

3. Show the user the state of the queue

The save state is visible: waiting, synchronising, error, login required. An inspector who sees 'waiting' does not repeat the inspection, and one who sees 'login required' knows what to do after returning to the office.

4. Retry with growing delays

Retry delays grow according to the Fibonacci sequence: 1, 2, 3, 5, 8, 13 s and so on. The sequence grows more gently than doubling, so the device regains sync quickly after signal returns, but does not overload the network during a long outage.

5. Tell a missing network apart from a logic error

No network is a reason to retry. A 4xx response needs the user's attention, because retrying the same request gives the same error. The queue shows such cases as an error, not as endless waiting.

6. Limit what the queue holds

Files and photos take up browser memory. Set a limit on photo size and resolution in the field app before the first inspector fills the queue on a round.

7. Test with the network off and with a broken link

Test scenarios: airplane mode during a save, a link dropped halfway through the upload, a session that expired during offline work. Check whether, after the network returns, the server holds exactly one record, not zero and not two.

Queue retry delays following the Fibonacci sequence

Queue retry delays following the Fibonacci sequenceBar chart: retry delays of 1, 2, 3, 5, 8 and 13 seconds051015sAttempt 1: 1 s1 sAttempt 1Attempt 2: 2 s2 sAttempt 2Attempt 3: 3 s3 sAttempt 3Attempt 4: 5 s5 sAttempt 4Attempt 5: 8 s8 sAttempt 5Attempt 6: 13 s13 sAttempt 6
Source: Fibonacci sequence described in the offline queue feature documentation

Sample figures for planning

Sample calculation: an inspector completes a round of 40 points, and at each one saves a form and a photo. If 8 of those points lie outside coverage, 8 forms and 8 photos wait in the queue and are sent when the network returns. With idempotency keys, retrying the upload does not push the number of records above 40.

Without idempotency keys, the same situation could give two records for some points if the upload is interrupted. This is a sufficient reason for the key to be a standard, not an add-on.

What an offline queue does not do

The queue does not replace a business decision about what is binding. A save made offline carries the device's time, so for important events (a permit, a handover of work) it is worth showing the user that the save is not yet confirmed by the server. For life-threatening alarms, it is better to use a device with its own link, such as a LoRa watch with a gateway.

Checklist

Video

Frequently asked questions

Does the offline queue handle photos and files?

Yes. The queue also handles files and forms, but the size needs to be limited, because browser memory is finite.

What if the server returns a 4xx error?

The key is released and the request moves to an error state. The user corrects the data and sends it again, with no risk of a duplicate.

How long does the server remember idempotency keys?

By default 13 days, after which the records are cleared. A request retried after a longer time is treated as new.

Sources

Let's test offline work on your round

We will show the offline queue in the app and together design test scenarios for rounds in places without signal. We invite you to a conversation.

Let's talk