SfSkills Domains Docs GitHub

Home / architect / fsl-integration-patterns

fsl-integration-patterns

Use this skill when designing FSL integrations: ERP parts/inventory sync, GPS/fleet management integration, IoT-triggered work order creation, and customer notification workflows. Trigger keywords: FSL ERP integration, ProductConsumed ERP sync, GPS fleet integration FSL, IoT work order trigger, customer notification FSL integration. NOT for Financial Services Cloud integration design — use architect/fsc-architecture-patterns. NOT for bulk-loading Work Order and Service Appointment history — use data/fsl-work-order-migration.

Open the skill folder on GitHub

FSL Integration Patterns

This skill activates when an architect designs integrations between FSL and external systems: ERP inventory platforms, GPS/fleet management systems, IoT platforms, and customer notification services. FSL's integration patterns have FSL-specific object constraints and anti-patterns that generic Salesforce integration guidance doesn't cover.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

ERP Parts Sync — ProductRequired and ProductConsumed

FSL uses two objects to track parts for a job:

The bidirectional sync pattern:

  1. ERP → FSL: Sync product catalog and warehouse stock to Product2 and ProductItem (van stock per location)
  2. FSL → ERP: After technician records ProductConsumed, upsert that consumption back to ERP to decrement warehouse ledger

Critical gotcha: If ProductConsumed is not upserted back to ERP, the van stock is decremented in Salesforce (from ProductItem) but the ERP warehouse ledger still shows the parts as available — creating phantom stock. The technician arrives at the next job expecting parts that were already used.

Both ProductRequired and ProductConsumed should have External ID fields for upsert-safe ERP round-tripping.

IoT-Triggered Work Orders

IoT devices (connected assets, sensors) that detect anomalies should trigger work order creation asynchronously:

Correct pattern:

  1. IoT platform publishes event to Salesforce Platform Event channel
  2. Platform Event trigger (Apex or Flow) creates WorkOrder + ServiceAppointment
  3. Optional: Call FSL scheduling API via Queueable (never synchronously in the Platform Event handler)

Anti-pattern: Calling FSL.ScheduleService.schedule() synchronously inside the Platform Event Apex handler. Platform Events fire in an Apex context — scheduling callouts require a fresh async context (Queueable). Synchronous scheduling in the event handler throws CalloutException.

GPS/Fleet Integration

Fleet management systems provide real-time vehicle location data. The common mistake is polling Salesforce as the GPS source, with Salesforce making outbound calls to the fleet API in real-time.

Correct pattern: Fleet system pushes batch location updates to Salesforce on a defined schedule (every 5–15 minutes). The fleet system is the source of truth for vehicle location; Salesforce consumes updates, not the reverse.

Anti-pattern: Using a Scheduled Apex or Flow on a tight interval (every 1–5 minutes) to poll the fleet API for GPS data. This approach exhausts the Daily API Request limit for high-volume fleets.

Customer Notifications

Customer notifications (SMS "technician en route", email ETA update) should be triggered by FSL Mobile status transitions:

The notification platform (Twilio, SendGrid, AWS SNS) is called via Salesforce's external service or named credential integration, triggered by the status change event.

Common Patterns

ProductConsumed ERP Round-Trip

When to use: ERP is the warehouse ledger for parts; FSL Mobile records actual parts usage.

How it works:

  1. ERP → Salesforce: Nightly batch upsert of Product2 and ProductItem (van stock) with External IDs
  2. Technician records ProductConsumed in FSL Mobile: ProductConsumed.QuantityConsumed decrements ProductItem.QuantityOnHand
  3. Salesforce → ERP: Near-real-time Platform Event or scheduled batch upsert of ProductConsumed records back to ERP using External ID
  4. ERP processes ProductConsumed records as parts consumption events, decrementing warehouse stock

IoT Work Order Creation

When to use: Connected assets trigger field service dispatch automatically.

How it works:

// Platform Event handler — creates WO and queues scheduling
public class IoTWorkOrderTrigger implements Database.Batchable<SObject> {
    // Trigger creates WorkOrder + ServiceAppointment via DML
    // Then enqueues FslScheduleQueueable (from apex/fsl-scheduling-api skill)
    // Never calls FSL.ScheduleService.schedule() here
}

Decision Guidance

Integration TypePatternAvoid
ERP parts catalogNightly inbound batch upsert with External IDsReal-time per-product REST calls
ERP parts consumptionProductConsumed Platform Event or scheduled batch → ERPIgnoring the ERP feedback loop (causes phantom stock)
IoT work order creationPlatform Event → Flow/Apex → WO creation → Queueable for schedulingSynchronous scheduling inside event handler
GPS fleet locationInbound batch from fleet system on cadenceOutbound polling from Salesforce to fleet API at high frequency
Customer notificationsStatus change trigger → named credential → notification platformDirect SMS/email from triggers (synchronous callout risk)
  1. Map integration directions — For each external system, document whether data flows into FSL, out of FSL, or both. Identify the authoritative system for each data domain.
  2. Design ERP parts feedback loop — Confirm ProductConsumed → ERP upsert is included. Missing this creates phantom stock.
  3. Use Platform Events for IoT — Design IoT event ingestion via Platform Events. Keep Work Order creation in the event handler; defer scheduling to a Queueable.
  4. Define GPS update cadence — Agree on a batch update frequency with the fleet team. Document the Daily API limit implications at each frequency.
  5. Implement notification triggers — Configure FSL Mobile status transitions as notification triggers via Platform Events or record-triggered Flows.
  6. Add External IDs to all integration objects — ProductRequired, ProductConsumed, WorkOrder, ServiceAppointment should all have External IDs for idempotent integration operations.
  7. Test integration failure modes — Test ERP unavailability, GPS feed delays, and IoT event storms. Define retry and dead-letter queue patterns.

Review Checklist

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Missing ProductConsumed → ERP feedback loop creates phantom stock — The most common FSL ERP integration gap. Van stock decrements in Salesforce but ERP still shows parts as available, causing technicians to arrive at jobs without the parts they expected.
  2. FSL scheduling callouts cannot be made synchronously inside Platform Event handlers — Platform Event handlers run in an Apex transaction. Schedule() and GetSlots() are callouts that require no uncommitted DML. Use Queueable for any scheduling that follows a Platform Event.
  3. Daily API limit exhaustion from GPS polling — Polling the fleet GPS API every 1 minute for 200 vehicles = 288,000 API calls/day. At typical FSL org limits, this exhausts the daily limit by midday. Fleet systems should push to Salesforce, not be polled.
  4. FSL Mobile offline status transitions fire integration triggers at sync — not in real-time — Customer notifications triggered by status changes will be delayed until the technician syncs. Design notification logic to tolerate sync latency.

Output Artifacts

ArtifactDescription
FSL integration architecture diagramData flow diagram for ERP, GPS, IoT, and notification integrations
ProductConsumed round-trip designERP bidirectional sync pattern with External ID and event trigger

Package files