Recurring Schedules

Learn about recurring schedules within Maica and how to manage these.

Overview

Maica support the management of recurring schedules supporting the ongoing generation of either Appointments, Shifts, or Unavailabilities. The following configuration options are available when managing Recurring Schedules.

It’s important to note that Recurring Schedules cannot be set to begin in the past. They must start either today or on a future date.

Recurring Schedule Configuration available for Appointments, Shifts, and Unavailabilities.

Configuration	Description	Options
Schedule Start	The date on which the recurring schedule starts. This is a mandatory value.	Date
Schedule End	The date on which the recurring schedule ends. This is optional and, if left blank, the schedule does not end.	Date (greater than Schedule Start)
Number of	Sets a specific number of either Appointments, Shifts, or Unavailabilities to be recurring.	Number
Frequency	Sets the frequency at which the recurring schedule is executed.	Daily Weekly Monthly Quarterly Annually
Repeat Every	Sets the repetition of days at which the recurring schedule is executed.	Number of Days
Exclude Public Holidays	If selected, Maica excludes any days marked as a public holiday(s) in Salesforce.	Yes/No

Maica does not support a Fortnightly Frequency. If you wish to have a Recurring Schedule on a Fortnightly basis, please set your Frequency to Weekly, select your Schedule Day and Repeat Every 2 weeks.

Scheduled Appointment Creation Logic

Within a Recurring Schedule, Maica generates Appointments based on a Schedule Horizon and forward rolling basis. Appointment records will be created for the Schedule Horizon Date Range.

A Schedule Horizon defines the rolling time period into the future during which Maica evaluates schedules and creates corresponding Appointments. It is measured in weeks and determines how far ahead Appointments are planned and generated. You can set your desired Schedule Horizon in the Maica General Settings. For more information on setting your Schedule Horizon, click here.

The Schedule Horizon Date Range is determined based on today() + Schedule Horizon (weeks)

To further understand the Appointment Creation Logic, see the below example:

Let's say you are creating a Recurring Schedule with the following inputs,

• Schedule Horizon = 12 weeks

• Schedule Start Date = Jan 3, 2025

• Schedule End Date = Jun 3, 2025

• Frequency = Daily

• Today = Dec 3, 2024

• Schedule Status = Approved

• Master Appointment != null

• Master Appointment != Cancelled

Then, when the daily batch is run, the following occurs:

• The Schedule Horizon End Date will be calculated per below:

  • Today + 12 weeks = Feb 25, 2025

• Maica will create Appointment records for the period between the Schedule Start Date and the Schedule Horizon End Date

  • Meaning that Appointment records will be created for the period Jan 3, 2025 to Feb 25, 2025

• Furthermore, when the batch runs tomorrow (in this case, Dec 4, 2024), the next Appointment, or the Appointment on the Feb 26, 2025 will be created

• And so on

This Maica logic ensures Appointment Records are created for schedules within a rolling time horizon, maintaining consistent coverage and adapting dynamically as time progresses.

When an Appointment Schedule is created the Schedule Horizon only respects 4 weeks. This is due to Salesforce limits and timeout risks during business hours. However, the overnight Batch will always respect the 12 week Schedule Horizon as per the setting.

Schedule Evaluation Date

Maica retrieves Appointment Schedule records that will be included for Appointment processing based on a Schedule Evaluation Date field. The below information defines the field and details how the logic works in practice:

Schedule Evaluation Date: Specifies the earliest date on which Maica will include the Appointment Schedule record for evaluation to determine whether Appointment records need to be created. It is calculated as the Schedule Start Date minus the Schedule Horizon (in weeks). This ensures that the system identifies and processes Appointment Schedule records within the appropriate window for generating Appointment’s on a rolling basis. The formula is shown below.

maica__Schedule_Start_Date__c - Schedule Horizon (weeks)

Example:

• Given Inputs:

  • Schedule Horizon: 12 weeks

  • Schedule Start Date: 1st April 2025

  • Schedule End Date: 30th October 2025

  • Frequency: Weekly

  • Today: 4th December 2024

Formula:

Schedule Evaluation Date = Schedule Start Date - Schedule Horizon (weeks)

Calculation:

• Schedule Horizon = 12 weeks

  • 12 × 7 days = 84 days

• Schedule Start Date = 1st April 2025

• Subtract 84 days:

• 1st April 2025 - 84 days = 7th January 2025

• Result: Schedule Evaluation Date will be 7th January 2025.

How This Works in Practice:

• Using the example above, on 7th January 2025, Appointment records for the 1st April to 24th June 2025 (12 weeks ahead) will be created.

• As time progresses, the Appointment Schedule will be assessed daily and additional Appointment records will be created, maintaining the rolling 12-week horizon.

Please note, there is also an Under Evaluation field which indicates whether the Appointment Schedule is eligible for automated processing. The value is determined by a formula that evaluates whether the current date falls within the Schedule Evaluation Date and the Schedule End Date. This ensures that only relevant Appointment Schedules are included for processing. Used in both the Appointment Schedule (Recurring Appointment) and Unavailability automation logic, as show below.

Under Evaluation Formula:

AND(
    maica__Schedule_Evaluation_Date__c <= TODAY(),
    TODAY() <= maica__End_Date__c,
    ISPICKVAL(maica__Status__c, "Approved")
)

All conditions inside the AND() must evaluate to TRUE for the overall formula to return TRUE.

Under Evaluation Conditions:

• maica__Schedule_Evaluation_Date__c <= TODAY()

  • Ensures the Schedule Evaluation Date is on or before today's date.

• TODAY() <= maica__End_Date__c

  • Ensures today's date is on or before the End Date.

• ISPICKVAL(maica__Status__c, "Approved")

  • Checks if the picklist field maica__Status__c is set to "Approved”

Schedule Protection

Maica has logic to prevent past Scheduled Appointment being created. If the Scheduled Batch is interrupted (eg, stopped or paused) and then resumed at a later date, Maica ensures the Anchor Date is only used if the Appointment Schedule Start Date is greater than or equal to today's date. This logic prevents the creation of Appointments with dates in the past during the interrupted period.

Consider the following example:

• Today's Date = 20th November 2024

• An Appointment Schedule was configured to generate weekly Appointment records starting from 1st November 2024.

• The batch process was interrupted on 10th November 2024, after creating Appointment records for 1st November and 8th November 2024.

When the batch is resumed, Maica evaluates and sets the Anchor Date to:

• The most recent Appointment Schedule Start Date, if it is greater than or equal to today's date; or

• Today's date, if the most recent Appointment Schedule Start Date is in the past.

By covering both scenarios, the logic ensures that the Anchor Date will always be today or a future date, never a past date.

So, if today's date is 20th November 2024, the system evaluates the most recent Appointment Schedule Start Date (8th November 2024) and determines that it is in the past. As per the logic:

• The system ignores the 8th November 2024 date because it is before today's date.

• Instead, it defaults the Anchor Date to 20th November 2024 (today's date), ensuring no Appointment records are created in the past.

Maica will then begin generating Appointment records starting from the next valid future date, based on the schedule's frequency.

Things to look out for: Schedules Running Old Logic After a Package Update

When a managed Apex class used in a scheduled job is updated, Salesforce does not automatically refresh the job to use the latest version of the class. Instead, it continues to execute a cached version of the old logic, which can lead to discrepancies in behaviour.

This is a Salesforce platform behaviour and applies to any scheduled job relying on an updated Apex class. To ensure the job runs with the latest logic, it needs to be manually rescheduled after an update.

Whilst this is a Salesforce platform behaviour, Maica’s development team proactively monitors and reschedules all necessary scheduled jobs after every package update. This ensures that updates are applied smoothly, and you should experience no disruption in behaviour.

If you notice any unexpected behaviour following an update, please contact the Maica team, and we’ll ensure everything is running as expected.