How offline-first mobile works

The xMatix mobile app keeps a copy of your working data on the phone and queues every change you save in an on-device outbox, so you can keep working when the network drops and your changes go up when it returns. There is no separate "offline mode" to switch into. Connectivity is a state the app tracks: when coverage drops in the middle of a visit, you keep using the same screens, and when it comes back, the queue syncs in the background.

This page explains the model: what is on the device, how saves travel, how conflicts are handled and what an administrator controls. The day-to-day screens (Sync status, the changes queue, Storage & database) are covered step by step in Working offline: sync status and recovery.

Overview

Offline working rests on four parts:

• A local copy of data. Record types your administrator lists in the app's offline settings are downloaded to the phone. Form layouts, views, apps and translations are stored there too, so screens open without a network.
• An outbox. Every save is written to the phone first and queued for upload. The queue lives in the app's local database, not in memory.
• Visible state. The app tells you when you are offline, how many changes are waiting, which changes need you, and when each record type last synced.
• Conflict handling. When the server's copy of a record moved while your edit was queued, the app works out whether your edit really clashes before it asks you anything.

Offline working is not all-or-nothing. It is set per record type: some types are kept on the phone and editable offline, some are only readable while connected, and some actions always need a connection.

When to use it

Read this page if you:

• work in places with weak or no coverage and want to know what you can rely on before you leave;
• need to explain to a field team why a record they saved is not yet visible to the office;
• are an administrator deciding which record types to put on phones, for which users, and how much history to keep.

How xMatix handles it

What lives on your device

The app downloads the record types listed on the Offline & Sync tab of your organization's mobile app configuration. Each listed type is one of two classes:

• Master data — accounts, contacts, items, price lists, schemes, checklist templates and similar reference data — is downloaded in full and is never pruned by age.
• Transaction data — orders, cases, leads, visit plans, activities, payments and similar — is kept for a rolling window measured from each record's last update. The shipped configuration keeps 90 days. Older records are pruned from the phone after each sync, except records with changes you have not uploaded yet, which always stay.

Some record types come along because they are related to a listed one — for example, an order's lines with the order. Picklists, form layouts, views and app pages arrive with the app's metadata, not as data, and the last good copy keeps serving when a refresh fails.

A record type that is not listed is not downloaded. You can still open it while connected. Two limits also apply:

• Row cap. If you can see more rows of a record type than the configured maximum (50,000 unless your administrator changes it), the phone does not download that type for you, and it behaves as online only.
• Your access. The phone only ever holds rows your security profile lets you read.

Where screens read from

By default an app is set to Online first: while you are connected, screens ask the server, and the phone's copy is used when you are offline. An administrator can switch an app to Offline first. The phone then answers from its own copy whenever that copy provably holds the whole answer, and goes to the server only for data that is not fully on the device.

While you are offline, anything the phone does not hold is marked rather than shown as empty. You may see Not available offline, or Can't load more while offline at the end of a list.

Saving goes through the outbox

When you save a record of a type that is editable offline, the change and its outbox entry are written to the phone in one step. Online, the queue sends it straight away. Offline, you see Saved offline — will sync when online, and the row is marked Offline until it uploads.

The queue survives closing the app and restarting the phone. A change that was mid-upload when the app stopped is picked up again on the next start. Changes upload in the order you made them. When an offline-created record reaches the server, any later change that refers to it (a line on a new order, for instance) is switched to the record's real identity before it is sent.

Photos, signatures and other files are copied into the app's own storage when you queue them, so the phone's camera roll or file picker clearing its temporary copy does not lose the attachment. The app's copy is removed once the upload succeeds.

Each queued change carries its own identity. The server uses it to recognise a resend of a new record or an action, so a create that is retried after a dropped connection is applied once, not twice. Edits to existing records are protected differently: each one is sent with the version of the record you edited, which is how the server spots a conflict (see below).

What cannot be done offline

• Saving a record type that is not editable offline. If a record type is not on the offline list, or an administrator turned off Editable offline for it, the app refuses to save while you are offline. A new record shows This record can't be saved offline. Reconnect to save. Inline edits and grids show You're offline. This record can only be saved with a connection.
• Server actions. Buttons that run an action on the server (approve, post, convert and similar) need a connection. Offline they show This action requires a connection.
• Any record type at all, when offline caching is switched off on the phone (Preferences → Data & Sync → Offline caching). With caching off, nothing is kept for offline use and nothing can be saved offline.

The state of your changes

Each queued change has one of these statuses. The Changes card on the Sync status screen shows them all.

When you are offline, a line above the tab bar reads Offline · 3 changes waiting (or Offline · changes sync when you're back when the queue is empty). When changes need you, it reads, for example, 2 changes need attention. The last sync time of each record type is shown on the Sync status screen as Synced 5m ago, Synced 2h ago or Not synced yet.

Conflicts are checked field by field

When you edit a record offline and someone changes it on the server before your edit arrives, the server refuses your edit because the record has moved. The app then compares the record field by field:

• If every field you changed still holds either the value you started from or the value you are writing, there is no real clash. Usually the other change was made by automation to fields you never touched. The app moves your edit onto the current server version and sends it again without asking you. Only the fields you edited are written, so the other changes stay.
• If a field you changed now holds a third value, someone else changed it too. That is a real conflict, and the change stops with the status Conflict.

For a conflict, Keep mine resends your values on top of the current server version. Discard drops your change. The app has no side-by-side comparison screen. If you are unsure, note your values from the change's summary, discard it, refresh the record and re-apply your edit.

Long stretches offline

Your local copy stays readable and editable (for offline-editable types) however long you are disconnected, and the queue keeps growing. On reconnection:

• Deleted records are removed from the phone by the normal sync, which brings deletions down along with changes.
• Full refresh. Each record type is also downloaded in full again periodically — about once a month with standard server settings — and whenever the server's data structure, the type's field list or its scope changes. Your unsent changes are kept through a full refresh.
• Lost access. If you lose read access to a whole record type, the phone drops it. Row-level access changes are repaired on every sync for record types with a scope. For record types an administrator marked Recheck access, they are repaired every 15 minutes.

Signing out and session expiry

Your local data and queue are stored per environment, organization, user and app, so they belong to you on this phone.

• When your session expires, uploading pauses. Nothing is discarded, and the queue resumes when you sign in again.
• When you sign out, the session is cleared and the local data and queue stay on the phone. Signing out from the Profile screen with changes still waiting first asks Uploads still waiting, explaining that they stay on this phone and upload after you sign in again here, with Stay signed in and Sign out anyway. Other sign-out buttons, such as the one on the check-in screen, do not ask.
• Only you can upload your queue. Queued changes upload only when you sign in again on the same phone. They do not follow you to another device.

Background sync

The phone's operating system gives the app occasional background windows — at most about once an hour, at the system's discretion. In those windows the app uploads queued changes and refreshes data. Treat this as a bonus. The reliable way to get the day's work up is to open the app with a connection and check that the queue is empty.

Low storage

When the phone has less than about 500 MB free, the app stops downloading offline data and shows Storage almost full — offline sync is disabled until space is freed. Uploading your queued changes carries on, and on the Sync status screen the Sync now button becomes Sync changes.

Prerequisites

• The mobile app installed and signed in. Your security profile must be assigned to an active mobile app configuration. See Using xMatix on mobile.
• A first sync completed while connected. Until a record type has downloaded, it shows Not synced yet and is not available offline.

Business rules

• Only record types listed on the configuration's Offline & Sync tab are downloaded. Unlisted types are online only and cannot be saved offline.
• A listed type is editable offline unless Editable offline is turned off for it. A type set to Off is neither stored nor editable offline.
• Transaction records older than the window (by last update) are pruned after each sync; records with unsent changes are never pruned.
• A type with more rows for the user than the row cap is not downloaded for that user.
• Changes upload in the order they were made. A change that depends on a failed create becomes Blocked.
• A change that fails five times in a row for retryable reasons becomes Rejected.
• An edit refused because the record moved is merged field by field. Only a field changed by someone else to a third value raises a Conflict.
• Server actions always need a connection.
• Only Discard on a change, and Delete all offline data on the Storage & database screen, remove queued changes. Signing out, session expiry, restarting the phone and Reset offline data do not.

Example

A sales representative starts the day in town with full coverage. The app has already synced the accounts, items, price lists and schemes for their beat, and the last 90 days of orders and visits.

1. At the first outlet, in a basement shop with no signal, the line above the tab bar reads Offline · changes sync when you're back. They open the account, which the phone holds, and take an order for 24 cases of an invented product, "Sunvale Mango Drink 200 ml". Saving shows Saved offline — will sync when online, and the line now reads Offline · 1 change waiting.
2. They try to run an action button that posts to the server and see This action requires a connection. They leave it for later.
3. Meanwhile, back at the office, a colleague edits the same account's phone number. The representative had changed only the account's delivery notes, offline.
4. Back on the street, the phone reconnects. The order uploads first, then its lines, each now carrying the order's real identity. The account edit is refused because the account moved, but the delivery notes field was untouched on the server, so the app merges silently and resends. The queue empties without asking anything.
5. They run the server action now that they are online.

Training

Practice exercise

In a sandbox, on a phone signed in to an app whose configuration lists Order as an offline record type:

1. Open Preferences → Data & Sync → Sync status and note the Synced … ago time on the Order row.
2. Turn on airplane mode, create an order for any account, and save it.
3. Check that the app showed Saved offline — will sync when online and that the line above the tab bar counts one change waiting.
4. Still offline, try a server action on any record and note the message.
5. Turn airplane mode off and watch the Changes card reach zero.

Expected result: the order appears on the web with the same values, created once. Step 4 showed This action requires a connection.

Quick reference

• Only record types on the app's Offline & Sync list are on the phone.
• Master data is kept in full; transaction data for a rolling window (90 days as shipped).
• Unsent changes are never pruned and survive app restarts.
• Server actions always need a connection.
• Saved offline — will sync when online means saved on the phone, not on the server.
• Rejected: fix or discard. Conflict: keep mine or discard. Blocked: fix its parent.
• Signing out keeps your queue; it uploads only after you sign in again on the same phone.
• Low storage stops downloads, never uploads.

Permissions

• Using the app. A user receives a mobile app configuration only when their security profile is assigned on that configuration's Profiles tab and the configuration is active.
• What reaches the phone. Offline data never widens access. The phone only holds rows the user's security profile lets them read, and losing read access to a record type removes it from the phone.
• Saving offline. Creating, editing or deleting a record offline still needs the same permission as online. The server checks it on upload, and a refusal shows as Rejected.
• Configuring offline behaviour. Editing mobile app configurations (Setup → Design Studio → Apps → Mobile Apps) needs the same Setup access as managing apps.

Configuration

Administrators shape offline behaviour on the Offline & Sync tab of a mobile app configuration (Setup → Design Studio → Apps → Mobile Apps, open a configuration). Every save raises the configuration's version, and phones pick up the change when they next fetch it — at sign-in, on app switch and when the app returns to the foreground. Unsent changes are always kept. The tab's settings, all described in Configuring the mobile app, are:

On the phone, each user can also switch Offline caching off under Preferences → Data & Sync. When an administrator allows it with User override, users can set a record type to Auto, Manual or Off from the Sync status screen.

Common problems

"This record can't be saved offline. Reconnect to save."

The record type is not editable offline: it is not on the app's offline list, Editable offline is turned off for it, or offline caching is off on the phone. Save it when you are connected. If the team needs it offline, an administrator adds the record type on the Offline & Sync tab.

"This action requires a connection"

Server actions never run offline. Reconnect and run the action again. Your saved field changes are not affected.

A record type shows "Not available offline" or is missing offline

The record type is not on the offline list, or its row count for you is over the row cap, or its scope is Online only. All three are administrator settings. Check the Offline data card on the Sync status screen: a record type with no row there is not kept offline for you.

My edit came back as a Conflict

Someone else changed the same field on the server while your edit was queued. Choose Keep mine to overwrite their value, or Discard and re-apply your edit to the current version.

Downloads stopped and the phone says storage is almost full

Below about 500 MB free space, offline downloads pause, while your queued changes keep uploading. Free up space on the phone, or use Optimize database on the Storage & database screen.

Old orders are no longer on the phone

Transaction records older than the configured window are pruned from the phone; they are still on the server and open normally while you are connected.

Common questions

What happens if I close the app before my changes sync?

Nothing is lost. Queued changes are stored in the app's local database on the phone, not in its running memory. They survive the app being closed, the phone restarting or the battery running out, and a change that was mid-upload is picked up again on the next start. Because each new record carries its own identity, the server applies a resent create once, so closing the app mid-sync does not create duplicates. To be sure the day's work is up, open the app with a connection and check that the Changes card on the Sync status screen is empty.

What if someone edited the same record while I was offline?

The app checks before it bothers you. If the other person changed different fields from the ones you edited — often it was automation stamping a field you never touched — your edit is merged onto the current version and sent without a question. Only when the same field was changed to a different value does your change stop as a Conflict. Then you choose Keep mine, which writes your value over theirs, or Discard, which keeps theirs. Neither happens silently: a conflicted change waits on the phone until you decide.

My session expired while I was offline — is my queued work gone?

No. An expired session only pauses uploading. You can keep reading the records on the phone and keep saving offline-editable records. When you sign in again on the same phone, the queue resumes in the order the changes were made. Signing out also keeps the queue on the phone. Your changes are tied to you on this phone, though: they do not upload if you sign in on a different device, so finish syncing before switching phones.

Why can't my colleague see the record I just created?

Because it has not reached the server yet. A record saved offline exists on your phone as soon as you save it — you see Saved offline — will sync when online and an Offline marker on the row — but colleagues see it only after your queue sends it. Open Sync status and look at the Changes card. If the change is still waiting, get a connection; if it is Rejected or Blocked, fix it there. Once the queue is empty, the record is on the server for everyone with access.

Does the phone always show the latest data when I'm online?

With the default Online first read mode, yes: while you are connected, screens ask the server, and the phone's copy is used only when you are offline. An administrator can set an app to Offline first, which answers from the phone's copy whenever it holds the full answer. That is faster, and the copy is refreshed on every sync. If something looks out of date, tap Sync now on the Sync status screen.

Related topics

• Working offline: sync status and recovery
• Configuring the mobile app
• Monitoring sync failures
• Troubleshooting the mobile app
• Using xMatix on mobile
• Apps, entities and records