SfSkills Domains Docs GitHub

Home / architect / fsl-offline-architecture

fsl-offline-architecture

Use this skill when designing FSL Mobile offline-first architecture: data priming strategy, priming limits, conflict resolution patterns, and sync failure handling. Trigger keywords: FSL offline priming, briefcase sync FSL, offline data limits, conflict resolution MERGE_ACCEPT_YOURS, ghost records FSL. NOT for offline in the standard mobile app — use lwc/lwc-mobile-offline-and-briefcase. NOT for installing, branding or extending the FSL mobile app — use admin/fsl-mobile-app-setup.

Open the skill folder on GitHub

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:

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:

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:

StrategyBehaviorWhen to Use
MERGE_ACCEPT_YOURSLocal device changes winDefault. Use when technician's field data should override office changes during offline period
MERGE_FAIL_IF_CONFLICTSync fails on conflict — requires manual resolutionUse when data accuracy is critical and offline/server versions cannot be auto-merged

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:

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:

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:

Decision Guidance

SituationRecommended ApproachReason
High record volume per technicianStay under 100 WOs / 10 children eachKeeps page references under 1,000
Dispatcher + technician concurrent editsMERGE_FAIL_IF_CONFLICT + resolution UIPrevents silent data overwrites
Field-first operations (technician data primary)MERGE_ACCEPT_YOURS (default)Technician's offline work takes precedence
Ghost records persistingTrigger cleanResyncGhosts() after each syncOnly mechanism to remove ghost records
Validation rules needed at job completionAccept sync-time firing; build post-sync reviewVRs don't fire offline — architectural reality
Custom object needs offline accessAdd to priming hierarchy via Briefcase configurationOnly primed objects are available offline
  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

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

ArtifactDescription
Priming volume analysisPage reference calculation for average technician schedule
Conflict resolution design decisionStrategy choice and operational impact documentation
Offline scenario test planTest cases for offline work, sync, conflict, and ghost record scenarios

Package files