Availability Calendar

Availability Calendar

The Availability Calendar controls when a doctor is bookable. Every slot the system offers to patients is derived from what's defined here. The calendar uses three entry types — Schedules, Blocks, and Overrides — which combine to produce the final availability for any given day.

Three Entry Types

Every calendar entry is one of these three types:

Schedules — Regular Availability

Schedules define the doctor's recurring working pattern. Each schedule entry has a frequency (Daily, Weekly, Monthly, or Yearly), optional day/date filters, and time windows.

A doctor can have multiple schedule entries — the system merges them automatically. This is the key to building complex availability patterns.

Frequency Types

Daily Schedule

The doctor is available every single day during the specified time windows.

Weekly Schedule

The most common pattern. The doctor is available on specific days of the week.

Examples:

• Standard weekday — Mon through Fri, 10:00 AM to 5:00 PM
• Specific days only — Mon, Wed, Fri with different time windows
• Weekend-only — Sat and Sun, 09:00 AM to 01:00 PM

Alternating Week Schedule

For doctors who rotate between clinics or work alternate weeks, set an interval on weekly schedules.

An interval of 2 means every other week. Interval of 3 means every third week. The starting week is determined by the Valid From date.

Monthly Schedule — By Date

The doctor is available on specific dates each month. Use the by month day setting to list which days of the month.

Examples:

• 1st and 15th — Visiting consultant who comes twice a month
• 1st through 10th — Doctor available only in the first 10 days of each month
• 20th, 21st, 22nd — Three specific days per month for a specialty clinic

Monthly Schedule — By Week

The doctor is available during specific weeks of the month. Use the by week number setting combined with days.

Weeks are numbered 1 through 5 based on day of month: days 1-7 = week 1, days 8-14 = week 2, days 15-21 = week 3, days 22-28 = week 4, days 29-31 = week 5. Use -1 for the last week of the month.

Examples:

• Mon-Fri of 1st week — Week 1, days Mon-Fri. Matches days 1-7 that fall on a weekday
• Mon-Fri of 2nd and 4th weeks — Weeks 2 and 4, days Mon-Fri
• Last Friday of month — Week -1 (last week), day Fri. Matches the last 7 days of the month that fall on Friday
• Every Saturday of week 1 and 3 — Weeks 1 and 3, day Sat

Yearly Schedule

Available on a specific date every year. Primarily used for recurring holiday blocks, but can also define annual special clinic days.

Example: Republic Day (Jan 26) every year — create a yearly block to automatically mark the doctor as unavailable.

Combining Multiple Schedules

A doctor can have any number of schedule entries. The system automatically merges all matching entries for any given date. This is the most powerful feature of the calendar — it lets you build complex availability from simple building blocks.

How Merging Works

On any date, the system:

1. Checks every active schedule entry for this doctor
2. Keeps all entries whose recurrence pattern matches the date
3. Collects time windows from all matching entries into a single list
4. The doctor is available during the union of all these windows

Each schedule entry is independent — they don't interfere with each other. If two entries both match a date, both contribute their time windows.

Example: Visiting Consultant with Mixed Pattern

A visiting consultant is available on the 2nd and 4th week (Mon-Fri) plus the 20th through 22nd of every month. Set this up with two schedule entries:

How this plays out in February:

Example: Different Hours on Different Days

A doctor works mornings on weekdays and full days on specific dates:

On a day where both match (e.g. March 1 which is a Friday), both time windows are collected. If the windows overlap, the slot engine produces slots covering the full merged range.

Example: Summer and Winter Rotations

Use the month filter to create seasonal schedules. The month filter works as a pre-check on any frequency — if the current month is not in the list, the entry is skipped entirely.

In June, only the summer entry matches → early morning hours. In November, only the winter entry matches → later hours. No manual switching needed.

Date Exceptions

Any schedule entry can have an exceptions list — specific dates where the schedule does not apply, even though the recurrence pattern would normally match.

• Skip one date — Doctor works every Monday, but not this specific Monday (add that date to exceptions)
• Skip a holiday — Daily schedule with Dec 25 in exceptions → no slots on Christmas
• Skip from monthly — Monthly schedule for 1st and 15th, with Mar 15 excepted → no slots on that one date

Exceptions are checked before the recurrence pattern. If the date is in the exceptions list, the entry is immediately skipped — regardless of frequency or day matching.

Multiple Time Windows

A single schedule entry can have multiple time windows in a day. This is common for doctors with a lunch break or split shifts.

Each window generates its own set of bookable slots. There are no slots during the gap.

Service-Specific Windows

Each time window can optionally be restricted to specific services. This lets a doctor offer different services at different times of day.

If no services are specified on a window, all services assigned to that doctor are available during that time.

Validity Period

Every schedule has an optional Valid From and Valid Until date. This controls when the schedule is active.

• Both set — Schedule only applies between those dates (e.g. a seasonal rotation)
• Only Valid From — Schedule starts on that date and runs indefinitely
• Neither set — Schedule applies from the beginning of time onward

This lets you set up future schedule changes ahead of time. For example, create a new schedule with Valid From = March 1 for an upcoming rotation.

Centre-Specific Schedules

If a doctor works at multiple centres, each schedule entry can be linked to a specific centre. This means the doctor can have different hours at different locations.

• Centre A — Mon, Wed, Fri from 10:00 AM to 5:00 PM
• Centre B — Tue, Thu from 09:00 AM to 1:00 PM

Blocks — Marking Time Unavailable

Blocks subtract from the schedule. When a block is active, the system removes those hours from the available slots. Blocks do not affect override entries.

One-Time Block

Block a specific date — a single day off or a partial day block.

All-Day vs Partial Block

Recurring Blocks

Blocks can also follow a recurring pattern, just like schedules.

• Daily recurring block — Block the same hours every day (e.g. admin time 12:00–1:00 PM daily)
• Weekly recurring block — Block specific days each week (e.g. every Saturday afternoon for research)

Recurring blocks also support intervals. For example, block every other Friday for training sessions.

Block Reason Types

The reason type is for categorisation and reporting. Patients see a general 'Doctor unavailable' message — they do not see the specific reason.

Centre-Specific Blocks

• Centre-specific block — Doctor is unavailable only at that centre (still bookable at other centres)
• Global block (no centre) — Doctor is unavailable at all centres

Overrides — One-Time Custom Hours

An override replaces the regular schedule for a specific date. When the system finds an override for a date, it ignores the schedule entirely and uses only the override's time windows.

When to Use Overrides

• Doctor wants to work different hours on a specific day
• Doctor wants to add availability on a day they normally don't work
• Special clinic day with extended hours
• Reduced hours for a specific date without blocking

How Overrides Work

How the System Calculates Final Availability

For each date in a slot search, the system follows this exact sequence:

1. Check for overrides — If an override exists for this date, use its time windows. Skip to step 4.
2. Get all matching schedules — Find every active schedule entry whose recurrence pattern matches this date and whose validity period includes this date. Collect all their time windows into one list.
3. Apply blocks — Find all active block entries matching this date. Subtract blocked time windows from the schedule windows. If an all-day block exists, the result is zero availability.
4. Intersect with centre hours — The remaining doctor windows are intersected with the centre's working hours. Only the overlap produces slots.
5. Generate slots — The final time windows are divided into discrete appointment slots based on the configured slot duration and buffer time.

Example: A Typical Wednesday

Doctor's calendar:

• Schedule — Weekly, Wed, 09:00 AM – 01:00 PM and 03:00 PM – 06:00 PM
• Block — Wed Dec 18, partial, 03:00 PM – 06:00 PM (training)
• No override for this date

Result:

1. No override found — use schedule
2. Schedule matches Wednesday — windows: 09:00–13:00 and 15:00–18:00
3. Block matches — subtract 15:00–18:00 → remaining: 09:00–13:00 only
4. Intersect with centre hours (08:00–20:00) → 09:00–13:00 passes
5. Generate 15-minute slots: 09:00, 09:15, 09:30, ... , 12:45

Example: Multiple Schedule Merge

Doctor's calendar — two entries:

• Schedule A — Monthly, weeks 2 and 4, Mon-Fri, 09:00 AM – 05:00 PM
• Schedule B — Monthly, days 20-22, 09:00 AM – 05:00 PM

On Feb 21 (Friday, week 3, day 21):

1. No override found
2. Schedule A: week 3 not in [2, 4] → no match. Schedule B: day 21 in [20, 21, 22] → match
3. Windows from Schedule B: 09:00 AM–05:00 PM
4. No blocks → full window available
5. Intersect with centre hours → generate slots

On Feb 10 (Monday, week 2, day 10):

1. No override found
2. Schedule A: week 2 in [2, 4], Monday in [Mon-Fri] → match. Schedule B: day 10 not in [20, 21, 22] → no match
3. Windows from Schedule A: 09:00 AM–05:00 PM
4. Result: available 9-5 from schedule A alone

Common Calendar Patterns

Real-world scheduling patterns and how to set them up:

Deactivating Calendar Entries

Calendar entries are not deleted — they are deactivated. Deactivating an entry stops it from affecting future slot generation, but the record is preserved for audit purposes.

• Deactivating a schedule removes future availability for those days
• Deactivating a block restores the original schedule availability
• Deactivating an override reverts to the normal schedule for that date

What's Next?

Now that you understand the calendar, learn how it feeds into slot search in How Slot Search Works, or explore the full list of scheduling settings in Appointment Settings.