Monitoring mobile sync failures

A Mobile Sync Failure is a report that the xMatix mobile app files on the server when a change queued on a device fails for good, so that you can see what is failing across the whole field team without waiting for someone to call. When a queued change fails like this, the device does two things. It flags the change to the user under Needs attention on their Pending changes screen (see Working offline). The change stays there until the user fixes, retries or discards it, or until you settle it from the server. The device also files the report described on this page. The report is sent through the same store-and-forward queue as every other change, so a failure that happens without coverage still reaches you once the device reconnects.

Overview

Each report records what the device tried to write, the server's answer, how often it tried, and which device, user and app version were involved. You read the reports, fix whatever is wrong on the server side (a rule, a permission, a setting), tell the user what to do on their device, and track your progress with Resolution Status.

The failed change itself stays on the device. You can either ask the user to fix, retry or discard it there, or settle it from the server with Resolution Status. The device checks for your decision on its next sync and applies it:

• Retry: the device sends the change again. For a conflict, the user's values win, as if they had tapped Keep mine. The device then sets the report to In Progress.
• Resolved or Won't Fix: the device removes the change, exactly as if the user had tapped Discard.
• Open and In Progress change nothing on the device.

When to use it

• Routine monitoring. Check the list or the Tenant Adoption dashboard regularly. A healthy field team files no reports at all.
• After a user reports a stuck change. Find their report to see the exact error and payload without needing their phone.
• After a configuration change. A new validation, required field or permission change that devices cannot check offline shows up here first, as many reports for the same record type.
• After a mobile app release. Group the reports by App Version to see whether a failure is limited to one build.

How xMatix handles it

The device sends each queued change and sorts every failure by the server's answer:

Other behaviour to know:

• One report per failed attempt. The same attempt is never reported twice. If the user fixes and resubmits a change and it fails again, you get a second report.
• Dependent changes are not reported separately. When a change fails, later changes that depend on it (for example the lines of an order whose creation was refused) are held on the device as Blocked. Only the first failure is reported.
• A failed report is not reported again. The report is itself a create, so the user's security profile must allow creating Mobile Sync Failure records. If it doesn't, the report is refused and nothing reaches you (see Permissions).
• Long text is cut off. Error Message and Payload keep the first 4000 characters.
• Times are UTC. Occurred (UTC) and Last Attempt (UTC) are stored and shown in UTC, not in your time zone.
• Nothing cleans up reports. Records stay until someone deletes them.
• Devices read decisions back. While a device has changes that are Rejected or in Conflict, it asks the server for its own reports marked Retry, Resolved or Won't Fix, at most every five minutes. It matches each report to its change by record type, operation, record and the time the change was queued. A decision on a report whose change the user has already dealt with does nothing. A device whose user cannot read Mobile Sync Failure records never sees the decisions.

Prerequisites

• A security profile that can read Mobile Sync Failure records. In the standard profiles that is System Admin, Standard User and Sales Executive.
• Access to the app that hosts the list. In the standard setup that is the Field Sales app.
• For the fix itself, the setup rights for whatever caused the failure (business rules, security profiles, settings).

Procedure

Step 1 — Open the failure list

In the Field Sales app, open Settings and select Mobile Sync Failures in the Diagnostics group. The list opens on the All Mobile Sync Failures view, with these columns: Name, Source Entity, Operation, Failure Reason, Resolution Status, Device, Attempt Count, Last Attempt (UTC), Created By and Created On.

An empty list means no report is recorded. It does not show changes that are still waiting or retrying on devices: those exist only on the phones, on each user's Pending changes screen.

If your administrator placed the list in another app, open it from that app's navigation instead.

Step 2 — Find the reports that need work

Filter on Resolution Status to see the Open reports. Sort on Last Attempt (UTC) or Created On to see the newest first. In the standard setup you can filter on Source Entity, Operation, Failure Reason, Resolution Status and Device, and sort on Name, Source Entity, Device, Last Attempt (UTC) and Created On. Before opening single records, look for patterns:

• The same Source Entity from many users points to a rule, a required field or a permission problem on the server.
• Many reports from one Device point to one phone or one user.
• Reports from only one app version point to a build that has not been updated.
• An Attempt Count of 1 means the server refused the change straight away. An Attempt Count of 5 means temporary errors used up every retry.

Step 3 — Open a report and read the evidence

Select the report's name. The record page header reads Error Log and shows Source Entity and Device at the top. The page has five sections:

• Error Details: Failure Reason, Error Message, Payload, Operation, User and Owner.
• Source & Context: Source Entity, Source Record Id, Device and App Version.
• Attempts & Timing: Attempt Count, Occurred (UTC) and Last Attempt (UTC).
• Resolution: Resolution Status, Resolved (UTC) and Resolution Notes.
• Audit Trail: Created By, Created Date, Modified By and Updated On.

Read Error Message for the rule or reason the server gave. Then read Payload to see exactly what the device tried to write. Together they usually show the cause.

Step 4 — Decide what kind of failure it is

Start with Failure Reason:

• Rejected, Attempt Count 1. The server refused the change. Common causes are a validation or business rule the user could not check offline, a missing permission, or a reference to a record that was deleted or renamed. Fix the cause on the server if there is one. The rule might be unsuitable for offline work, or a profile might be missing a permission.
• Rejected, Attempt Count 5. The server kept failing or timing out. Look for server-side problems around Last Attempt (UTC). The change itself may be valid: the user can retry it.
• Conflict. Someone else changed or removed the record while the device's edit was queued. There is rarely a server-side fix. The user decides on their device whether to keep their version or discard it. Repeated conflicts on the same records suggest that two roles are editing records that only one role should own.

Step 5 — Tell the user what to do on their device

The change is still waiting on the user's device under Needs attention. If you can settle it yourself, go to Step 6. Otherwise, depending on your finding, ask them to:

• tap Fix, correct the value the error names, and save;
• tap Retry (or Retry all) once you have fixed the server-side cause;
• tap Keep mine or Discard for a conflict.

Working offline describes these actions. If the change is fixed and fails again, a new report arrives.

Step 6 — Settle the change and record the outcome

On the report, set Resolution Status and save:

• In Progress while you work on it. Nothing happens on the device.
• Retry once you have fixed the cause on the server. The device sends the change again on its next sync. For a conflict, the user's values overwrite the server's. If it fails again, a new report arrives and this one stays In Progress.
• Resolved when the change is no longer needed because you fixed the data on the server, or because it already reached the server another way (for example, a later attempt went through).
• Won't Fix when the change should not happen.

Resolved and Won't Fix remove the change from the device, including a record the user created offline that never reached the server. That data is then gone, apart from the copy in Payload. If the user should keep their change, use Retry or ask them to act on the device instead.

In the standard metadata, the Resolution Status values are inactive, so the list offers no choices until you activate them (see Configuration). Only change Resolution Status. The other fields are the device's evidence and can be edited, but don't change them. Leave Resolved (UTC) and Resolution Notes empty: they are on the form, but this record type cannot store them (see Common problems).

Step 7 — Watch the trend on the dashboard

The standard Tenant Adoption dashboard, in the System Admin/Data Studio folder, has six tiles built on these reports:

• Mobile Sync Failures: the total count.
• Unresolved Sync Failures: reports whose status is not Resolved. Won't Fix reports still count here.
• Mobile Sync Failures by Day: reports by the day the change was first queued.
• Sync Failures · Entity → Reason: reports by record type and failure reason.
• Sync Failures by Resolution: reports by Resolution Status.
• Sync Failures · Operation × Reason: reports by operation and failure reason.

Step 8 — Delete old reports

Nothing deletes reports automatically. When you no longer need a closed report, open it and use Delete in the page header. Deleting a report has no effect on any device.

Fields

Business rules

• Devices create reports, and update one only to move it from Retry to In Progress after re-sending the change.
• A report is filed only for the failed change itself, never for the dependent changes held behind it, and never for a failed report.
• Retry, Resolved and Won't Fix act on the device that filed the report, on its next sync. Retry also releases the changes held behind the failed one. Open and In Progress have no effect. Deleting a report has no effect on any device.
• Unresolved Sync Failures on the dashboard counts every status except Resolved.
• Mobile Sync Failure records can't be included in a sync profile, so integrations never import or export them.

Example

A field sales executive takes an order at an outlet with no coverage. The order and its three lines wait on the phone. When the phone reconnects, the server refuses the order with the message of a validation rule the organization added, which requires a branch for this customer. The executive's Pending changes screen shows the order under Needs attention, with the three lines Blocked behind it.

A few minutes later, the administrator sees a new report in Mobile Sync Failures: Name Order Create failed, Failure Reason Rejected, Attempt Count 1, Resolution Status Open. Error Message gives the branch rule, and Payload shows that the order had a partner account but no branch. There is only one report, for the order. The blocked lines are not reported separately.

The administrator sets the report to In Progress. The partner account has branches, so every order for it must name one. The administrator asks the executive to tap Fix on the order, choose the branch, and save. The order and then its lines sync. The administrator sets the report to Resolved. The device has nothing left to remove, so this only closes the report. Several similar reports from other executives would suggest a training point, or a form change that makes the branch easier to pick on the phone.

Training

Practice exercise

In a sandbox, use a test user whose profile can create orders, and add a validation rule that always refuses orders where a test field has a particular value. On the mobile app, turn on flight mode, create an order with that value, then turn flight mode off.

Expected result: the order appears under Needs attention on the device's Pending changes screen. A new Mobile Sync Failure appears under Field Sales → Settings → Diagnostics → Mobile Sync Failures with Operation Create, Failure Reason Rejected, Attempt Count 1 and Resolution Status Open. Its Error Message contains your rule's message. Then remove the rule, set the report to Retry and save. Keep the app open and online for a few minutes. Confirm that the order syncs without anyone touching the device, and that the report now reads In Progress. Set it to Resolved and delete the test report. (If Resolution Status offers no values, activate them first, as described in Configuration.)

Quick reference

• Find reports in Field Sales → Settings → Diagnostics → Mobile Sync Failures.
• Rejected with 1 attempt: the server refused the change. Read Error Message.
• Rejected with 5 attempts: temporary errors used up every retry.
• Conflict: the record changed or was removed on the server. The user decides.
• Retry re-sends the change from the device. Resolved and Won't Fix remove it from the device. Deleting a report does nothing.
• Times are UTC. Payload and error text stop at 4000 characters.
• Leave Resolved (UTC) and Resolution Notes empty.
• Users need permission to create Mobile Sync Failure records, or their reports never arrive.

Permissions

Access is set per security profile on the Mobile Sync Failure entity. The standard profiles ship with:

Two things to check:

• Every mobile user needs Create. A user whose profile cannot create Mobile Sync Failure records still sees failures on their own device, but their reports are refused and never reach you.
• Settling from the server needs Read on the user's side. The device reads its own reports to pick up Retry, Resolved and Won't Fix. For a user whose profile can only create reports (such as Sales Manager and Parts Manager in the standard setup), your decisions never reach the phone, and the user must act on the device.
• Payloads can contain business data. In the standard setup, Standard User and Sales Executive can read every report, including other users' payloads. If that is too broad, reduce those profiles to Create only. Their devices keep filing reports. See Security profiles.

Configuration

• Where the list appears. The standard setup puts Mobile Sync Failures in the Field Sales app, in the Diagnostics group under Settings. To show it in another app, add it with Setup → Design Studio → Apps → Manage Items.
• Inactive fields. In the standard metadata, every field the device fills (and its picklist values) is marked inactive. Values are still saved and shown on the list and the record page. However, the report builder skips inactive fields. To report on them, open Setup → Design Studio → Entities → Mobile Sync Failure → Schema → Fields, edit each field you need, and switch Active on. Don't activate Resolved (UTC) or Resolution Notes: they have no storage on this record type.
• Resolution Status values. In the standard metadata, all five values (Open, In Progress, Resolved, Won't Fix, Retry) are inactive, and inactive values are not offered in the list. Before you can settle reports, open Setup → Design Studio → Entities → Mobile Sync Failure → Schema → Fields, select Manage PickList Values on Resolution Status, switch on Active for the values you use, and save.
• Views. You can add list views, for example Open reports filtered on Resolution Status. See Entity behavior. In the standard metadata, Attempt Count, App Version and User can't be sorted or filtered.
• Dashboard. The standard Tenant Adoption dashboard already has six tiles built on these reports (see Step 7).
• Retention. No archive or clean-up job removes reports. Delete closed reports when you no longer need them.
• Sync profiles. Mobile Sync Failure is protected: an integration sync profile can't include it.

Common problems

"Field 'Resolution Notes' … is inactive, so a value for it cannot be stored"

You typed into Resolution Notes or Resolved (UTC). These two fields are on the standard form but have no storage on this record type, so the save is refused. Clear them and save again. Track the outcome with Resolution Status, and keep notes in your own ticketing or activity process.

A user has a failed change on their phone, but there is no report

Check, in this order:

1. The user's security profile can create Mobile Sync Failure records.
2. The device is back online, so its queue has sent the report.
3. The failure is final: a change that is still retrying is not reported until the fifth attempt fails.
4. The change is not Blocked behind another change. Only the first failure in a chain is reported.

I set the report to Retry or Resolved, but the user's change is still stuck

Check, in this order:

1. The device has been online with the app open since you saved. It checks for decisions at most every five minutes, and only during a sync.
2. The user's profile can read Mobile Sync Failure records (see Permissions).
3. The change is Rejected or in Conflict. Decisions don't apply to Blocked changes. Settle the failed change they depend on instead.
4. The user hasn't already fixed or resubmitted the change. A resubmitted change is a new attempt, and if it fails it files a new report. Settle the newest report.

If none of these apply, ask the user to fix, retry or discard the change on their device.

Resolution Status offers no values

The values ship inactive. Activate them with Manage PickList Values, as described in Configuration.

The same failure keeps appearing

Each fixed-and-resubmitted change that fails again files a new report. The server-side cause is still there: read the newest Error Message and fix the rule, permission or setting it names.

I can't build a report on Failure Reason or Source Entity

In the standard metadata, the fields are inactive, so the report builder skips them. Switch them to Active as described in Configuration.

The times look wrong

Occurred (UTC) and Last Attempt (UTC) are in UTC. Convert them to your time zone before matching them to a user's account of events.

Common questions

Does resolving or deleting a report retry or cancel the change?

Setting Resolution Status does. On its next sync, the device that filed the report sends the change again for Retry, and removes it for Resolved or Won't Fix, the same as the user's own Discard. This only works if the user's profile can read the reports. Deleting a report, or setting it to Open or In Progress, does nothing on the phone. The user can still fix, retry or discard the change themselves on their Pending changes screen, as described in Working offline.

Why do network problems sometimes appear as Rejected?

The device retries temporary errors (time-outs, server errors, rate limits) automatically, with growing delays. Time spent offline does not count. If the fifth attempt also fails, the device stops and reports the change as Rejected with an Attempt Count of 5. Look for a server problem around Last Attempt (UTC). The change itself may be fine, so a retry from the device often succeeds.

Can I re-enter the data from the payload myself?

You can, but it is usually safer not to. The user's change is still waiting on their device, and if you enter the same data and the user later retries, you get a duplicate. A long payload is also cut off after 4000 characters. Prefer fixing the cause and setting the report to Retry. If you do re-enter the data, set the report to Resolved straight away so the device drops its copy.

Who can see the payloads?

Anyone whose security profile can read Mobile Sync Failure records. In the standard setup that is System Admin, Standard User and Sales Executive. Sales Manager and Parts Manager can only create them. Payloads contain whatever the user was saving, such as order quantities or customer details. Narrow read access if that matters for your organisation.

Related topics

• Working offline: sync status and recovery
• Configuring the mobile app
• How offline-first mobile works
• Troubleshooting the mobile app
• Field Sales
• Mobile Sync Failure entity reference