Setting up the org's holiday calendar is the annual responsibility of the Service Cloud admin or business operations team. The steps below cover the initial setup and the maintenance cycle.
- Identify the Business Hours records
Setup > Business Hours. List the active Business Hours records. Each is a target for holiday attachment.
- Source the holiday calendars
For each region's Business Hours, gather the holiday list from an authoritative source (government website, HR policy doc, regional office calendar).
- Create Holiday records
Setup > Holidays > New Holiday. Add each holiday with name, date, recurrence (if annual). For multi-region orgs, create distinct Holiday records per region or one shared Holiday per date with multiple Business Hours attachments.
- Attach holidays to Business Hours
From each Business Hours detail page, use the Holidays related list to add the relevant holidays. The same Holiday can attach to multiple Business Hours records.
- Verify with BusinessHours.diff()
Run an Apex anonymous block calling BusinessHours.diff() across a holiday range. Confirm the returned working time excludes the holiday.
- Test Case Milestone behavior
Create a test Case with an Entitlement applied. Confirm the milestone target time respects the holiday. Adjust if behavior is unexpected.
- Schedule annual refresh
Add a Q4 calendar reminder to update the holiday list for the next year. Variable-date holidays and one-off observances need new entries.
Specific date like December 25. Use recurrence to repeat annually without new records each year.
Date changes each year (Easter, Thanksgiving). Configure as a recurring rule with the appropriate weekday-of-month pattern.
Partial-day observance (Christmas Eve closing at noon). Configure with specific time range rather than full date.
Holiday attaches only to relevant Business Hours record. Lunar New Year applies to APAC; Memorial Day applies to US.
Same calendar date observed in multiple regions. One Holiday record attached to multiple Business Hours.
- Holidays are attached per Business Hours, not global. Forgetting to attach a Holiday to a regional Business Hours leaves that region treating the day as working.
- Annual maintenance is required for variable-date holidays. Without it, the calendar drifts and SLAs miscalculate silently.
- Recurrence rules support standard patterns but not all corner cases. For complex movable holidays (Easter is computed differently each year), one-off Holiday records may be easier.
- Changes to Holiday configuration do not retroactively recalculate historical Case milestones. The change applies to new Cases and milestones created after the change.
- BusinessHours.diff() in Apex respects only the Business Hours you pass. Code that hard-codes a default Business Hours Id may apply the wrong holiday calendar for a regional Case.