AppointmentSchedulingPolicy Metadata Guide

Architectural Overview#

The AppointmentSchedulingPolicy metadata type is the central rule engine for Salesforce Scheduler. Whenever a customer or contact center agent invokes a Salesforce Scheduler Flow or the /connect/scheduling/available-territory-slots REST API, the referenced AppointmentSchedulingPolicy dictates how candidate time slots and resources are filtered.

Architecturally, AppointmentSchedulingPolicy controls whether the engine checks standard Salesforce Calendar Event records, external Exchange/Google calendars, exact skill level thresholds, primary versus secondary service territories, and resource load-balancing policies.

Directory Location and File Suffix#

Key Metadata Fields#

Declarative XML and Package Manifest Examples#

The following example configures a retail banking scheduling policy with 30-minute start intervals, Salesforce calendar conflict checking, skill enforcement, and load balancing:

<?xml version="1.0" encoding="UTF-8"?>
<AppointmentSchedulingPolicy xmlns="http://soap.sforce.com/2006/04/metadata">
    <appointmentAssignmentPolicy>Advisor_Duration_Load_Balance</appointmentAssignmentPolicy>
    <appointmentStartTimeInterval>30</appointmentStartTimeInterval>
    <isOrgCalendarUsed>true</isOrgCalendarUsed>
    <isPrimaryMemberUsed>true</isPrimaryMemberUsed>
    <isRelocationUsed>true</isRelocationUsed>
    <isSecondaryMemberUsed>false</isSecondaryMemberUsed>
    <isSkillHierarchyUsed>true</isSkillHierarchyUsed>
    <isSkillUsed>true</isSkillUsed>
    <isTerritoryMembershipUsed>true</isTerritoryMembershipUsed>
    <masterLabel>Retail Branch Scheduling Policy</masterLabel>
</AppointmentSchedulingPolicy>

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

Querying AppointmentSchedulingPolicy via SOQL#

Audit all scheduling policies in your org using standard SOQL:

SELECT Id, DeveloperName, MasterLabel, AppointmentStartTimeInterval,
       IsOrgCalendarUsed, IsSkillUsed, IsSkillHierarchyUsed,
       IsTerritoryMembershipUsed, ExtCalEventHandlerId
FROM AppointmentSchedulingPolicy
ORDER BY DeveloperName

Senior Architect Best Practices and Gotchas#

1. External Calendar Handler Timeouts: When binding an Apex class to extCalEventHandler, remember that synchronous callouts to Microsoft Graph or Google Calendar execute during live slot generation. Implement aggressive caching or batch availability queries so slot loading stays under 3 seconds.
2. Keep appointmentStartTimeInterval Coarse for High-Volume Portals: Setting appointmentStartTimeInterval to 5 or 10 minutes across hundreds of service resources multiplies the CPU cost of slot calculation. Use 30 or 60 minutes for public Experience Cloud guest scheduling flows.
3. Include Dependent Apex and Assignment Policies: If your AppointmentSchedulingPolicy references both an appointmentAssignmentPolicy and an extCalEventHandler Apex class, deploy all three components in the same package manifest.

Frequently asked questions

Where are AppointmentSchedulingPolicy files stored in an SFDX project?

They are stored in force-app/main/default/appointmentSchedulingPolicies/ with the file suffix .appointmentSchedulingPolicy-meta.xml.

How does Salesforce Scheduler know which AppointmentSchedulingPolicy to use?

Screen Flows and REST API calls pass the DeveloperName of the AppointmentSchedulingPolicy into the scheduling component or getAppointmentCandidates API endpoint.

What is the difference between extCalEventHandler and isIncludeConfirmationEmail?

extCalEventHandler specifies an Apex implementation that reads external calendar busy times, while Salesforce Event management settings control whether Salesforce calendar events are checked.

Can I query AppointmentSchedulingPolicy via SOQL?

Yes, you can query the AppointmentSchedulingPolicy object in SOQL to inspect flags such as IsOrgCalendarUsed, IsTerritoryMembershipUsed, and AppointmentStartTimeInterval.