Scheduling appointments

The appointment engine is xMatix's general booking model: one Appointment record per booking, placed on a dated slot that a branch's slot template releases, and holding the people, vehicles or bays its appointment type requires.

To book a product demo, test drive or service appointment from a lead, opportunity or case, use Product demos and appointments. That everyday flow uses its own branch time slots. The engine on this page is separate. It is configured in the CRM Settings app and its bookings are listed in the CRM app.

Overview

The engine has four parts. Each one is a list you can open from the App Launcher:

The product-demo record is also shown as Appointment in some places. Both can appear when you search the App Launcher for "Appointment". This page covers the record that has Subject, Appointment Type and Slot fields.

When to use it

Use the engine when bookings must respect real capacity. Typical cases:

• a branch can serve only so many visits per hour;
• each booking needs a free advisor, demo vehicle or bay;
• some kinds of appointment need lead time, a cancellation cutoff or a reschedule limit.

For a simple demo or test drive booked from a lead or opportunity, the product demo flow is the one with ready-made screens.

How xMatix handles it

• Slots are released by a background sweep. When Enable appointment scheduling sweeps is on, an hourly job creates slots from every active template, from today to the release horizon. A date produces no slots in these cases:
  • it is outside the template's effective dates;
  • its weekday capacity is 0;
  • it falls outside the branch's working days;
  • it is a holiday for that branch or for the whole organization.
• Capacity is claimed when the appointment is saved. A booking on a slot takes one unit of the slot's capacity in a single database step. If the slot is full, the save is refused; the engine never overbooks silently. In the same save, the type's required resources are claimed.
• Status follows a fixed lifecycle. Illegal status changes are refused. Final statuses cannot be changed. Cancelling, rescheduling, a no-show or deleting the appointment gives the slot unit and the resources back.
• A second job runs every 15 minutes while the switch is on. It expires unfinished booking holds and marks overdue appointments No Show.

Prerequisites

• The CRM product licence. The background jobs skip an organization without it.
• The Sales module enabled, with Enable appointment scheduling sweeps turned on if you want slots released automatically (see Configuration).
• Business Hours with a time zone on every branch that takes bookings, plus its Holidays. Slot times are worked out in the time zone of the branch's business hours. A branch with no business hours is treated as UTC.
• Forms. No Create or View form ships for appointments, appointment types, slot templates or bookable resources. Until an administrator designs one under *Setup → Metadata → entity → Layouts*, two things happen:
  • New shows "No form is set up for entity";
  • existing records open as a read-only field list.

  Without a designed form, records can also be created through the data API.

  Procedure

  Step 1 — Create an appointment type (admin)

  Open Appointment Type (CRM Settings) and create a type, for example "Test drive". At a minimum, set:

  • Default Duration (min). It defaults to 30 and must be greater than zero.
  • Category.
  • Location Modes Allowed, for example Branch,Onsite. Leave it empty to allow all modes.
  • Resource Requirements, if bookings must claim resources (see the Fields table).

  Then set the booking policy: Min Lead Time (hrs), Max Advance (days), Cancellation Cutoff (hrs), Max Reschedules, Overbook Allowance (%) and Auto No-Show After (min). Zero turns each of these off.

  The save is refused when a value is out of range or the resource requirements are malformed (see Common problems).

  Step 2 — Create a slot template for each branch (admin)

  Open Appointment Slot Template (CRM Settings) and create a template with these values:

  • Branch (required).
  • Start Time and End Time in branch-local time.
  • Slot Duration (min). Leave it empty to make the whole window one slot.
  • Interval (min): the gap between slot starts. Leave it empty for back-to-back slots.
  • Capacity Mode.
  • Maximum Capacity, plus any per-weekday capacities.

  Set Appointment Type to keep the slots for one type. Left empty, any type can use them, but no overbooking allowance is added to them.

  The template is active by default. Its slots appear on the next hourly sweep.

  Step 3 — Check the released slots (admin)

  After the sweep has run, open Appointment Slot and filter by the template or branch. Check these four cases:

  • an ordinary weekday has the start times, Capacity and Overbook Allowance you expect;
  • a weekday set to 0 has no slots;
  • a holiday has no slots;
  • Start (UTC) and End (UTC) convert back to the branch's local times.

  To take one slot off sale, set its Status to Blocked. The sweep never overrides Blocked or Recalled.

  Step 4 — Register bookable resources (admin)

  Most resources are created for you:

  • saving a service bay creates its Facility resource;
  • allocating a technician on a service time sheet creates their Person resource.

  For anything else, such as a demo vehicle, open Bookable resource and create a record:

  1. Choose a Kind and link exactly one matching record: Person links a Resource, Asset links an Asset, Facility links a Service Bay.
  2. Set Branch, Concurrent Capacity (how many overlapping bookings it can serve; at least 1) and, if needed, Effective From and Effective To.

  A resource with no branch can serve every branch.

  Step 5 — Book an appointment

  Create an Appointment. Choose these fields:

  • Appointment Type (required);
  • a Slot;
  • Location Mode, which defaults to Branch;
  • the links the booking is about, such as Account, Contact, Lead, Opportunity, Case, Service Order or Delivery Order.

  When you pick a slot, the appointment takes its start, end, branch and time zone from the slot. If you don't pick a slot, enter Scheduled Start and Scheduled End yourself; a branch appointment also needs a Branch. If you leave Subject empty, it takes the type's label.

  On save, the appointment is created with status Scheduled unless you chose Requested. The slot's Booked count goes up by one. One resource booking is created for each required resource, covering the appointment plus the type's buffers.

  Step 6 — Move it through the day

  Change Status as the appointment progresses. Some changes also fill in a time stamp:

  Change to	Allowed from	What else happens
  Scheduled	Requested	Nothing else. A Requested appointment already holds its slot unit and resources.
  Confirmed	Scheduled	Confirmed At is stamped
  Checked In	Scheduled, Confirmed	Checked In At is stamped
  In Progress	Scheduled, Confirmed, Checked In	Actual Start is stamped
  Completed	Scheduled, Confirmed, Checked In, In Progress	Actual Start and Actual End are stamped. The slot and resource claims are kept as history.
  Cancelled	any status that is not final	The slot unit and resources are released. The cutoff check applies.
  No Show	Scheduled, Confirmed	No-Show Marked At is stamped. The slot unit and resources are released.
  Rescheduled	Scheduled, Confirmed	The slot unit and resources are released. The cutoff check applies.

  Completed, Cancelled, No Show and Rescheduled are final.

  Step 7 — Reschedule

  A reschedule is a new appointment. Follow these steps:

  1. Create the replacement appointment with Rescheduled From set to the original. Its Reschedule Count becomes the original's count plus one. The save is refused once the type's Max Reschedules is exceeded.
  2. Set the original appointment's Status to Rescheduled. Nothing does this for you, so until you do, the original keeps its slot unit.

  Fields

  Appointment Type

  Field	What it means	Notes
  Label	The type's name	Becomes the default Subject of its appointments
  Category	Kind of booking	Product Demo, Test Drive, Service Visit, Pickup / Dropoff, Delivery, Consultation, Site Visit, Other
  Icon, Color	Presentation	—
  Is Active	Marks the type in use	Defaults to on. Booking does not check it, so an inactive type can still be booked.
  Default Duration (min)	Length of a booking without a slot or an end time	Defaults to 30. Must be greater than zero.
  Buffer Before (min), Buffer After (min)	Preparation and clear-down time claimed on resources around the booking	Cannot be negative
  Resource Requirements	What each booking must claim	A JSON list, for example [{"role":"Advisor","kind":"Person","count":1},{"role":"Demo vehicle","kind":"Asset","assetCategory":"Demo","count":1}]. Kind is Person, Asset or Facility. You can narrow it with skillName (Person), assetCategory (Asset) or bayType (Facility). mandatory defaults to true.
  Min Lead Time (hrs)	How soon a booking may start	0 means no limit. Checked when the appointment is created.
  Max Advance (days)	How far ahead a booking may start	0 means no limit. Checked when the appointment is created.
  Cancellation Cutoff (hrs)	Hours before start during which Cancel and Reschedule are refused	0 means no cutoff. The window ends at the start time.
  Max Reschedules	Maximum length of a reschedule chain	0 means no limit
  Overbook Allowance (%)	Extra bookings allowed on top of slot capacity	0–100. Applied only to slots from templates scoped to this type.
  Requires Customer Confirmation	Records whether the type expects the customer to confirm	Stored only. No step enforces it.
  Auto No-Show After (min)	Minutes after the scheduled end before an unstarted booking becomes No Show	0 means the organization fallback is used
  Applicable Entities	Record types the appointment may be about	Stored only. Not enforced.
  Location Modes Allowed	Comma-separated list from Branch, Onsite, Virtual	Empty allows all. Enforced when the appointment is created.
  Reminder Offsets	Reminder points in minutes before the start	Stored only. The engine sends no reminders.

  Appointment Slot Template

  Field	What it means	Notes
  Label, Display Name	Name of the pattern	Display Name becomes the label of the slots it releases
  Branch	Where the capacity is	Required
  Appointment Type	Keeps the slots for one type	Empty means any type can use them, with no overbooking allowance
  Start Time, End Time	The daily window in branch-local time	Both required. End must be after start.
  Slot Duration (min)	Length of each slot	Empty means the whole window is one slot. If set, it must be greater than zero.
  Interval (min)	Step between slot starts	Empty or 0 means back-to-back slots
  Capacity Mode	How slot capacity is worked out	Fixed (the template's numbers, the default), Resource Derived (the free bookable resources that day), Min Of Both
  Maximum Capacity	Capacity per slot on any weekday without its own number	Defaults to 0. With no weekday numbers, the template releases nothing.
  Monday Capacity … Sunday Capacity	Per-weekday capacity	Overrides Maximum Capacity. 0 closes that day.
  Is Active	Whether the sweep uses the template	Defaults to on
  Effective From, Effective To	Dates the template applies	To cannot be before From
  Release Horizon Override (days)	How far ahead this template releases slots	1–365. Empty means the organization setting.
  Applicable To Item, Applicable To Item Group	Product scope	Only one of the two may be set. Slot release and booking do not use them.

  Appointment Slot

  Field	What it means	Notes
  Slot Template, Branch, Appointment Type	Where the slot came from	Copied from the template
  Slot Date, Start (UTC), End (UTC), Time Zone	When the slot runs	Stored in UTC
  Capacity	Bookings the slot can take	Recomputed by every sweep
  Overbook Allowance	Extra bookings above capacity	Capacity × the type's overbook percentage, rounded up
  Booked	Live bookings on the slot	Kept by the booking engine and recounted by every sweep. Don't edit it.
  Reserved	Units held by booking holds	Don't edit it
  Status	Released, Blocked, Closed, Recalled	Only Released slots can be booked
  Overcommitted	The slot has more bookings than its capacity now allows	Set by the sweep. A person must move or cancel bookings.

  Bookable resource

  Field	What it means	Notes
  Label	Display name	—
  Kind	Person, Asset or Facility	Required. Must match the one linked record.
  Resource, Asset, Service Bay	The underlying record	Link exactly one
  Branch	Home branch	Empty means it can serve any branch
  Business Hours	Working-hours reference	Stored only. Availability does not check it.
  Concurrent Capacity	Overlapping bookings it can serve	Defaults to 1. Must be at least 1.
  Is Active, Effective From, Effective To	When the resource can be claimed	To cannot be before From

  Appointment

  Field	What it means	Notes
  Subject	The booking's title	Defaults to the type's label
  Appointment Type	The policy that applies	Required
  Status	Lifecycle position	Requested, Scheduled, Confirmed, Checked In, In Progress, Completed, Cancelled, No Show, Rescheduled. Defaults to Scheduled.
  Source Channel	Where the booking came from	Web, Mobile, Portal, Agent, Walk-In, API
  Scheduled Start, Scheduled End	When it happens	Taken from the slot when one is chosen. Otherwise required. End must be after start.
  Time Zone, Duration (min)	Presentation zone and length	Taken from the slot and type
  Actual Start, Actual End	When it really ran	Stamped by In Progress and Completed
  Location Mode	Branch, Onsite, Virtual	Defaults to Branch. Must be allowed by the type.
  Branch	Where a branch appointment happens	Required for Branch mode. Taken from the slot.
  Address, Location, Meeting URL	Where an onsite or virtual appointment happens	Stored as entered
  Slot	The capacity it uses	Must be Released, at the same branch, and not reserved for another type
  Regarding Entity, Regarding Record, Regarding	The record the appointment is about	Regarding is not filled in automatically
  Cancellation Reason	Why it was cancelled	Customer Request, No Longer Required, Resource Unavailable, Weather, Other
  Rescheduled From, Reschedule Count	The reschedule chain	The count is set on save
  Confirmed At, Checked In At, No-Show Marked At	Status time stamps	Filled in by the status changes
  Customer Confirmation, Reminder Last Sent, Reminder Count	Confirmation and reminder tracking	Nothing fills these in
  Outcome Notes, Outcome Rating	How it went	Free entry
  Field Serviceable, Visit	Field-plan link	Stored only. Visit plans do not read them.
  Account, Contact, Partner Account, Opportunity, Service Order, Lead, Case, Delivery Order, Asset, Item	The records involved	Asset is the customer's asset, not a demo vehicle (demo vehicles are claimed as resources)

  Business rules

  • Creating an appointment is refused when any of these is true:
    • there is no valid type;
    • there are no start and end times, or the end is not after the start;
    • a branch appointment has no branch;
    • the location mode is not allowed for the type;
    • the start breaks the type's minimum lead time or maximum advance;
    • the slot is missing, not Released, at another branch, or reserved for another type;
    • the reschedule source is missing or over its limit;
    • the status is not one of Requested, Scheduled, Confirmed, Checked In or In Progress.
  • Slot capacity. A booking succeeds only while Booked + Reserved is less than Capacity + Overbook Allowance.
  • Resource claims. For each requirement, a resource is eligible when all of these hold:
    • it is active and of the right kind;
    • it is effective at the start of the claim;
    • it belongs to the appointment's branch or to no branch;
    • it matches the skill, asset category or bay type, if the requirement names one.

    It is free when its overlapping bookings are fewer than its Concurrent Capacity. The least-loaded free resource is chosen, then the first by name. The first resource claimed is marked primary. A mandatory requirement with too few free resources refuses the save. A requirement that isn't mandatory is skipped.

    • Changing the slot or the times of an appointment that still holds capacity releases its claims and takes new ones.
    • Deleting an appointment that still holds capacity releases its slot unit and resources.
    • Resource Derived capacity is the total Concurrent Capacity of the matching active resources at the branch (or with no branch), divided by the count each booking needs. The lowest result across the type's mandatory requirements is used. People with approved leave that day are left out. A type with no requirements counts Person resources, one per booking.
    • Closed dates. If a date that already has released slots becomes closed (a new holiday, a weekday set to 0, the template's dates changed, or no resource supply), the sweep sets those slots to Closed with capacity 0. Appointments already on them stay, and the slot is flagged Overcommitted. If the date opens again, its slots are released again.
    • Past slots. Released slots whose end has passed are set to Closed.
    • Recount. Each sweep recounts Booked from the live appointments.
    • Holds. The booking-hold API can hold a slot unit for the Booking hold TTL (minutes). Saving an appointment does not use up the hold: the held unit stays reserved until the hold is released or expires.
    • Auto no-show. Scheduled or Confirmed appointments whose scheduled end is older than the margin become No Show. The margin is the type's Auto No-Show After (min) or, if that is 0, the organization fallback. Their capacity is then released.

    Example

    A dealership's main branch offers 45-minute test drives from 10:00 to 18:00, with one advisor and one demo vehicle per drive.

    1. The administrator creates the type "Test drive": Category Test Drive, Default Duration 45, Buffer After 15, Min Lead Time 2, Cancellation Cutoff 4, Max Reschedules 2. Its Resource Requirements are [{"role":"Advisor","kind":"Person","count":1},{"role":"Demo vehicle","kind":"Asset","assetCategory":"Demo","count":1}].
    2. They create the template "Main branch test drives" for the branch, with Appointment Type "Test drive", 10:00–18:00, Slot Duration 45, Capacity Mode Min Of Both, Maximum Capacity 3 and Sunday Capacity 0.
    3. They register two demo vehicles as Asset bookable resources at the branch. Two advisors already exist as Person resources.
    4. After the next sweep, each Monday to Saturday has ten slots: 10:00, 10:45 and so on, up to 16:45. Each slot has capacity 2, the lower of 3 and the two vehicles. Sundays have none.
    5. A sales executive books the 11:30 slot on Thursday for a prospect. The slot shows Booked 1. One advisor and one vehicle are claimed from 11:30 to 12:30, which includes the 15-minute buffer after.
    6. The prospect calls on Thursday at 09:00 to cancel. That is inside the 4-hour cutoff, so the change to Cancelled is refused. The executive marks the appointment No Show after the slot instead, which releases the slot unit and both resources.

    Training

    Practice exercise

    In a sandbox, do the following:

    1. Create a type with Default Duration 30 and no resource requirements.
    2. Create a template for one branch with 09:00–11:00, Slot Duration 30, Maximum Capacity 1 and the type selected.
    3. After the hourly sweep, book two appointments on the same 09:30 slot.

    Expected result: the first save succeeds and the slot shows Booked 1. The second is refused with "The selected slot is fully booked. Please pick another slot." Set the first appointment to Cancelled: Booked returns to 0 and the second booking now succeeds.

    Quick reference

    • Types, templates, slots and bookable resources are in CRM Settings; appointments are in CRM.
    • No slots appear until Enable appointment scheduling sweeps is on and an hourly sweep has run.
    • A template with Maximum Capacity 0 and no weekday numbers releases nothing.
    • Only Released slots can be booked. Set a slot to Blocked to stop sales.
    • Final statuses: Completed, Cancelled, No Show, Rescheduled.
    • Completed keeps its claims. Cancelled, No Show, Rescheduled and deleting release them.
    • Rescheduling means creating a new appointment and then marking the old one Rescheduled.
    • Is Active on a type does not stop bookings.

    Permissions

    Profile	Appointment, Appointment Type, Appointment Slot Template, Appointment Slot, Bookable resource
    System Admin	Full access
    Sales Manager	Full access
    Sales Executive	Full access

    These are the shipped grants. Other profiles have no access to these records until an administrator grants it under Security profiles. In the shipped profiles, the CRM Settings app is visible to System Admin, Sales Manager and Standard User. See Security profiles.

    Configuration

    The organization settings are on Setup → Feature Hub → Sales → Settings, in the Scheduling group:

    Setting	Default	Effect
    Enable appointment scheduling sweeps	Off	Turns on the hourly slot release and the 15-minute maintenance sweep. With it off, appointments can still be created against existing slots or with typed times, but no slots are released, no holds expire and no one is marked No Show automatically.
    Slot release horizon (days ahead)	30	How many days ahead slots are released (1–90). A template's Release Horizon Override (days) replaces it for that template.
    Booking hold TTL (minutes)	10	How long a booking hold keeps a slot unit reserved (1–120)
    Auto no-show after (minutes past end, 0 = off)	0	Fallback margin for types whose Auto No-Show After (min) is 0 (0–1440)

    The sweeps also need the Sales module enabled and the CRM licence.

    Other things that shape scheduling:

    • Branch business hours. Their time zone and working days decide slot times and closed days. See Holidays.
    • Holidays. Holidays for the branch, and holidays with no branch or partner, close a date.
    • Service bays. Saving a bay keeps its Facility bookable resource up to date. See Service bays.
    • Forms. Design Create and View layouts for the scheduling entities under Setup → Metadata.

    Common problems

    "No slots are released for my branch"

    Work through these checks in order:

    1. Is the switch on, and is the Sales module enabled?
    2. Is the template active and inside its effective dates?
    3. Does the weekday have a capacity above 0? With a Maximum Capacity of 0, every weekday without its own number is closed.
    4. Is the date a working day and not a holiday?
    5. With Resource Derived or Min Of Both capacity, are matching active resources available at the branch?

    Then wait for the next hourly sweep.

    "The selected slot is fully booked. Please pick another slot."

    Booked plus Reserved has reached Capacity plus Overbook Allowance. Unexpired booking holds also count against it. Pick another slot, or raise the template capacity and wait for the sweep.

    "The selected slot is not open for booking."

    The slot is Blocked, Closed or Recalled. Closed slots are past slots or dates that became closed.

    "The selected slot belongs to a different branch." / "The selected slot is reserved for a different appointment type."

    The appointment's Branch or Appointment Type does not match the slot. Choose a slot from the right template.

    "No free Advisor available for this time (0 of 1 needed)."

    A mandatory resource requirement could not be met. The message names the requirement's role, or its kind if no role is set. Every eligible resource is fully booked for that time (buffers included), or none is active, effective and at the branch. Add a resource, raise its Concurrent Capacity, or pick another time.

    "This appointment type needs at least N hour(s) of lead time." / "…can be booked at most N day(s) ahead."

    The start time breaks the type's booking policy. Pick a later or an earlier slot.

    "Illegal status transition Scheduled → Requested." / "Appointment is Completed; terminal appointments cannot change status."

    The status change is not in the lifecycle table, or the appointment is already final. To reopen a cancelled booking, create a new appointment.

    "Cancellation window closed N hour(s) before start."

    You are inside the type's Cancellation Cutoff (hrs). Wait until the start time has passed and record No Show, or have an administrator change the type.

    "This appointment has already been rescheduled the maximum N time(s)."

    The reschedule chain has reached Max Reschedules.

    "A slot shows Overcommitted"

    The slot now has more bookings than its capacity allows, or its date was closed after bookings were made. Move or cancel the extra appointments. The flag clears on the next sweep.

    Appointment type save errors

    • "Default duration must be greater than zero."
    • "Buffers cannot be negative."
    • "Overbook percent must be between 0 and 100."
    • "Policy values cannot be negative."
    • "Every resource requirement needs a count of at least 1."
    • "Unknown resource kind '…'. Use Person, Asset or Facility."
    • "Resource requirements must be a JSON array of {role, kind, count} objects."

    Correct the field the message names.

    Slot template and bookable resource save errors

    • "Start and end times are required."
    • "End time must be after start time."
    • "Slot duration must be greater than zero (or empty for a single whole-window slot)."
    • "Capacities cannot be negative."
    • "Release horizon override must be between 1 and 365 days."
    • "Scope the template to an item OR an item group, not both."
    • "Exactly one of Resource, Asset or Service Bay must be linked."
    • "Concurrent capacity must be at least 1."

    Correct the field the message names.

    "No form is set up for Appointment"

    No Create layout ships for the scheduling entities. An administrator can design one under Setup → Metadata → Appointment → Layouts.

    Common questions

    Does this replace the demo booking on leads and opportunities?

    No. The Book product demo and Book appointment buttons on leads, opportunities and cases create a product-demo record. They hold capacity on the branch's own time slots, not on this engine's slots. A product-demo record can link to an Appointment, but the two booking flows are configured separately. If you need everyday booking screens, use Product demos and appointments. Use this engine where you have designed forms for it or book through the data API.

    Does the engine send reminders or ask the customer to confirm?

    No. Reminder Offsets and Requires Customer Confirmation on the type, and the Customer Confirmation and reminder fields on the appointment, are stored but nothing acts on them. If you need reminders, build them with an automation or use activities with reminders. Record a customer's confirmation by changing the status to Confirmed.

    Why can I still book a type I made inactive?

    Booking does not check Is Active on the appointment type. To stop new bookings of a type:

    1. Deactivate its slot templates, or set their future slots to Blocked.
    2. Make sure no unscoped template (one with no appointment type) offers slots at the branch.

    What happens to the slot when an appointment is completed?

    Nothing is released. The slot is in the past and the claims stay as history of who and what was used. Only Cancelled, No Show, Rescheduled or deleting an appointment gives capacity back.

    Do bookable resources respect working hours or leave?

    Booking checks only that a resource is active, inside its effective dates, at the branch and not fully booked. The Business Hours field is not consulted. Approved leave is taken into account only when a Resource Derived or Min Of Both template works out how much capacity a slot has.

    Related topics

    • Product demos and appointments
    • CRM configuration reference
    • CRM troubleshooting
    • Holidays
    • Service bays
    • The data API
    • Security profiles
    • Appointment — entity reference