PranavNagrecha/AwesomeSalesforceSkills / skills/admin/business-hours-and-holidays
business-hours-and-holidays
VerifiedUse this skill when creating, deploying, or troubleshooting Salesforce Business Hours and Holidays: the calendars that pause Case escalation rules, entitlement milestones, and Apex BusinessHours math outside working hours. Covers the BusinessHoursSettings metadata, the default calendar, per-region calendars, holiday attachment, the Case Business Hours field, and the BusinessHours Apex class. Trigger keywords: business hours, holidays, SLA clock, escalation not pausing, working hours, support hours, milestone timer weekend. NOT for the escalation rule entries themselves — use admin/escalation-rules. NOT for entitlement process design — use admin/entitlements-and-milestones. NOT for Field Service operating hours or shift scheduling — use admin/fsl-scheduling-setup.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.7 KB |
| references/examples.md | markdown | 9.7 KB |
| references/gotchas.md | markdown | 8.6 KB |
| references/llm-anti-patterns.md | markdown | 4.2 KB |
| references/metadata-examples.md | markdown | 12.9 KB |
| references/well-architected.md | markdown | 3.9 KB |
| scripts/check_business_hours_and_holidays.pyexecutable | script | 10.2 KB |
| templates/business-hours-and-holidays-template.md | markdown | 2.1 KB |
references/gotchas.md
View on GitHub# Gotchas — Business Hours and Holidays
Non-obvious platform behaviors that cause real production problems. Each is grounded in the Metadata API Developer Guide, the Object Reference, or the Apex Reference Guide (v62 PDFs) cited in `well-architected.md`; where a behavior could not be re-verified against an official page it is marked UNVERIFIED beside the claim.
## Gotcha 1: The shipped default calendar is 24 hours a day, 7 days a week
**What happens:** Every new org contains a calendar named `Default` with `default` = `true` and every weekday stored as start `00:00:00.000Z`, end `00:00:00.000Z`. The Metadata API guide's own sample definition shows exactly this shape, and the same pair of values means "open the whole day". Escalation entries left on the default, entitlement processes with no calendar, and Apex calls that fall back to `IsDefault = true` all count wall-clock time.
**Scoped to the default, not to the shape.** The midnight-to-midnight-every-day shape is not itself a mistake — it is exactly how a deliberately named, always-open calendar is stored (a `Severity 1 24x7` tier that genuinely must never pause, for example). The mistake is that shape sitting on the calendar every unconfigured consumer falls back to: the org's `<default>true</default>` calendar, or one still named literally `Default`. `scripts/check_business_hours_and_holidays.py` reflects this: the 24/7 shape on the default (or on a calendar named `Default`) is an ERROR; the same shape on any other, deliberately named calendar prints as an INFO line — "always-open calendar '\<name>': SLA clocks on it never pause — intended for 24/7 severity tiers; confirm it is not attached to entitlements that expect business-hour pauses" — and never fails the check.
**When it occurs:** Any org that enabled escalation rules or entitlements before anyone edited the default calendar. The symptom is an SLA that "breaches over the weekend".
**How to avoid:** Decide explicitly what the default should be. Either edit it to the primary region's hours or create regional calendars and set one of them as default. Never leave the shipped 24/7 calendar as the default in an org that promises business-hours SLAs. If a genuinely always-open calendar is needed for a severity tier, give it its own name, leave `default` false, and confirm nothing that expects business-hour pauses (an entitlement milestone, say) is accidentally attached to it — that confirmation is exactly what the checker's INFO line asks for.
---
## Gotcha 2: A holiday only pauses calendars it is attached to
**What happens:** In `BusinessHoursSettings`, each `holidays` entry carries a `businessHours` value, "the name of the business hours setting that applies to this holiday". A holiday with no calendar attached is stored and displayed in Setup but suspends nothing. The Object Reference states the effect only for associated holidays: business hours and the escalation rules that use them are suspended during the dates and times specified as holidays.
**When it occurs:** Admin creates the year's public holidays from the Holidays page and stops there, or adds a second regional calendar after the holidays were created and forgets to attach them to it.
**How to avoid:** Treat attachment as part of creating a holiday. Retrieve `Settings:BusinessHours` and check that every `holidays` entry names the calendars it should; the skill's checker flags unattached holidays.
---
## Gotcha 3: Each escalation entry chooses its own calendar source
**What happens:** An escalation rule entry has `businessHoursSource` = `None`, `Case`, or `Static`. `None` ignores every calendar. `Static` uses the named `businessHours` and ignores the Case's field. Only `Case` reads `Case.BusinessHoursId`. A regional design that populates the Case field is silently defeated by any entry still set to `None` or to a static calendar.
**When it occurs:** Escalation rules built before regional calendars existed; a "Sev-1 always on" entry copied to create a Sev-2 entry without changing the source.
**How to avoid:** List every entry with its source (`admin/escalation-rules`, `references/metadata-examples.md` in `admin/assignment-rules` shows the XML), and make `None` a deliberate, documented exception.
---
## Gotcha 4: `Case.BusinessHoursId` is empty unless something sets it
**What happens:** Nothing populates the Case's calendar at creation: not the assignment rule, not Email-to-Case, not Web-to-Case. An empty field means the org default for every consumer that says "use the Case's hours".
**When it occurs:** Regional calendars exist, escalation entries are correctly set to `Case`, and every case still follows the default calendar.
**How to avoid:** A before-save record-triggered Flow on Case sets `BusinessHoursId` from the account's region, origin, or entitlement, with an explicit fallback. It runs before the assignment rule and before any timer starts. Document the mapping in the intake design (`admin/case-management-setup`).
---
## Gotcha 5: Milestones read the process calendar, not the Case calendar, unless told otherwise
**What happens:** An entitlement process carries its own business hours, and each milestone can override them. Neither reads `Case.BusinessHoursId` by default. A Case with a regional calendar can therefore escalate on the regional clock (escalation rule set to `Case`) while its first-response milestone counts on the process calendar.
**When it occurs:** Entitlements added after escalation rules, configured by a different admin.
**How to avoid:** Choose one authority per SLA policy. Either the process calendar is the contract calendar and escalation entries use `Static` to match it, or the Case calendar is authoritative and the process is set accordingly. See `admin/entitlements-and-milestones` for the process-level versus milestone-level rule.
---
## Gotcha 6: Times are stored in the calendar's own time zone, and the documented file shape cannot tell "open all day" from "closed"
**What happens:** Day windows are stored as `HH:mm:ss.SSSZ` in the calendar's `timeZoneId`, not in the deploying user's zone and not in UTC despite the `Z` suffix. The shipped `Default` calendar is 24/7 and is stored with every day as start `00:00:00.000Z`, end `00:00:00.000Z`. The Metadata API guide's second sample calendar (`bh1`) also stores its weekend days as `00:00:00.000Z` to `00:00:00.000Z`, so from the documented shape alone you cannot tell whether that pair means "open 24 hours" or "closed" (UNVERIFIED: the guide does not say; set one day to closed and one to 24 hours in Setup, retrieve, and compare before hand-writing either).
**When it occurs:** Copying a calendar from one region to another and only changing `timeZoneId`; hand-writing a weekend as midnight-to-midnight from the sample and getting a seven-day calendar.
**How to avoid:** Build calendars in Setup once, retrieve `Settings:BusinessHours`, and use the retrieved file as the template. Verify a hand-edited calendar with a clock test (`references/examples.md`, Example 4) before relying on it.
---
## Gotcha 7: Apex methods take milliseconds and ignore nothing you did not pass
**What happens:** `add`, `addGmt`, and `diff` work in milliseconds (`60 * 60 * 1000L` for one hour in the Apex Developer Guide's example). `add` returns the local time zone result and `addGmt` the GMT result of the same calculation; mixing them shifts targets by the zone offset. `isWithin` includes holidays in its check; a date on an attached holiday returns `false`. Passing a null or inactive calendar Id is a runtime error, not a fallback to the default.
**When it occurs:** Custom SLA code that passes `Case.BusinessHoursId` directly when the field can be empty; unit conversions that use seconds.
**How to avoid:** Resolve the calendar first (`BusinessHoursId != null ? BusinessHoursId : defaultId`), keep one unit helper, and test with a start time just before closing and a start time on a holiday.
---
## Gotcha 8: The settings file is the whole calendar set
**What happens:** All calendars and holidays deploy as one `Settings` member, `BusinessHours`. Deploying a hand-built file with one calendar into an org that has five is a change to the whole set, and a sandbox refresh replaces the sandbox file with production's. A calendar that is referenced by an escalation entry, an entitlement process, or a Case cannot simply disappear; deactivate rather than delete.
**When it occurs:** Deploying business hours from a scratch org into a long-lived sandbox; editing the file after a refresh from a stale branch.
**How to avoid:** Retrieve `Settings:BusinessHours` from the target org first, merge, deploy the merged file, and keep the file in source control so a refresh does not lose sandbox-only calendars.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |