Working offline: sync status and recovery

The mobile app's Sync Status and Pending changes screens show what your device holds offline and which of your changes have not reached the server yet. Use them to fix a change the server refused. Storage & database shows how much space the offline data takes. The model behind them (offline data on the device, a queue of outgoing changes, field-by-field conflict checks) is explained in How offline-first mobile works. This page covers the practical side: what each screen shows and what to tap when something needs you.

Overview

Everything you save on the phone goes into a queue of outgoing changes first and is sent to the server from there. You can keep working without a connection, and nothing is lost if the connection drops halfway through. Most days the queue empties by itself and you never open these screens. You need them when:

• a change shows up under Needs attention, because the server refused it, someone else changed the same record, or it depends on a change that failed;
• a record you expect on the phone is missing or looks out of date;
• the phone is running out of space.

When to use it

• The line above the tab bar says Offline · 3 changes waiting and you want to see what is waiting.
• The line says 2 changes need attention.
• Your administrator asks you to fix, retry or discard a change.
• A list on the phone does not match the web, even after a sync.
• You get a low-storage warning, or the sync button reads Sync changes instead of Sync now.

How xMatix handles it

Sending changes. The queue sends changes in the order you made them. A change that depends on an earlier one, such as the lines of an order you created offline, waits for that one to go through. A temporary problem (no response, a time-out, a server error) is retried automatically after 15 seconds, 1 minute, 4 minutes and then 15 minutes. If the fifth attempt also fails, the change stops and is marked Rejected. Waiting while the phone is offline does not count as an attempt. If the server says the document is busy with a background job, the change shows Waiting — document is being processed and retries on its own without using up attempts.

Statuses. The Pending changes screen sorts every queued change into two groups:

Downloading data. The app downloads only the record types your organization has set up for offline use. When you are online, screens still read from the server. The copy on the device is used when you are offline. Downloads run when the app starts, in regular passes while it is open, and in the background when the operating system allows. The first time the app opens with a connection on a new day, it shows a Syncing your data cover while it fetches the changes since your last sync. The cover appears only if the download takes more than a moment. You can tap Skip and keep working while the download continues in the background.

Server-side clean-up. Each change that ends up under Needs attention is also reported to your administrators. An administrator can settle a Rejected or Conflict change from the server, so you don't have to act on it. Your app applies the decision on its next sync and checks for decisions at most every five minutes. A change marked Resolved or Won't Fix is removed from your phone, exactly as if you had tapped Discard. A change marked Retry is sent again. This works only if your security profile can read Mobile Sync Failure records.

Prerequisites

• The xMatix mobile app, signed in, with the first download finished. See Using xMatix on mobile.
• No special permission is needed to open these screens. Whether a change is accepted depends on your normal security profile.

Procedure

Step 1 — Open the sync screens

Open the app drawer, tap Preferences, and look under Data & Sync:

• Sync status opens the Sync Status screen. A badge on the row shows how many changes are still on your device. It is red when at least one of them needs attention.
• Storage & database opens the storage screen (Step 7).

The shortcut is the line that floats above the tab bar. It reads Offline · 2 changes waiting (or Offline · changes sync when you're back) while you have no connection, and 2 changes need attention when changes need you. Tapping it opens Pending changes if changes are queued, and Sync Status otherwise. While a sync runs for more than a moment, a small spinning icon takes its place. You can close the attention line with ×. It comes back when another change needs attention.

Step 2 — Read the Sync Status screen

Sync Status has three parts:

• Changes: one line that summarises the queue, for example 1 needs attention · 3 waiting, or All changes synced. Tap it to open Pending changes (Step 3).
• Offline data: one row per record type kept on the device. Each row shows a short status: Up to date · 1,240 records, 850 records on device (last 90 days), a live Syncing… 1,240 of 5,200 with a progress bar, or Online only when a record type is too large to keep on the phone. While a download pass runs, Downloading offline data… shows its overall progress above the list. A row that failed turns red and ends with tap for details. Tap it to read the full error.
• Maintenance: Reset offline data (Step 6).

The Sync now button in the header sends your queued changes and downloads fresh data in one pass. It is greyed out while you are offline or a sync is already running. When the phone is low on storage it reads Sync changes, because downloads are paused but your changes still go up.

Step 3 — Open Pending changes

Pending changes is the queue itself. It lists Needs attention first, then Waiting to sync, each with a count. When the queue is empty it says Nothing waiting to sync.

Each row shows:

• what the change is, such as Create · Order, Update · Visit or File upload · Visit;
• its status;
• up to three of the values it carries;
• for a change that needs attention: the server's reason (with one line per field the server rejected, such as Name: Required) and a Ref: code. Give your administrator the code. It finds the same failure in the server logs.

The Sync changes button in this screen's header sends the queue. Pull down to refresh the list.

Step 4 — Fix a rejected change

Rejected means the server refused the change and resending it unchanged will not help. The usual causes are a validation rule, a missing permission, or a reference to a record that no longer exists. Read the reason on the row, then choose one of these:

• Fix (creates and updates only). The record form opens with the values from the failed change, and the server's reasons appear under the fields they belong to. Correct the value and save. Your correction replaces the queued change and keeps its identity, so the server applies it once, however often you resubmit.
• Retry. Use this when the cause has been fixed on the server, for example after your administrator corrects a permission.
• Discard. Use this when the change should not happen at all. The confirmation Discard change? warns that this abandons the queued change and reverts it on this device, and that it cannot be undone. A record you created offline disappears from the phone. For an edit, the phone shows the server's version again.

Failed changes stay on the phone until you act on them or an administrator settles them from the server. Nothing is dropped silently.

Step 5 — Resolve a conflict or a blocked change

Conflict (reason Changed on the server since your edit) means someone else changed the same fields while your edit was queued. Edits to different fields are merged automatically and never show as a conflict. For a conflict, the Retry button reads Keep mine. It applies your change on top of the record's current server version, so your values win for the fields you changed.

If you are not sure your values should win, check the values shown on the row and Discard the change. Then open the record online and make your edit again on top of the current version.

Blocked (reason Waiting on a related change that failed) means the change depends on another change that failed, such as order lines waiting for the order itself. Deal with the failed parent first:

• Fix or Retry the parent. When it goes through, the blocked changes are released and sent automatically.
• If you Discard the parent, the blocked changes are not released. They stay under Needs attention. Discard them too, because they have nothing to attach to.

Retry all at the top of Needs attention re-queues every row in the group at once. Use it after a server-side fix that affects several changes. For a conflict, Retry all resends without Keep mine, so the conflict usually comes back. Use Keep mine on each conflict instead.

Step 6 — Reset the offline data

When data on the phone looks wrong in a way a normal sync does not fix, open Sync Status and tap Reset offline data under Maintenance. The confirmation explains that it removes downloaded offline data and downloads it again, and that pending changes are never deleted. If you have queued changes, it also says how many will be kept. After Reset, the app downloads everything again behind the same cover it shows on first use. On a slow connection this can take a while.

Step 7 — Check storage

Preferences → Storage & database shows what the offline data costs:

• Database: size on disk, including Reclaimable free space.
• Record store: Total records, Un-synced edits and a By entity breakdown.
• Projected tables and Sync & queue tables: technical detail your administrator may ask for.

When a lot of space can be reclaimed, an Optimize recommended card appears with Optimize now. Under Maintenance, Optimize database compacts the database file and Run integrity check checks it for damage. Both keep your un-synced edits.

The Danger zone at the bottom holds Delete all offline data. It erases every workspace and app on the phone, including changes that have not reached the server. Those changes are lost for good. Before you confirm Delete everything, make sure Pending changes says Nothing waiting to sync, unless losing the queue is what you intend.

Step 8 — Choose what syncs (when allowed)

Your organization can let you choose how individual record types sync. Those rows on Offline data show Auto, Manual and Off buttons:

• Auto: kept up to date in every sync pass.
• Manual: left out of the regular passes. Choosing Manual downloads the data once, right away.
• Off: not kept on the phone. The confirmation Stop offline sync? warns that the data is removed from this device. Changes you have not synced yet are kept.

A row you changed shows (yours) next to its mode. Reset to app defaults at the bottom of the card restores your organization's settings. Rows without these buttons follow your organization's setting and cannot be changed on the phone.

The Offline caching switch under Preferences → Data & Sync turns offline downloads off for every record type at once. Leave it on unless your administrator tells you otherwise.

Example

A sales representative visits three outlets in an area with no coverage. At the second outlet she creates an order with two lines, and at the third she updates the outlet's phone number. The line above the tab bar reads Offline · 4 changes waiting.

Back in coverage, the line briefly shows the sync icon and then 1 change needs attention. She taps it, and Pending changes opens. Under Needs attention, Create · Order is Rejected. Its reason comes from a validation rule her organization added, saying that a branch is required for this customer, and the row also shows a Ref: code. Below it, the two order lines are Blocked. The phone-number update has already gone through.

She taps Fix. The order form opens with her values and a message under Branch. She picks the branch and saves. The order goes through, the two lines are released and sent, and Pending changes shows Nothing waiting to sync. On the web, the order shows both lines.

Training

Practice exercise

In a sandbox app, with a test user:

1. Turn on flight mode. Edit any field on a record you can change, and create a new record.
2. Check that the line above the tab bar reads Offline · 2 changes waiting, and that Preferences → Sync status shows a badge of 2.
3. Open Pending changes and check that both changes are listed under Waiting to sync as Pending.
4. Turn flight mode off and tap Sync changes.

Expected result: both rows disappear, the screen shows Nothing waiting to sync, and the Sync Status Changes line reads All changes synced. For a second round, ask your trainer for a validation rule that refuses a test value. Repeat with that value, and practise Fix and Discard on the row that turns Rejected.

Quick reference

• Preferences → Data & Sync → Sync status: offline data, Sync now, Reset offline data.
• Changes line or the line above the tab bar: the Pending changes queue.
• Rejected: Fix, Retry or Discard. Conflict: Keep mine or Discard.
• Blocked: fix the parent. Discarding the parent leaves the blocked rows for you to discard.
• Retry all doesn't apply Keep mine to conflicts.
• Reset offline data keeps your queued changes. Delete all offline data does not.
• Sync changes instead of Sync now means low storage: uploads continue, downloads wait.
• Signing out keeps your queued changes for when you sign in again on this phone.

Permissions

• The sync screens are available to every signed-in user.
• Whether a change is accepted depends on your security profile on the server. A change you could save offline can still be refused, and it then becomes Rejected.
• Reports of failed changes are created on the server under your account. Your profile needs permission to create Mobile Sync Failure records for the reports to arrive, and permission to read them for administrator decisions to reach your phone. See Monitoring mobile sync failures.

Configuration

Administrators set up offline behaviour on the Mobile App record, under Offline & Sync. See Configuring the mobile app. Settings there decide:

• which record types are downloaded at all (a record type that is not listed never appears on Offline data);
• whether each record type is downloaded in full or for a recent window, and the row limit above which a record type stays Online only;
• which record types a user may switch between Auto, Manual and Off on the phone, and which are locked;
• which record types can be saved offline. Where saving offline is not allowed, the form says This record can't be saved offline. Reconnect to save.

Phones pick up a changed offline setup the next time they load the app definition, for example after Refresh Metadata in Preferences → Data & Sync. Administrators can follow failed changes, and settle them from the server, in Mobile Sync Failures. See Monitoring mobile sync failures.

Common problems

The queue is not draining

Check, in this order:

1. You are online. The line above the tab bar starts with Offline when you are not.
2. Open Pending changes and tap Sync changes. That sends every Pending row now. A Retrying row keeps its own timer, up to 15 minutes between attempts, and goes when that runs out. The app also sends the queue when the phone reconnects and when you bring the app back to the front.
3. You are still signed in. If the app returned you to the sign-in screen, your queued changes were kept, and they are sent once you sign in again on this phone.

A change is stuck under Needs attention

Read the reason on the row, then use Fix, Retry or Discard (Step 4). If you don't understand the reason, give your administrator the Ref: code. They can also settle the change from the server.

The conflict keeps coming back

You probably used Retry all, which doesn't apply Keep mine. Tap Keep mine on the row itself, or Discard it and make the edit again online.

Downloads stopped and the button says "Sync changes"

The phone has less than about 500 MB free. Offline data shows Offline sync is disabled — storage almost full. Downloads pause, but your changes keep going up. Free up space on the phone. Optimize database can help if it shows reclaimable space. Downloads resume when space is available.

A record type never syncs

Look at its row under Offline data:

• Manual or Off is a choice made on the phone. Switch it to Auto, or tap Reset to app defaults.
• Online only means the record type has more records than the phone keeps offline. It still works whenever you are connected.
• If the row is missing, your organization has not set that record type up for offline use. Ask your administrator.
• If the card says No offline entities are configured for this app, nothing is set up for offline use in this app.

A change disappeared from Pending changes without my doing anything

Either it went through, or your administrator settled it from the server as Resolved or Won't Fix. In the second case the phone removes it exactly as Discard would. Ask your administrator if you are unsure.

Common questions

Does sync run when the app is closed?

Partly. The phone's operating system gives the app occasional background slots, at most about once an hour and entirely at the system's discretion. In those slots the app sends queued changes and refreshes data. Don't rely on them. The dependable way to get a day's work to the server is to open the app with a connection and check that Pending changes says Nothing waiting to sync.

Can retrying or fixing a change create a duplicate?

No. Every queued change carries its own identity. Fix and Retry resend it under the same identity, and the server applies it once. That is also why a sync interrupted by a lost connection or a closed app resumes cleanly. If you save exactly the same edit twice in a row before it syncs, the phone queues it only once.

What can delete my pending changes?

Three things: tapping Discard on a change, Delete all offline data on the storage screen, and an administrator settling a failed change as Resolved or Won't Fix. Signing out, restarting the phone, Reset offline data, Refresh Metadata and switching a record type Off all keep your queued changes.

Why is a Blocked change not sent when its parent is discarded?

A blocked change belongs to a change that failed, such as the lines of an order the server refused. Once the order is discarded, the lines have nothing to attach to, so the app keeps them under Needs attention for you to discard. They are released automatically only when the parent goes through.

Do I have to wait for the "Syncing your data" cover every morning?

No. It appears only for the first sync of the day, and only when that sync takes more than a moment. Tap Skip to start working while the download continues in the background. If some data cannot be downloaded, the cover offers Retry or Continue anyway.

Related topics

• How offline-first mobile works
• Using xMatix on mobile
• Troubleshooting the mobile app
• Monitoring mobile sync failures
• Configuring the mobile app