AppointmentAssignmentPolicy Metadata Guide

Architectural Overview#

The AppointmentAssignmentPolicy metadata type defines the resource distribution algorithm used by Salesforce Scheduler when assigning ServiceAppointment records to eligible ServiceResource staff (such as wealth advisors, branch bankers, or healthcare clinicians).

Instead of overloading the first alphabetically returned advisor, architects configure an AppointmentAssignmentPolicy to calculate resource utilization across a defined duration and balance incoming bookings fairly across the qualified pool.

Directory Location and File Suffix#

Key Metadata Fields#

Declarative XML and Package Manifest Examples#

Below is an AppointmentAssignmentPolicy configured to load-balance appointments across wealth advisors based on total appointment duration over a 2-week rolling window:

<?xml version="1.0" encoding="UTF-8"?>
<AppointmentAssignmentPolicy xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Advisor Duration Load Balance</masterLabel>
    <policyApplicableDuration>TwoWeeks</policyApplicableDuration>
    <policyType>LoadBalancing</policyType>
    <utilizationFactor>TotalAppointmentsDuration</utilizationFactor>
</AppointmentAssignmentPolicy>

<?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>
    <version>68.0</version>
</Package>

Querying AppointmentAssignmentPolicy via SOQL#

You can query AppointmentAssignmentPolicy records directly in SOQL to verify active load-balancing configurations:

SELECT Id, DeveloperName, MasterLabel, PolicyType,
       PolicyApplicableDuration, UtilizationFactor
FROM AppointmentAssignmentPolicy
ORDER BY DeveloperName

Senior Architect Best Practices and Gotchas#

1. Deploy Before AppointmentSchedulingPolicy: Because AppointmentSchedulingPolicy references AppointmentAssignmentPolicy by developer name when resource assignment rules are enabled, always include both metadata types in your package.xml or deploy AppointmentAssignmentPolicy first.
2. Choose Duration vs. Count Wisely: Use TotalAppointmentsDuration when appointment lengths vary widely (e.g., 15-minute check-ins mixed with 90-minute mortgage reviews). Use NumberOfAppointments only when all work type durations are uniform.
3. License Requirement in Scratch Orgs: Deploying AppointmentAssignmentPolicy to a scratch org requires the LightningScheduler feature flag in config/project-scratch-def.json.

Frequently asked questions

Where are AppointmentAssignmentPolicy files stored in SFDX?

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

How does AppointmentAssignmentPolicy work with AppointmentSchedulingPolicy?

An AppointmentSchedulingPolicy references an AppointmentAssignmentPolicy via its appointmentAssignmentPolicy field to decide which eligible service resource receives an appointment.

What utilization CalculationDuration values are supported?

Valid utilization calculation durations enable Salesforce Scheduler to evaluate existing appointment loads over a rolling window when balancing assignments across resources.

Can I query AppointmentAssignmentPolicy via SOQL?

Yes, AppointmentAssignmentPolicy is available as a standard and Tooling API object to inspect PolicyType, UtilizationFactor, and MasterLabel.