BusinessHoursSettings Metadata Type in SFDX

Architectural Overview#

In global Service Cloud and Field Service architectures, SLA milestone clocks, Case escalation timers, and Omni-Channel support schedules must accurately reflect regional working hours and statutory holidays. The BusinessHoursSettings metadata type stores the organization’s BusinessHoursEntry schedules (such as Default, EMEA_Support_24x5, or APAC_Gold_SLA) alongside Holiday definitions in a single declarative settings file.

Architecturally, BusinessHoursSettings bridges metadata and data: while BusinessHours and Holiday can be queried via standard SOQL at runtime (and passed into System.BusinessHours Apex calculations), Salesforce exposes them in the Metadata API (BusinessHours.settings-meta.xml) so DevOps pipelines can version-control SLA operating hours alongside Case Escalation Rules and Entitlement Processes.

SFDX Directory & File Suffix#

Key Metadata Fields#

The BusinessHoursSettings metadata type contains two top-level arrays (businessHours and holidays):

Declarative XML & package.xml Examples#

SFDX Source File Example#

<?xml version="1.0" encoding="UTF-8"?>
<BusinessHoursSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <businessHours>
        <active>true</active>
        <default>true</default>
        <fridayEndTime>17:00:00.000Z</fridayEndTime>
        <fridayStartTime>09:00:00.000Z</fridayStartTime>
        <mondayEndTime>17:00:00.000Z</mondayEndTime>
        <mondayStartTime>09:00:00.000Z</mondayStartTime>
        <name>Default</name>
        <thursdayEndTime>17:00:00.000Z</thursdayEndTime>
        <thursdayStartTime>09:00:00.000Z</thursdayStartTime>
        <timeZoneId>America/New_York</timeZoneId>
        <tuesdayEndTime>17:00:00.000Z</tuesdayEndTime>
        <tuesdayStartTime>09:00:00.000Z</tuesdayStartTime>
        <wednesdayEndTime>17:00:00.000Z</wednesdayEndTime>
        <wednesdayStartTime>09:00:00.000Z</wednesdayStartTime>
    </businessHours>
    <holidays>
        <activityDate>2026-01-01</activityDate>
        <businessHours>Default</businessHours>
        <description>New Year Day Holiday</description>
        <isRecurring>true</isRecurring>
        <name>New Year Day</name>
        <recurrenceDayOfMonth>1</recurrenceDayOfMonth>
        <recurrenceMonthOfYear>January</recurrenceMonthOfYear>
        <recurrenceStartDate>2026-01-01</recurrenceStartDate>
        <recurrenceType>RecursYearly</recurrenceType>
    </holidays>
</BusinessHoursSettings>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>BusinessHours</members>
        <name>Settings</name>
    </types>
    <version>68.0</version>
</Package>

Querying via SOQL & SFDX CLI#

Because BusinessHours is exposed as a standard SObject at runtime, you can query it directly in SOQL for use in ApexClass SLA utilities or Flow actions:

SELECT Id, Name, IsActive, IsDefault, TimeZoneSidKey,
       MondayStartTime, MondayEndTime, FridayStartTime, FridayEndTime
FROM BusinessHours
WHERE IsActive = true
ORDER BY IsDefault DESC, Name ASC

Retrieve and deploy BusinessHoursSettings via Salesforce CLI:

# Retrieve BusinessHoursSettings (all schedules and holidays)
sf project retrieve start --metadata Settings:BusinessHours

# Deploy BusinessHoursSettings to a target environment
sf project deploy start --metadata Settings:BusinessHours

Senior Architect Best Practices & Gotchas#

• Holiday Recurrence Start Dates: A Holiday with <isRecurring>true</isRecurring> will fail deployment if <recurrenceStartDate> is set in the past relative to the first deployment into a new org unless properly aligned with the recurrence pattern. Prefer RecursYearly or RecursYearlyNth rules for annual holidays.
• Avoid Hardcoding BusinessHours IDs in Flows: Never hardcode an 18-character BusinessHoursId in a Flow or Apex class. Query BusinessHours by Name (which matches <name> in BusinessHours.settings-meta.xml) or IsDefault = true.
• Cannot Delete BusinessHours via Settings Deployment: Removing a <businessHours> entry from BusinessHours.settings-meta.xml and redeploying does not delete the schedule in the target org; instead, set <active>false</active> to retire an obsolete schedule.

Frequently asked questions

What is stored inside the BusinessHoursSettings metadata file?

It contains two main collections: businessHours (defining daily operating start/end times and time zones for each schedule) and holidays (defining recurring or one-off holiday exclusions).

Where is BusinessHoursSettings located in an SFDX project?

It is stored at force-app/main/default/settings/BusinessHours.settings-meta.xml in SFDX source format.

Can I retrieve a single BusinessHoursEntry without retrieving the entire BusinessHoursSettings file?

Yes, you can reference BusinessHoursEntry or MilestoneType separately, or retrieve Settings:BusinessHours to pull all business hours schedules and holidays together.

How do I query BusinessHours at runtime in Apex or SOQL?

Query the standard BusinessHours and Holiday SObjects in SOQL, and use System.BusinessHours methods like BusinessHours.diff() or BusinessHours.isWithin() in Apex.