The offline model — local data, a durable outbox, visible sync — is explained in How offline-first mobile works. This page is the practical companion: the Sync Status screen where that model becomes something you can read and act on, and the Storage & Database screen behind it. You will rarely need either on a good day; you need them the day a change is flagged, a record seems missing, or the phone runs low on space.
No web screenshot is used here because Sync Status, the durable device outbox and Storage & Database are React Native screens backed by the device's local store. A phone-width web list would show neither queued changes nor offline retention state, and staging those states through retry, discard or delete actions would be destructive. The named native controls below remain the source of truth until demo2 mobile-build captures can be made from pre-seeded, disposable queue states.
Prerequisites
- The xMatix mobile app, signed in, with the first sync complete — see Using xMatix on mobile.
- Nothing else. Everything on this page is available to every user; there are no special permissions involved.
Procedure
Step 1 — Open the Sync Status screen
Open the app drawer, tap Preferences, and under Data & Sync tap Sync status. The row carries a red badge with the number of changes still waiting on your device, so you can see from Preferences whether there is anything to look at. There is a shortcut too: whenever you are offline or a sync is running, a small floating pill appears at the top of the screen — tapping it lands on the same place.
Step 2 — Read the offline data card
The Offline data card lists each record type kept on your device with its record count, its last sync time, and live progress while a download runs. A row that failed turns red with the reason — tap it to read the full server response. For record types your organization has marked as user-adjustable, the row carries Auto, Manual and Off choices, so you can stop syncing something you do not use (an admin-disabled record type cannot be switched back on from the device). The Sync now button at the top pushes your pending changes up and pulls fresh data down in one pass; while the device is low on storage it renames itself to Sync changes, because downloads pause but your outgoing changes still go.
Step 3 — Read the changes queue
The Changes card is the outbox. It splits into two groups:
- Waiting to sync — changes doing fine on their own: Pending (not sent yet), Syncing… (being sent now) and Retrying (a network hiccup; the app retries by itself with a growing wait between attempts). You do not need to do anything here except be online at some point.
- Needs attention — changes that will not proceed without you: Rejected, Conflict and Blocked. A Retry all button re-queues the lot when the underlying cause (say, a permissions fix on the server) has been addressed.
Each row shows what the change is (Create · Order, File upload · Visit and so on), a summary of the values it carries, and — for failed rows — the error and a Ref: code you can give your administrator, which finds the same failure in the server logs.
Step 4 — Fix a rejected change
Rejected means the server refused the change and retrying alone will not help — typically a validation rule, a permission, or a reference to something that no longer exists. Open the row and read the message; field-level validation errors are listed individually. Then either:
- Tap Fix (available for creates and edits) — the record form opens pre-filled with the values from the failed change, you correct the offending field, and save. The correction replaces the original queued change under the same identity, so the server applies it once — no duplicate is created however many times you resubmit.
- Tap Discard if the change should not happen at all. The confirmation is explicit — discarding abandons the queued change and reverts it on your device, and cannot be undone.
Failed changes stay on the device until you do one of these; nothing is dropped silently.
Step 5 — Resolve a conflict or a blocked change
Conflict — flagged as Changed on the server since your edit — means someone else changed the record while your edit was queued. The retry button becomes Keep mine, which resends your version. If the conflict keeps coming back, take the deliberate route: your values are visible in the row's summary, so note what you changed, Discard the queued change, pull down to refresh the record, and re-apply your edit on top of the current server version. That way you decide with both versions in view.
Blocked means the change depends on another queued change that failed — a line item waiting on the creation of its order, for instance. Resolve the parent row first; the blocked rows release automatically once it goes through.
Step 6 — Reset the offline data when the cache looks wrong
Under Maintenance, Reset offline data clears the downloaded data and re-downloads it from the server. It is the right tool when local data looks inconsistent with the web in a way a normal sync does not cure. It is deliberately safe with respect to your work: pending changes are kept and sync as usual — the confirmation dialog tells you how many you have before you commit.
Step 7 — Check the Storage & Database screen
Back in Preferences, Storage & database shows what the offline data actually costs: total size on disk, a per-record-type breakdown, and counts of un-synced edits. Two maintenance actions are safe to run any time: Optimize database reclaims free space (the screen suggests it when worthwhile and says how much it will recover), and the integrity check verifies the local database. The danger zone at the bottom is different in kind: Delete all offline data erases everything on the device including any changes that have not reached the server — the one action on either screen that can cost you queued work. Read its warning as written, and check the Changes card is empty first unless losing the queue is what you intend.
Expected result
The Changes card reaches zero after the device reconnects, no row remains under Needs attention, and the record can be opened from another signed-in device or the web experience with the same saved values. If the queue is not empty, do not repeat the business transaction: open the remaining row, use its status and reference code to choose Fix, Retry, or Discard, and confirm the count falls only after that deliberate action.
Common problems
The queue is not draining. In order: check you are actually online (the floating pill is red with a wifi-off glyph when not); bring the app to the foreground and tap Sync now; and check whether your session has expired — an expired sign-in pauses sending without discarding anything, and the queue resumes the moment you sign in again.
Downloads stopped and the button says "Sync changes". The device is low on storage. Offline downloads pause to avoid making it worse, but your outgoing changes keep sending. Free up space, or use Optimize database, and downloads resume.
A record type never syncs. Check its row on the offline data card. Off or Manual means that is the configured behavior — Manual rows sync when you tap them, Off rows not at all. If the row is missing entirely, the record type is not in your organization's offline scope; that is an administrator setting, not a fault.
Common questions
Does sync run when the app is closed?
Partially. The operating system grants the app periodic background windows — at best roughly hourly, entirely at the OS's discretion — in which it sends pending changes and refreshes data. Treat that as a bonus, not a guarantee: the dependable way to get a day's work up is to open the app with a connection and let the pill or the Sync Status screen confirm the queue is empty.
Can retrying or fixing a change create a duplicate?
No. Every queued change carries its own identity, and a fix or retry resends under the same identity, which the server recognizes and applies once. This is also why an interrupted sync — connection lost mid-send, app killed mid-sync — resumes cleanly rather than double-applying.
What can actually delete my pending changes?
Exactly two things, both deliberate: tapping Discard on an individual change, and Delete all offline data on the Storage & Database screen. Signing out does not delete them, restarting the phone does not, Reset offline data does not, and an expired session only pauses them.
What does "Blocked" mean and why can't I retry it directly?
The change references something that itself has not synced — usually a record created offline whose creation failed. Sending the dependent change first would fail anyway, so the app holds it and points you at the real problem. Fix or discard the parent change; the blocked ones follow automatically.