Fsl Scheduling API

FSL Scheduling API

This skill activates when an Apex developer needs to programmatically call the FSL scheduling Apex namespace — specifically FSL.AppointmentBookingService.GetSlots(), FSL.ScheduleService.schedule(), FSL.GradeSlotsService, or FSL.OAAS — to book, rank, or optimize service appointments. It handles the transaction boundary constraints, bulk patterns, and add-on licensing requirements that the standard documentation buries or omits.

Before Starting

Gather this context before working on anything in this domain:

• Confirm whether the org has the Enhanced Scheduling and Optimization (ESO) add-on license. OAAS operations that use ESO require it. Without ESO, the legacy optimization engine is used and operation limits differ.
• Determine the Apex execution context. FSL.AppointmentBookingService.GetSlots() and FSL.ScheduleService.schedule() are callout-backed; they cannot be called in the same transaction as a DML statement that precedes them unless the DML comes first and the transaction is committed before the callout.
• Know whether you are scheduling one appointment (sync) or many (bulk). Bulk requires a Batch Apex class with Database.executeBatch(job, 1) — batch size 1 is mandatory because each FSL scheduling call is itself a callout.
• Identify what "scheduling" means in your context: slot retrieval only (GetSlots), hard assignment (schedule()), slot ranking for a custom UI (GradeSlotsService), or background optimization (OAAS).

Core Concepts

AppointmentBookingService — Slot Retrieval

FSL.AppointmentBookingService.GetSlots(saId, policyId, schedulingPolicyId) returns a List<FSL.Scheduling.TimeSlot> representing available booking windows for a ServiceAppointment. Each TimeSlot includes start/end times and a list of candidate resources.

Critical constraint: GetSlots is a callout. After calling GetSlots, you cannot perform DML in the same transaction. The common pattern — call GetSlots, pick a slot, update ArrivalWindowStart/ArrivalWindowEnd on the SA, then call schedule() — requires two separate transactions:

• Transaction 1: Call GetSlots, return slot data to the caller (LWC, Flow, or async context)
• Transaction 2: Update the SA's ArrivalWindow fields (DML), then call schedule()

Attempting to do all three in one transaction throws a System.CalloutException: You have uncommitted work pending.

ScheduleService — Hard Assignment

FSL.ScheduleService.schedule(saId, schedulingPolicyId) assigns a ServiceResource to the ServiceAppointment based on the scheduling policy. It returns an FSL.ScheduleResult containing the assigned resource, territory, and scheduled start/end time.

Unlike GetSlots, schedule() both calls out and commits scheduling data — it does not require a separate DML commit after it runs. However, it must be called after any preceding DML is committed (i.e., in a fresh transaction with no prior DML in scope).

GradeSlotsService — Slot Ranking

FSL.GradeSlotsService.GradeSlots(saId, slots, schedulingPolicyId) accepts a list of TimeSlots (from GetSlots) and returns them scored by the scheduling policy's optimization criteria. Use this when building a custom booking UI where customers or dispatchers choose from ranked options rather than having the system auto-assign.

OAAS — Optimization as a Service

FSL.OAAS exposes four optimization operations:

• Global: Batch optimization over a 1–7 day horizon. Hard timeout of 2 hours.
• In-Day: Re-optimizes same-day disruptions.
• Resource Schedule: Optimizes a single resource's schedule.
• Reshuffle: Reassigns pinned appointments to fill gaps.

OAAS operations are asynchronous — they submit an optimization job and return immediately. ESO (Enhanced Scheduling and Optimization) is a newer Hyperforce-backed engine with higher throughput and work chain support. When ESO is enabled for a territory, that territory uses ESO; there is no automatic fallback to the legacy engine if ESO encounters an error.

Common Patterns

Two-Transaction Booking Flow

When to use: Any time you need to get slots, let a user or automated logic pick one, then hard-assign the resource.

How it works:

1. In a first Apex transaction (e.g., an @AuraEnabled method or Queueable), call FSL.AppointmentBookingService.GetSlots(saId, ...). Return the slot list to the caller.
2. Store the chosen slot data (start/end, resourceId, territoryId) in a temporary custom object or pass back to the next Apex call.
3. In a second transaction, update ServiceAppointment.ArrivalWindowStart/ArrivalWindowEnd with DML, then call FSL.ScheduleService.schedule(saId, ...).

Why not one transaction: FSL scheduling calls are HTTP callouts to the optimization microservice. Uncommitted DML before a callout throws a CalloutException.

// Transaction 1 — slot retrieval (Queueable or @AuraEnabled)
List<FSL.Scheduling.TimeSlot> slots = 
    FSL.AppointmentBookingService.GetSlots(saId, null, schedulingPolicyId);
// Return to LWC or store in intermediate object

// Transaction 2 — assignment (separate @AuraEnabled or Queueable)
ServiceAppointment sa = [SELECT Id FROM ServiceAppointment WHERE Id = :saId];
sa.ArrivalWindowStart = chosenSlot.startTime;
sa.ArrivalWindowEnd = chosenSlot.endTime;
update sa; // DML first, no prior callout in this transaction
FSL.ScheduleService.schedule(saId, schedulingPolicyId);

Bulk Scheduling via Batch Apex

When to use: Scheduling more than one ServiceAppointment at a time from Apex (e.g., post-migration bulk assignment, nightly scheduling run).

How it works: Implement Database.Batchable<SObject> and set batch size to exactly 1. Each execute() call handles one SA and makes one FSL scheduling callout.

global class BulkFslScheduler implements Database.Batchable<SObject>, Database.AllowsCallouts {
    global Database.QueryLocator start(Database.BatchableContext bc) {
        return Database.getQueryLocator(
            'SELECT Id FROM ServiceAppointment WHERE Status = 'None''
        );
    }
    global void execute(Database.BatchableContext bc, List<SObject> scope) {
        ServiceAppointment sa = (ServiceAppointment)scope[0];
        try {
            FSL.ScheduleService.schedule(sa.Id, SCHEDULING_POLICY_ID);
        } catch (Exception e) {
            // log and continue
        }
    }
    global void finish(Database.BatchableContext bc) {}
}
// Call with: Database.executeBatch(new BulkFslScheduler(), 1);

Why batch size 1: The Apex callout limit is 100 callouts per transaction. More importantly, FSL scheduling calls are long-running HTTP requests — running more than one per execute() risks timeouts and partial failures with no rollback.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Confirm licensing and ESO status — Verify whether the org has the Field Service Scheduling optimization add-on and whether ESO is enabled per territory in Setup > Field Service > Enhanced Scheduling. Mismatched assumptions cause silent OAAS failures.
2. Identify transaction context — Determine whether the call originates from a trigger (avoid — no callouts in triggers), a synchronous Apex controller (@AuraEnabled), a Queueable, or a Batch class. Plan transaction boundaries before writing any code.
3. Split GetSlots and schedule() across two transactions — If the flow requires slot retrieval followed by user selection followed by assignment, implement the split explicitly. Pass slot data via a custom object or back through the LWC component.
4. Implement bulk patterns with Batch Apex, size 1 — If scheduling more than one SA, use Database.executeBatch(new BulkFslScheduler(), 1). Never loop schedule() inside a single transaction or standard batch execute() with size > 1.
5. Handle OAAS operations asynchronously — Call FSL.OAAS methods from a Queueable or scheduled job. Confirm the operation type (Global/In-Day/Resource/Reshuffle) matches the optimization window and scope.
6. Add error handling for scheduling failures — schedule() can return null or throw if no resource is available. Always check the return value and log failures without rethrowing to avoid blocking the batch.
7. Validate in a sandbox with real scheduling policy data — FSL scheduling calls depend on scheduling policies, resources, territories, and operating hours being correctly configured. Unit tests with mocked return values will pass but integration tests against real FSL config are mandatory.

Review Checklist

Run through these before marking work in this area complete:

• No DML statements precede FSL scheduling callouts in the same transaction
• Bulk scheduling uses Batch Apex with executeBatch(job, 1)
• OAAS calls originate from async context (Queueable or Scheduled)
• ESO licensing and per-territory enrollment confirmed before OAAS design
• Error handling checks ScheduleResult for null and logs FSL failures without rethrowing
• Transaction 2 in two-transaction flow performs DML before calling schedule()
• Integration tested against real scheduling policy and territory setup in sandbox

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. GetSlots → ArrivalWindow DML → schedule() must span two transactions — Attempting this in one transaction throws System.CalloutException: You have uncommitted work pending. This is the most common FSL scheduling Apex bug and the official docs do not call it out explicitly.
2. Batch size must be exactly 1 for bulk scheduling — Using a batch size > 1 with FSL callouts risks System.LimitException: Too many callouts and partial failure with no automatic rollback. Always executeBatch(job, 1).
3. OAAS has a 2-hour hard timeout for Global optimization — Jobs submitted past the 2-hour window are cancelled silently. Monitor FSL optimization job records to detect incomplete runs.
4. ESO has no automatic fallback to legacy engine — If ESO is enabled for a territory and the ESO service is unavailable, optimization fails for that territory. There is no automatic downgrade to the classic scheduling engine.
5. schedule() returns null when no resource is available — Do not assume a non-null return. Null means the SA was not scheduled. Log and handle gracefully.

Output Artifacts

Related Skills

• apex/fsl-apex-extensions — Broader FSL Apex namespace coverage including trigger disabling, custom actions, and FSL SDK patterns
• architect/fsl-optimization-architecture — Architecture-level decisions on optimization mode selection, territory sizing, and ESO adoption