8.3 Offline Synchronization & Conflict Resolution

8.3 Offline Synchronization & Conflict Resolution

Scope note: Offline synchronization is not one of the eight published Intermediate exam sections; it belongs to the mobile specialisation and deepens at the Advanced level. It earns its place here because the synchronization model is the sharpest illustration of a principle the exam does test everywhere — that client state and server state are separate, and that validation and security must be enforced on the server. Read it for that principle, and for the delivery skills you will need the first time a customer asks for a field app.

In field service, construction, emergency response, and logistics, mobile workers frequently operate in environments with intermittent, degraded, or non-existent network connectivity. Building an enterprise application that simply shows a "Network Disconnected" error in these scenarios is unacceptable. Mendix solves this challenge through a robust offline-first data architecture.

---

The Offline-First Data Architecture

An offline-first application does not treat network loss as an error state; rather, it treats local device storage as its primary data repository and uses network connectivity opportunistically to synchronize changes with the central database.

[Mobile Device File System]
  └── Embedded SQLite Database
       ├── Local Entity Tables (Cached server records)
       ├── New Offline Records (Staged for upload)
       └── System Synchronization Metadata Tables
            ├── Object State Flags (Created, Changed, Deleted)
            └── Last Sync Timestamp Tokens

The Local Embedded SQLite Database

When you configure an entity for an offline-enabled Native Mobile profile in Mendix Studio Pro, the Mendix runtime automatically builds and maintains an embedded SQLite relational database on the user's mobile device:

• Schema Mirroring: Studio Pro creates local SQLite tables that correspond directly to the domain model entities selected for the mobile navigation profile. Attributes, data types, and local association pointers are mapped into SQLite columns.
• Local Change Tracking (Dirty Flags): Whenever a user creates, updates, or deletes an object while offline via a Nanoflow, the local SQLite database modifies the record and marks it with an internal synchronization state flag:
  • Created: The object was instantiated on the device and does not yet exist on the server database.
  • Changed: The object was originally downloaded from the server, but one or more attributes or associations were updated locally.
  • Deleted: The object was flagged for deletion by the user while offline.
  • Synced: The local record matches the server database state.
• Isolation: Operations executed against local SQLite are completely isolated from the server database until the application explicitly executes a Synchronize activity.

The Synchronization Lifecycle: The Two-Phase Protocol

Data exchange between the client device's SQLite database and the central server database occurs exclusively through the Synchronize activity in a Nanoflow. The synchronization protocol strictly executes in two sequential phases:

Phase 1: The Upload Phase (Client to Server)

Before the mobile client can safely download new records from the server, it must first upload all pending changes made on the device:

1. Payload Packaging: The client scans local SQLite for all objects bearing Created, Changed, or Deleted state flags. It serializes these objects, attributes, and modified associations into an upload payload.
2. Transmission & Transaction Initialization: The client transmits the payload to the Mendix Server over a secure HTTPS connection. The server initiates a single relational database transaction.
3. Server Validation & Event Handlers: The server processes each uploaded change:
   • Object validations and domain rules are evaluated.
   • Server-side Before Commit and After Commit entity event handlers execute.
4. Conflict Evaluation: If an uploaded object was also modified on the server while the client was offline, the server detects the version conflict and evaluates the entity's configured conflict resolution strategy.
5. Server Commit: If all validations pass without fatal errors, the server commits the transaction to the central database (e.g., PostgreSQL). It sends an acknowledgement back to the client, mapping any temporary local client GUIDs to permanent server database IDs.
6. Local State Cleanse: The client updates local SQLite, resetting object dirty flags to Synced.

Phase 2: The Download Phase (Server to Client)

Once the upload phase completes successfully, the download phase retrieves server-side modifications:

1. Delta Calculation: The client sends its Last Synchronization Token (timestamp/sequence token) to the server. Rather than sending the entire database over the wire, the server queries the database for delta changes—records that have been created, modified, or deleted on the server since that token.
2. Payload Retrieval: The server serializes the delta records and returns them to the client.
3. Local SQLite Update: The client processes the delta payload:
   • Inserts newly created server records into SQLite.
   • Updates existing local records with fresh server attribute values.
   • Deletes local records that were deleted on the server.
4. Token Update & UI Refresh: The client stores the new synchronization token in SQLite and signals the React Native runtime to refresh active page views.

---

Synchronization Modes

The Synchronize activity (available in nanoflows inside an offline-first app) has three modes, and all three run the same two phases — upload, then download:

The documentation also frames the two ends of that range as full synchronization and selective synchronization, which is the vocabulary the exam tends to use:

1. Full Synchronization

Full Synchronization processes every entity that is configured for offline use in the active navigation profile.

• How It Works: Uploads all uncommitted client changes across all offline entities, then downloads all server-side deltas across all offline entities.
• Default Usage: Typically executed upon user login, app launch, or when the user explicitly taps a global "Sync All" button in the application header.
• Downside: If the application domain model contains dozens of entities with large data volumes, full synchronization consumes significant cellular bandwidth, drains battery life, and increases the risk of timeout on weak connections.

2. Selective Synchronization

Selective Synchronization allows the developer to restrict synchronization to specific objects or specific entity subsets.

• How It Works: The developer selects an object or a list of objects in the Synchronize action dialog (e.g., synchronizing only the currently active WorkOrder and its related InspectionItem records).
• Performance Advantage: Minimizes the network payload to a few kilobytes. Execution takes milliseconds rather than seconds.
• Ideal Scenario: Used in high-frequency field workflows—such as submitting an urgent safety incident report immediately while deferring the synchronization of massive equipment catalogs to a nightly Wi-Fi sync.

Full vs. Selective Synchronization Comparison

---

Conflict Behaviour: "Last Wins", Not a Setting

A data conflict occurs when an offline user edits an object on their device while another user — or a backend integration — modifies that same object on the central server.

Exam Trap: Mendix has no "Conflict Resolution" property on the entity offering Server Wins or Client Wins. That pair of strategies is invented, and it is one of the most confidently wrong answers in circulation. Any option describing a configurable Server-Wins/Client-Wins switch is a distractor.

What Mendix Actually Does

Mendix documents the platform behaviour plainly: when multiple users synchronize the same state of an object, change it, and synchronize it back, the last synchronization overwrites the entire content of the object on the server. This is a "last wins" approach — and note that it overwrites the whole object, not just the attributes the second user happened to touch. A field technician who syncs at 16:05 silently discards everything a colleague wrote at 16:03.

Two further consequences follow from how synchronization is defined:

• Synchronization works at the database level. New uncommitted objects and uncommitted attribute changes are never synchronized — only committed state travels.
• Because the upload phase runs first, the server has already accepted the client's version by the time the download phase refreshes the device. The device does not "lose the argument"; it wins it, and the server-side edit is what disappears.

Building Something Better Than Last Wins

Mendix's documented remedy is to detect the conflict yourself:

1. Add a revision ID (or version number) attribute to the offline-enabled entity, and increment it on every server-side commit.
2. In a before-commit microflow on that entity, compare the revision ID arriving from the device with the revision currently stored on the server.
3. If they differ, another party changed the object while the device was offline. Now you choose the policy explicitly — reject the upload, merge attribute by attribute, write both versions to a conflict entity for a human to adjudicate, or accept the device version and log what was overwritten.
4. For deletes, Mendix's stated best practice is to use an isDeleted Boolean attribute rather than deleting the record outright, so that deletion conflicts can be detected on the server at all.

This is a modelling responsibility, not a configuration checkbox — which is exactly why the exam can ask about it.

Advanced Pattern: Custom Conflict Resolution via Microflows

When plain "last wins" is not acceptable (e.g., merging individual conflicting fields or notifying a supervisor), architects implement custom reconciliation:

1. Mobile clients write offline edits to dedicated Staging Entities (e.g., InspectionSubmission) rather than the core master entity.
2. Synchronization uploads the staging record without conflict.
3. A server-side microflow compares the staging record against the master record, merges non-conflicting attributes, and flags genuine discrepancies for human review in an administrative dashboard.

---

Offline Validation Rules & Association Integrity

Designing bulletproof offline applications requires understanding when and where business rules are evaluated:

Local Validation vs. Server Event Handlers

• Domain Model Validation Rules: Basic validation rules defined directly on entity attributes (such as Required, Range, or Regular Expression) are evaluated locally on the client device during Nanoflow execution before objects are saved to SQLite.
• Microflow Event Handlers: Server-side event handlers (Before Commit, After Commit, Before Delete) DO NOT execute on the mobile device while offline. They execute exclusively on the Mendix Server during Phase 1 (Upload Phase) of the Synchronize activity.
• Validation Failure During Upload: If a server-side Before Commit handler rejects an uploaded object (for example, failing an inventory availability check), the server aborts the entire upload transaction, rolls back database mutations, and sends an error response to the client. The client retains its dirty records in SQLite for correction.

Association Integrity Constraints

When synchronizing entities with associations:

• If you configure a child entity for offline synchronization, you must also configure its associated parent entity if business logic requires the association to be valid.
• If a mobile user associates a locally created Child object with a Parent object and synchronizes, Mendix guarantees that parent-child relational foreign keys are correctly resolved and committed within the server database transaction.

---

Offline Synchronization Exam Traps

Exam Trap 1: Believing Full Synchronization can be executed without an active network connection. The Synchronize activity requires an active network connection to open an HTTPS socket to the Mendix Server. If a Nanoflow calls Synchronize while offline, it will fail and trigger the activity's error handler.

Exam Trap 2: Assuming Microflow Commit event handlers run immediately when an offline user edits an object. In offline apps, editing and saving an object in a Nanoflow updates only the local SQLite database. Server-side event handlers do not trigger until the Synchronize activity uploads the record to the Mendix Server.

Exam Trap 3: Overlooking Selective Synchronization association dependencies. When using Selective Synchronization to sync a specific child object, failing to include its modified associated parent object can result in broken associations on the server or validation rejections.