fsl-capacity-planning

# FSL Capacity Planning

This skill activates when a practitioner needs to configure, audit, or report on Field Service Lightning workforce capacity — including per-resource capacity caps via `ServiceResourceCapacity`, territory-level demand throttling via `WorkCapacityLimit`, and strategies for measuring capacity utilization. It addresses both mechanisms the FSL scheduling engine uses to constrain appointment volume and explains how the two mechanisms interact.

---

## Before Starting

Gather this context before working on anything in this domain:

- Confirm that Field Service is enabled (Setup > Field Service Settings) and that the running user has access to `ServiceResourceCapacity`, `WorkCapacityLimit`, and `ServiceResource` objects.
- Determine which capacity mechanism applies: resource-level capacity (`ServiceResourceCapacity`) controls how many hours or appointments a single resource can take in a period; territory-level capacity (`WorkCapacityLimit`) controls how many appointments of a given work type a territory accepts in a time window. These are independent and additive — an appointment must satisfy both constraints before it can be scheduled.
- Identify whether resources are marked `IsCapacityBased = true`. `ServiceResourceCapacity` records only take effect on resources where `IsCapacityBased = true` on the `ServiceResource` record. Standard time-slot-based technicians ignore these records entirely.
- Establish the scheduling horizon. `ServiceResourceCapacity` and `WorkCapacityLimit` records cover explicit date ranges. Gaps in coverage silently prevent scheduling without any error shown to dispatchers or optimization logs.
- Note that there are no seasonal capacity templates in FSL. Bulk updates to `WorkCapacityLimit` records (e.g., holiday reductions, peak-season increases) must be performed via Data Loader or Apex — there is no native UI for mass date-range updates.

---

## Core Concepts

### Two Capacity Mechanisms: Resource-Level vs. Territory-Level

FSL provides two distinct capacity objects that serve different purposes and operate independently:

**ServiceResourceCapacity** (API v38.0+) — per-resource cap on hours or appointments within a date range. Applies only when `ServiceResource.IsCapacityBased = true`. The scheduler checks this cap before assigning an appointment to a capacity-based resource. If the resource is at or over the cap for the period, the scheduler excludes it from candidates.

**WorkCapacityLimit** — territory-level demand throttle per work type per time window. Limits how many appointments of a given `WorkType` are accepted in a defined `CapacityWindow` (Daily, Weekly, or Monthly) within a `ServiceTerritory`. When the limit is reached, new appointments of that work type in that territory are rejected silently — no error is displayed to the dispatcher.

Both mechanisms can be active simultaneously. An appointment must pass the `WorkCapacityLimit` check at the territory level before the `ServiceResourceCapacity` check at the resource level is evaluated. Configuring only one without being aware of the other is a common misconfiguration that causes unexpected rejections.

### ServiceResourceCapacity Object

Key fields on `ServiceResourceCapacity` (Object API v38.0+):

| Field | Type | Notes |
|---|---|---|
| `ServiceResourceId` | Lookup | Must reference a resource where `IsCapacityBased = true` |
| `StartDate` | Date | Start of the period this record covers |
| `EndDate` | Date | End of the period (inclusive) |
| `TimeSlotType` | Picklist | `Normal` (standard business hours) or `Extended` (after-hours) |
| `Capacity` | Number | Maximum units available within the period |
| `CapacityUnit` | Picklist | `Hours` or `Appointments` — defines what `Capacity` measures |

The scheduler sums the duration (for `Hours` unit) or count (for `Appointments` unit) of all service appointments already linked to the resource within the period. If that sum equals or exceeds `Capacity`, the resource is excluded from scheduling candidates. Gaps between `EndDate` of one record and `StartDate` of the next create unschedulable windows with no warning.

### WorkCapacityLimit Object

`WorkCapacityLimit` records express territory-level demand throttles per work type. Key fields:

| Field | Type | Notes |
|---|---|---|
| `ServiceTerritoryId` | Lookup | The territory this limit applies to |
| `WorkTypeId` | Lookup | The work type being throttled |
| `CapacityWindow` | Picklist | `Daily`, `Weekly`, or `Monthly` |
| `CapacityLimit` | Number | Maximum appointments within the window |
| `StartDate` / `EndDate` | Date | Date range this limit is active |

When the number of scheduled appointments of the specified work type in the territory reaches `CapacityLimit` within the current window, additional booking attempts are rejected. Importantly, this rejection is **silent**: no error, no notification, no log entry visible to a dispatcher. The appointment simply does not schedule.

### Reporting Gap: No Native Capacity vs. Utilization Aggregation

There is no standard FSL report type that natively aggregates `ServiceResourceCapacity.Capacity` against the actual duration of scheduled `ServiceAppointment` records. To measure capacity utilization (e.g., "Resource X used 6 of 8 available hours this week"), one of two approaches is required:

1. **Custom Report Type** — Create a custom report type joining `ServiceResource` → `ServiceAppointment` and manually compute utilization by comparing appointment durations against the resource's capacity records (queried separately or via a formula field).
2. **CRM Analytics (Tableau CRM)** — Use the FSL Analytics app or a custom dataset recipe to join `ServiceResourceCapacity` and `ServiceAppointment` data and produce utilization dashboards. This is the recommended approach for orgs with more than 50 resources or complex territory structures.

---

## Common Patterns

### Pattern: Resource-Level Capacity Cap for Shared or Pooled Assets

**When to use:** A resource (shared equipment, a pool vehicle, or a contractor billed per appointment) must be capped at a fixed number of hours or appointment slots per day or week.

**How it works:**
1. Verify `ServiceResource.IsCapacityBased = true` for the target resource. If not, update the field before proceeding — `ServiceResourceCapacity` records inserted against a non-capacity-based resource have no scheduling effect.
2. Create `ServiceResourceCapacity` records to cover the full scheduling horizon without gaps. For a resource capped at 8 hours/day, create monthly records or a single long-range record with `Capacity = 8` and `CapacityUnit = Hours`.
3. Use `TimeSlotType = Normal` for standard business hours. If the resource can also be booked in extended hours, create a separate record with `TimeSlotType = Extended`.
4. Monitor approaching capacity by querying: `SELECT ServiceResourceId, Capacity, CapacityUnit, StartDate, EndDate FROM ServiceResourceCapacity WHERE EndDate >= TODAY`.

**Why not the alternative:** Using standard time-slot availability for shared assets means the scheduler treats the asset as if it has one dedicated shift — it will not correctly prevent overbooking across multiple simultaneous appointments consuming the same physical resource.

### Pattern: Territory-Level Demand Throttle by Work Type

**When to use:** A service territory must limit the number of a specific work type (e.g., "Complex Install") it accepts per week because of technician availability, parts supply constraints, or SLA management.

**How it works:**
1. Identify the `ServiceTerritory` and `WorkType` to be throttled.
2. Create a `WorkCapacityLimit` record:
   - `ServiceTerritoryId` = the territory's Id
   - `WorkTypeId` = the relevant work type Id
   - `CapacityWindow` = `Weekly` (or `Daily` / `Monthly` as appropriate)
   - `CapacityLimit` = maximum acceptable appointment count per window
   - `StartDate` / `EndDate` = the date range for this limit
3. Test by attempting to book more appointments than the limit. Confirm that once the limit is reached, additional bookings are rejected (they will not appear as scheduled without error in the dispatcher view).
4. Communicate the limit behavior to dispatchers. Because rejection is silent, dispatchers must actively monitor appointment counts per territory and work type via a custom report or dashboard.

**Why not the alternative:** Relying on dispatcher judgment to throttle territory demand is not scalable and breaks under dispatch team turnover. Encoding the limit in `WorkCapacityLimit` enforces it automatically at the scheduling engine level.

### Pattern: Seasonal or Event-Driven Capacity Adjustment

**When to use:** Capacity needs to change for a known future period (holiday reductions, peak-season expansions, a planned technician leave block).

**How it works:**
1. Identify which records need updating: `ServiceResourceCapacity` for resource-level adjustments, `WorkCapacityLimit` for territory-level adjustments.
2. Because no bulk-update UI exists, use one of:
   - **Data Loader** — export the current records, modify `Capacity`, `StartDate`, and `EndDate` in the CSV, then use upsert to apply changes.
   - **Apex batch job** — query the affected records and update the `Capacity` field programmatically.
3. Ensure the new records cover the adjusted period end-to-end. Insert a reduced-capacity record for the holiday window, then resume with the standard record after the window ends. Do not leave a date gap between records.
4. After the seasonal period ends, revert or create continuation records to restore standard capacity. Stale low-capacity records left in place silently prevent normal scheduling after the season ends.

**Why not the alternative:** Deactivating resources during low-capacity periods is not equivalent — it removes the resource from all scheduling, not just capacity-constrained scheduling. The correct approach is a reduced-capacity record, not resource deactivation.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Cap a single resource's daily appointment count | `ServiceResourceCapacity` with `CapacityUnit = Appointments` | Resource-level cap; requires `IsCapacityBased = true` |
| Cap a single resource's available hours per week | `ServiceResourceCapacity` with `CapacityUnit = Hours` | Hour-based cap enforced by scheduler against actual SA durations |
| Limit how many Complex Installs a territory accepts per week | `WorkCapacityLimit` with `CapacityWindow = Weekly` | Territory-level demand throttle; works independently of resource-level caps |
| Reduce capacity for a 2-week holiday period | New `ServiceResourceCapacity` or `WorkCapacityLimit` record with lower `Capacity` for that date range | No seasonal template UI; must create date-bounded records manually |
| Measure resource utilization vs. capacity | Custom report type or CRM Analytics dataset joining `ServiceResourceCapacity` and `ServiceAppointment` | No native aggregated report type exists |
| Resource appears capacity-based but is not restricted | Verify `ServiceResource.IsCapacityBased = true`; confirm no date gaps in `ServiceResourceCapacity` records | `IsCapacityBased` must be set before capacity records have effect |
| Dispatchers see no error but appointments stop scheduling | Check `WorkCapacityLimit` — limit reached causes silent rejection | Silent rejection is `WorkCapacityLimit`'s default behavior; no UI notification |
| Standard technician should have shift-based availability | Do NOT use `ServiceResourceCapacity`; use operating hours and shifts | Capacity records only apply to `IsCapacityBased = true` resources |

---

## Recommended Workflow

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

1. **Audit prerequisites** — Confirm Field Service is enabled and the running user can read and write `ServiceResource`, `ServiceResourceCapacity`, and `WorkCapacityLimit`. Query `SELECT Id, Name, IsCapacityBased FROM ServiceResource WHERE IsActive = true` to identify which resources are capacity-based and which are shift-based. This determines which capacity mechanism applies.

2. **Configure resource-level capacity** — For each resource where `IsCapacityBased = true`, create `ServiceResourceCapacity` records to cover the full scheduling horizon without gaps. Set `Capacity` and `CapacityUnit` to match the business rule (hours or appointment count). Create separate records for `Normal` and `Extended` `TimeSlotType` if both apply. Verify no date gaps exist between records by sorting on `StartDate`.

3. **Configure territory-level demand throttles** — For each territory and work type combination that requires demand management, create `WorkCapacityLimit` records with the appropriate `CapacityWindow` and `CapacityLimit`. Confirm `StartDate` and `EndDate` cover the intended scheduling window. Document the limit and communicate it to dispatchers — rejection is silent.

4. **Handle seasonal adjustments** — If near-future capacity changes are required (holiday reductions, peak expansions), create bounded `ServiceResourceCapacity` or `WorkCapacityLimit` records with the adjusted values. Do not leave date gaps. After the seasonal period, create continuation records to restore standard capacity.

5. **Build a utilization reporting strategy** — If the org does not already have a capacity utilization report, create a custom report type joining `ServiceResource` and `ServiceAppointment`, or configure a CRM Analytics recipe. Document the reporting approach for operations teams who will monitor capacity health.

6. **Validate end-to-end** — Query `SELECT Id, StartDate, EndDate, Capacity, CapacityUnit FROM ServiceResourceCapacity WHERE ServiceResource.IsCapacityBased = true ORDER BY ServiceResourceId, StartDate` and scan for gaps. Query `WorkCapacityLimit` records and confirm `CapacityLimit` values are non-zero and dates cover the active scheduling window. Create a test service appointment for each throttled work type and territory to confirm limits are enforced as expected.

7. **Review checklist and handoff** — Complete the review checklist below. If dispatchers report silent appointment rejections, re-examine `WorkCapacityLimit` records first, then check for date gaps in `ServiceResourceCapacity`. Document the capacity model for operations teams.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] All capacity-based resources have `ServiceResource.IsCapacityBased = true`
- [ ] `ServiceResourceCapacity` records cover the full scheduling horizon with no date gaps
- [ ] Each `ServiceResourceCapacity` record has a valid `CapacityUnit` (`Hours` or `Appointments`) and a non-zero `Capacity`
- [ ] `WorkCapacityLimit` records exist for each territory/work type pair that requires demand throttling
- [ ] `WorkCapacityLimit` records have non-zero `CapacityLimit` values and cover the active scheduling window
- [ ] Dispatchers are informed that `WorkCapacityLimit` rejections are silent — a monitoring report or dashboard is in place
- [ ] Seasonal or event-driven capacity changes have bounded date records and continuation records after the event ends
- [ ] A utilization reporting strategy (custom report type or CRM Analytics) is documented and accessible to operations
- [ ] No standard time-slot-based resources (non-capacity-based) have `ServiceResourceCapacity` records that could create false expectations

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **WorkCapacityLimit rejections are completely silent** — When a territory-level capacity limit is reached, the scheduling engine stops accepting appointments for that work type in that territory without displaying any error to the dispatcher or writing to any log visible in standard FSL UIs. Dispatchers see the appointment as unscheduled but receive no explanation. The only detection method is a SOQL query against `WorkCapacityLimit` to compare the limit against the actual appointment count for the period.

2. **ServiceResourceCapacity has no effect unless IsCapacityBased = true** — Inserting `ServiceResourceCapacity` records against a `ServiceResource` where `IsCapacityBased = false` produces no scheduling restriction and no error. The scheduler silently ignores those records. This is the most common misconfiguration when setting up capacity-based scheduling for the first time: the capacity records exist, but the resource flag was never set.

3. **No native report type aggregates capacity vs. actual utilization** — There is no standard FSL report type that joins `ServiceResourceCapacity.Capacity` to `ServiceAppointment` durations. Orgs that need capacity utilization metrics must build a custom report type or a CRM Analytics dataset recipe. Teams that assume a standard report exists often discover this only when asked to produce an operations dashboard.

4. **Date gaps in capacity records silently block scheduling** — If `ServiceResourceCapacity` record A ends on March 31 and the next record B starts on April 2, no appointments can be scheduled on April 1 for that resource, and no warning is issued. The scheduler finds no active capacity record and excludes the resource from candidates without any indication to the dispatcher. Gap auditing via SOQL `ORDER BY StartDate` is required at setup and after any seasonal update.

5. **No seasonal capacity template or bulk UI exists** — There is no native FSL UI to bulk-adjust `WorkCapacityLimit` or `ServiceResourceCapacity` values for a future time range. Peak-season or holiday adjustments must be performed via Data Loader, Apex batch, or the API. Teams that expect a "copy and reduce" UI workflow discover this constraint only when the need arises under time pressure.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| `ServiceResourceCapacity` records | Per-resource capacity caps (hours or appointment counts) covering the scheduling horizon without date gaps |
| `WorkCapacityLimit` records | Territory + work type demand throttles with defined capacity windows |
| Utilization reporting strategy | Custom report type definition or CRM Analytics recipe spec for capacity vs. actual appointment hours |
| Seasonal adjustment runbook | Data Loader or Apex batch procedure for updating capacity records at period boundaries |
| Capacity audit query | SOQL to detect date gaps and zero-capacity records for ongoing operational monitoring |

---

## Related Skills

- `fsl-resource-management` — ServiceResource setup including `IsCapacityBased` flag and `ServiceResourceCapacity` fundamentals; must be completed before capacity planning records can be inserted
- `fsl-service-territory-setup` — ServiceTerritory and operating hours configuration; `WorkCapacityLimit` requires valid territory records
- `fsl-scheduling-policies` — Work rules and optimization settings; scheduling policies interact with capacity limits during automated optimization runs

## Official Sources Used

- Capacity Planning Overview — https://help.salesforce.com/s/articleView?id=sf.fs_capacity_planning.htm
- Define Capacity-Based Resources — https://help.salesforce.com/s/articleView?id=sf.fs_capacity_based_resources.htm
- Manage Work Capacity — https://help.salesforce.com/s/articleView?id=sf.fs_work_capacity.htm
- ServiceResourceCapacity Object Reference — https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_serviceresourcecapacity.htm
- Salesforce Well-Architected Overview — https://architect.salesforce.com/docs/architect/well-architected/guide/overview.html