Offline Mode & Sync
What "Offline-First" Means
The ServCraft mobile app (version 4 and later, the Flutter app that replaced the old 3.x app on the same phones) is built to work without a connection. This means:
- The data a technician needs is stored on the phone
- Changes are saved on the phone first
- When a connection is available, the changes are sent to the server and new data is brought down
- The app looks and behaves the same whether there is a connection or not
The result: technicians in basements, underground car parks, rural properties, or areas with poor coverage can complete their full workflow without interruption.
What Is Stored on the Phone
The phone keeps its own database of the technician's work: jobs, quotes, invoices, purchase orders, queries, appointments, customers and contacts, inventory, forms, comments and messages, plus the list of changes still waiting to be sent. Photos, signatures, sketches and documents are kept as files on the phone until they have been uploaded.
What Works Offline
Everything a technician needs to do their job works offline:
| Feature | Offline? |
|---|---|
| View job details | Yes |
| View appointment details | Yes |
| Start/stop timers | Yes |
| Log parts used | Yes |
| Take photos | Yes |
| Add comments and notes | Yes |
| Complete forms/checklists | Yes |
| Capture customer signature | Yes |
| Change job status | Yes |
| Create a new job | Yes |
| Create customers, contacts and appointments | Yes |
| Create quotes, invoices and purchase orders | Yes |
| Do a stock take | Yes |
| Search inventory items | Yes (searches the copy on the phone) |
What requires a connection:
- Signing in with a password, whether for the first time or after Log Out or Switch User
- The initial sync
- Seeing anything that was created or changed on the web app since the last sync, including a customer or inventory item that has not reached the phone yet
The Sync Queue
Every change made on the phone is added to a sync queue. The queue is a list of changes waiting to be sent to the server.
What goes in the queue:
- Job changes, including status changes, timers and parts used
- New and changed customers, contacts and appointments
- Comments and notes
- Quotes, invoices and purchase orders
- Form submissions
- Stock takes
- Photos, signatures, sketches and documents (the file is uploaded first, then the record is sent)
Viewing the queue: open the gear icon on the Home or More page and choose Sync Queue. The Sync page shows the current status, how many items are pending, a Sync Now button and, under Queue items (tap to expand), the latest 40 entries and every entry that is not completed, each with the record type, the date, its status and any error message. The statuses are Pending, Completed, Error, Awaiting and Permanent failure. Error and Awaiting items show the note "Issue resolution in progress".
The queue survives closing the app. Items still waiting when the app is closed are there when it is opened again, and they also survive an app update and a Log Out.
Errors. When the server refuses an item, the item goes to Error and the phone keeps trying it again at the end of every sync. Items the server has parked behind an errored one show as Awaiting. An item whose file is gone from the phone shows as Permanent failure and is not retried. While anything is in Error or Awaiting, the phone does not download new data, so the technician can end up looking at old jobs until the stuck item is cleared.
Completed items are tidied up automatically. Once an item has synced successfully, it stays visible in the queue for 30 days and is then removed.
How Sync Works
What the technician sees
On Home a small status pill shows Offline, Syncing…, Sync failed (with Retry), Online with a count of changes still to send, or Online with the time of the last sync. On the other pages the same information is a coloured strip at the top: "Syncing...", "Offline", "Sync failed! Tap here for details.", "3 items pending..." or "Last synced" with a time. Tapping the strip starts a sync and opens the Sync page.
When the server refuses an item, the strip turns to "Sync failed! Tap here for details." and the Sync page shows "Your sync queue is in error state, retrying..." in red. Tapping Sync Now with items in error also shows that message at the bottom of the screen. Tapping the pill while the phone is offline shows a message that changes will send when the phone reconnects.
Photos, Signatures and Other Attachments
Photos, signatures, sketches and documents travel through the same sync queue as other changes, but get special handling because they are files:
Large photo queues can slow sync. If a technician has been offline for a full day and took 50 photos, it will take time to upload them all. This is expected and normal.
A file that is gone from the phone. If the phone cannot find the file for a queued attachment, the item is marked Permanent failure and is not retried.
Conflict Resolution
If both the phone and the web app change the same record while the phone was offline, the server decides what to keep when the phone's change arrives.
First-Time Login Sync
The initial sync is the most important sync. When a technician signs in on a phone that has no data yet:
- The app signs in with the server
- All data for that technician is downloaded: jobs, customers, inventory, appointments, forms, permissions
- The data is stored in the phone's local database
Keep the app open during the initial sync. The app covers the screen with a "Syncing your workspace" progress screen that names the record type being downloaded and asks the technician to keep the app open until the sync is complete. The phone's screen is kept awake while this screen is showing. If the sync fails, the screen shows the error with Retry and Log Out buttons.
Big history is trimmed. For businesses with a lot of data (more than 50,000 jobs, quotes, invoices, comments, attachments and similar records between them), the app stops before the first sync and asks "How far back should we sync?". The choices are 3 months, 6 months (the starting choice), 12 months and All data, and the technician taps Start Sync. Jobs, quotes, queries, invoices, purchase orders, appointments, tasks, comments and attachments older than that window are not downloaded. Customers, inventory and other lookup data come down in full. Smaller businesses are not asked and receive everything.
Pulling older history later. If a window was chosen, the Sync page shows "Not finding older entries?" with a Resync Data button under Sync settings. Resync Data asks for confirmation, then returns the phone to the "How far back should we sync?" question so a longer window can be chosen. The button is not shown when All data was chosen or when the question was never asked.
This should happen on Wi-Fi. The initial download can be large, depending on how much data the business has. On mobile data it can be slow, use a lot of the data allowance, and fail partway.
Switching Users on a Device
Log Out and Switch User are different.
Log Out (gear icon, then Log Out) signs the technician out and keeps everything on the phone, including changes still waiting to sync. The login page then shows "Welcome back" with the technician's username filled in and locked, and asks only for the password. The same technician signs in and carries on, and the waiting changes are sent.
Switch User is the link "Not you? Switch user" on that login page. It asks "Switch User?" and warns that all data for that user will be deleted from the device, including any changes that have not been synced. Choosing it clears the phone: the local database, the sync queue, the saved photos and files, and the remembered user. The next person signs in as if on a new phone and does a full initial sync.
Critical: Before a technician hands a device to someone else, make sure the sync queue is empty. Open the gear icon, then Sync Queue. If items are pending, connect and let them sync first. Anything still waiting when Switch User is confirmed is lost.
Updating from the Old App
Version 4 of the app was installed over the old 3.x app on the same phones, so a technician who updates keeps their work. After the update:
- Changes still waiting in the old app's sync queue are kept and are sent by the new app.
- Photos still waiting to upload are found and sent. If the file is gone, the item shows Permanent failure.
- The history window the technician chose in the old app is kept.
- The first time the new app opens, the login page shows "Welcome back" with the technician's username locked in and asks only for the password. Entering it keeps everything on the phone. Another person who tries to sign in on that phone must use "Not you? Switch user", which wipes the phone as described above.
- A technician who goes straight from the old app to a later 4.x release still sees the "Welcome to the new ServCraft" card explaining where things moved.
The update cannot be undone in place. Once the new app has written to the data, the old 3.x app cannot be put back over it without clearing the phone's data.
Troubleshooting Sync Issues
"Changes I made aren't showing in the web app"
- Check whether the phone has a connection (Wi-Fi or mobile data). The status pill or strip says Offline when it does not
- Open the gear icon, then Sync Queue, and look at Queue items. Are any items in Error, Awaiting or Pending?
- Tap Sync Now on the Sync page
- If an item shows an error, the Sync page shows its message in red with "Issue resolution in progress". Note the message. Tap "Send stuck items to support" to send ServCraft a report of every stuck item, and tell support
"The app shows old data, new jobs assigned to me aren't appearing"
- Check the connection
- Open the Sync page. If any item is in Error or Awaiting, the phone is not downloading new data until that item is cleared, so deal with the stuck item first
- Tap Sync Now
- If the job still does not appear, check on the web app that it is assigned to this employee. If the employee was only just given access to another store, the phone downloads that store's history on its next sync. If the technician chose a short history window, an older job will not be on the phone until they use Resync Data
"Photos uploaded but now they're gone"
Photos are stored in the cloud after upload. If a photo is showing as missing:
- Check the job on the web app. The photo should be there
- If it is on the web but not showing on the phone, tap Sync Now to pull it back down
- If it is not on the web either, it may still be in the upload queue. Check Queue items on the Sync page. An attachment marked Permanent failure means the phone lost the file before it could upload, and the technician will need to take or add it again
"The app keeps asking for my password"
"The app is showing data from weeks ago, everything is out of date"
The phone may have been offline for a long time and the sync has fallen far behind. Connect to a strong Wi-Fi connection and leave the app open until the status says Online with a recent "Last synced" time. Check the Sync page for items in Error or Awaiting, which block the download.