Fsl Offline Architecture

FSL Offline Architecture

This skill activates when an architect needs to design the offline data strategy for FSL Mobile: how records are primed to the device before the work day, how conflicts are resolved when technicians sync after working offline, and how to handle FSL-specific offline constraints. FSL's offline model has hard limits, specific priming hierarchy, and conflict resolution behaviors that differ from generic Salesforce offline patterns.

Before Starting

Gather this context before working on anything in this domain:

• Determine the expected number of parent Work Orders per technician per day and their child record depth (WOLI, Assets, Product). This drives priming volume calculation against the hard limits.
• Decide on conflict resolution strategy before go-live: MERGE_ACCEPT_YOURS (local device wins — default) or MERGE_FAIL_IF_CONFLICT (force manual resolution). This is a design decision, not a configuration option that can be changed post-deployment without impact.
• Understand connectivity patterns for the target deployment. Intermittent connectivity (cell coverage gaps, basements, industrial sites) drives the design toward larger priming windows and more aggressive prefetch.
• Confirm whether server-side automation (Apex triggers, validation rules) needs to fire at job completion or can be deferred to sync time.

Core Concepts

FSL Offline Priming Hierarchy

FSL Mobile primes (downloads) records to the device before the work day in a specific hierarchy:

ServiceResource (the technician)
  └── ServiceAppointments (today's schedule + near-future)
        └── WorkOrders
              └── WorkOrderLineItems
              └── Assets (if linked)
              └── Related records (custom objects with lookups)

The priming engine traverses this hierarchy automatically. Records outside this hierarchy are not primed unless explicitly configured.

Hard limits:

• 1,000 page references — Each related object traversal counts as a page reference. Exceeding 1,000 causes silent failure (not an error) — records beyond the limit are simply not primed.
• 50 records per related list — Only the first 50 records of any related list are primed.
• Recommended maximum: 100 parent Work Orders with 10 child records each

These limits are per-device sync session, not per technician record count.

Conflict Resolution

When a technician syncs after working offline, two conflict resolution strategies are available:

MERGE_ACCEPT_YOURS is the default and most common. It means if a dispatcher updated a Work Order status in Salesforce while a technician was offline updating the same record, the technician's version wins after sync. This can cause unexpected overwrites.

Server-Side Logic Is Deferred to Sync

Critical architectural constraint: Apex triggers, validation rules, and workflow rules do NOT fire when a technician updates records offline. They fire when the device syncs with the server.

Design implications:

• Validation rules that prevent incomplete data cannot catch offline errors until sync
• Apex triggers that send notifications or create related records don't fire in real-time during offline work
• FSL logic (scheduling engine re-evaluation, status transitions) fires at sync time, not at the moment of offline change

Build post-sync validation logic that reviews records updated during offline sessions.

Ghost Records

A "ghost record" is a record that was deleted on the server while a technician's device was offline. When the device syncs, the deleted record still appears on the device until cleanResyncGhosts() is called via the FSL Mobile SDK.

Ghost records can cause technicians to:

• See appointments that were cancelled
• Navigate to Work Orders that no longer exist
• Attempt status transitions on deleted records (which silently fail)

Ghost record cleanup should be triggered automatically after each sync session via an SDK integration point.

Common Patterns

Priming Volume Design

When to use: Before any FSL Mobile deployment, to verify the implementation stays within priming limits.

How it works:

1. Calculate: average WOs per technician per day × average WOLIs per WO × average related objects per WOLI
2. Compare to the 1,000 page reference limit
3. If near the limit: reduce priming depth by excluding non-essential related objects
4. Test with a production-sized data load in sandbox before go-live

Example: 10 WOs × 8 WOLIs × 5 related records = 400 page references (safe). 10 WOs × 20 WOLIs × 6 related records = 1,200 page references (exceeds limit — silent failure).

Conflict Resolution Strategy Selection

When to use: Any FSL Mobile deployment — decision must be made before go-live.

Decision criteria:

• If dispatcher office updates to active appointments are rare: MERGE_ACCEPT_YOURS (default)
• If dispatchers frequently update appointments technicians are actively working: MERGE_FAIL_IF_CONFLICT + build a conflict resolution UI
• If regulatory requirements mandate field data accuracy: MERGE_FAIL_IF_CONFLICT

Decision Guidance

Recommended Workflow

1. Calculate priming volume — Estimate page references for the average technician's daily schedule. Confirm within 1,000 page reference limit.
2. Define conflict resolution strategy — Choose MERGE_ACCEPT_YOURS or MERGE_FAIL_IF_CONFLICT. Document the decision and its implications for operations team.
3. Design ghost record cleanup — Integrate cleanResyncGhosts() into the post-sync SDK workflow.
4. Map server-side logic to sync events — List all Apex triggers and validation rules that touch FSL objects. Document that they fire at sync, not offline. Add post-sync review steps where needed.
5. Configure Briefcase priming — Configure which objects and record sets are primed. Test with production-representative data volume in sandbox.
6. Test offline scenarios — Simulate a 4-hour full-offline session with concurrent server edits. Verify sync behavior, conflict resolution, and ghost record handling.
7. Train dispatchers on offline behavior — Dispatchers must understand that changes to a technician's records during an offline session may be overwritten on sync (MERGE_ACCEPT_YOURS) or require manual resolution (MERGE_FAIL_IF_CONFLICT).

Review Checklist

• Priming volume calculated and confirmed under 1,000 page reference limit
• Conflict resolution strategy decided and documented
• Ghost record cleanup (cleanResyncGhosts()) triggered post-sync
• Server-side automation (triggers, VRs) impact of sync-time firing understood
• Briefcase priming configured and tested with production-representative data
• Offline + sync tested with concurrent server-side edits
• Dispatcher team trained on offline sync behavior

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. 1,000 page reference limit causes silent failure — Records beyond the limit are simply not primed. There is no error. Technicians discover missing data at the job site.
2. Ghost records persist until cleanResyncGhosts() is explicitly called — Deleted server records stay on device. Technicians see cancelled appointments as active until cleanup is triggered.
3. Apex triggers and validation rules fire at sync — not during offline work — Data errors that would be caught by VRs in online mode pass silently during offline work and only surface at sync.
4. MERGE_ACCEPT_YOURS (default) overwrites server changes with device changes — This is correct most of the time but can silently overwrite dispatch-center updates made while the technician was offline.
5. 50 records per related list hard limit — Only the first 50 related records are primed. Work orders with more than 50 line items will have incomplete data on the device.

Output Artifacts

Related Skills

• apex/fsl-custom-actions-mobile — Custom LWC actions that operate in the offline FSL Mobile context
• architect/fsl-integration-patterns — Integration patterns that need to account for sync-time trigger firing