Scheduler Tasks

Introduction

POM is equipped with an in-built Scheduler, that can be used to schedule batch entities at different frequencies, times and dates.

Scheduler Tasks

The basic unit of work within the Scheduler, is the Scheduler Task. By default , when a Batch Schedule is seeded or patched in POM, Scheduler tasks are automatically created by the system for the following batch entities.

A Task for the Nightly Flow.
A Task for each Flow on every Hourly Cycle.
A Task for every spreadsheet seeded invoke-able (Flow or Process) batch entity on the Standalone Cycle.

Note:

No Scheduler tasks are created automatically for custom batch entities created through the Batch Administration screen’s Create Custom Entities feature

Scheduler tasks are created by the system and cannot be removed unless their corresponding invoke-ables are removed.

Similar to Batch Jobs, the Scheduler Task metadata is kept separate from actual Scheduler Task instances. The configuration of a Scheduler Task is considered its metadata or definition, and is used at the creation of the New Scheduler Day to create a Scheduler Task instance that can run for the current Scheduler Day. Within the POM schema, a separate table stores the definition for each task defined for a Schedule.

The Scheduler Task configuration is accessible from the Scheduler Administration screen within POM. Refer to the Scheduler Administration section of the POM User Guide for additional details on how to configure Scheduler Tasks.

Access

A user must access the Scheduler Administration screen to configure the Scheduler Tasks based on the Retailer's needs. To access this screen, this user must have either of the following roles

BATCH_ADMINISTRATOR_JOB
BATCH_SCHEDULE_ADMINISTRATOR_JOB

Configuration

A Scheduler Task can be configured at the following frequencies.

Frequency	Description
DAILY	Run daily at the specified time
WEEKLY	Run every <day of a week> at the specified time. The business date of the Schedule is used here, to determine the day of the week.
ONCE	Run once at a specified date and time. The business date of the Schedule is used here, to determine the date at which the task is being run.
MONTHLY	Run on a particular day of each month at a specified time. For example, on the 15th of each month at 10pm The business date of the Schedule is used here, to determine the day of the month.
MONTHLY_START	Runs at the beginning of every month. The business date of the Schedule is used here, to determine if it is the start of the month.
MONTHLY_END	Runs at the end of every month. The business date of the Schedule is used here, to determine if it is the end of the month
MONTHLY_BY_WEEKDAY	Runs on the First/Second/Third…/Last weekday of the month. The business date of the Schedule is used here, to determine whether it is the x day of the month. For example: Second Saturday of the Month

Within each of the frequencies above, the following recurrences are supported.

Recurrence	Description
SINGLE	Will run just once at the time defined on the frequency
MULTIPLE	Will run multiple times at regular intervals starting at the time defined on the frequency

Special Restrictions

Recurring cycle supports only Daily frequency. It does not support the MULTIPLE recurrence.
Nightly cycle supports only Daily and Weekly frequencies. It does not support the MULTIPLE recurrence.
When Nightly is set up with Weekly frequency, it needs to be set up for every day of the week. This is due to the fact that when Nightly completes for a certain day, it sets up the schedule for the next business day that cannot be skipped.

Run at the Start of the Scheduler Day

The Scheduler schedules a task with no start time defined, to run immediately at the creation of a new Scheduler Day. This can be useful to schedule Jobs that need to run regularly throughout the day and that need to start running right away when the day starts.

Scheduler Task Instances

Any configuration changes made to Scheduler Tasks are activated from the next Scheduler Day onwards (similar to Batch Job configurations). The Scheduler Task instances for a given Scheduler Day can be seen by clicking on the Scheduler Tasks link on the Batch Monitoring screen. Refer to the Scheduler Tasks section within the Batch Monitoring chapter of the POM User Guide for details.

Scheduling

At the end of the Nightly Cycle, when the Scheduler Day rolls over and a new Scheduler Day is created for the next business date, Scheduler Task instances are created for those Scheduler Tasks that are ENABLED and have been configured.

Every instance is given a status and a start time (if configured) and is associated with a corresponding Scheduler Task definition (metadata) and a Scheduler Day. These instances are then processed by the Scheduler based on the configuration that is setup for each of them.

The scheduling of tasks takes place in two stages.

Stage 1 : Transform Task Definitions Into Task Instances

Each Scheduler Task definition has a status and a configuration associated with it. These task definitions are converted into task instances based on the following rules.

If the task is DISABLED, mark the task instance DISABLED.
If task frequency is ONCE, then enable the task instance only if the scheduled date matches the business date.
If task frequency is WEEKLY, then enable the task instance only if the business date matches one of the week days selected.
If task frequency is MONTHLY, then enable the task instance only if the business date matches the day of the month selected.
If task frequency is MONTHLY_START, then enable the task instance only if the business date is at the start of a month.
If task frequency is MONTHLY_END, then enable the task instance only if the business date is at the end of a month.
If task frequency is DAILY, then enable the task instance.

Stage 2 : Schedule the Enabled Task Instances

The Scheduler schedules task instances that are in the ENABLED status and have valid occurrences in the future. A task with a recurrence of SINGLE has one valid occurrence for a day. A task with a recurrence of MULTIPLE, may have many occurrences through the day.

For example, the valid occurrences for a task that starts at 3:30 and runs every 15 minutes, for a maximum of 4 times are – 3:30, 3:45, 4:00, 4:15.

The scheduling logic follows the following guidelines:

If a task has a start time defined, then the Scheduler will try to schedule the task for that time in the specified time zone region for the current day.
- If the time has passed and the task recurrence is SINGLE, then schedule it for the next day.
- If the time has passed and the task recurrence is MULTIPLE, then check if there are any valid occurrences in the future. If they exist, then schedule adjusted remaining occurrences, else schedule for the next day.
If a task has no start time defined, then schedule it for immediate execution.
Ensure compliance with daylight savings changes at the specified time zone.

To better understand the scheduling logic around valid occurrences, see the examples below:

Use Cases Expected Behavior

Use Cases	Expected Behavior
Task configured to run every 30 minutes, with `startTime` defined as 3:30 PM. No invocation limits specified.	New Scheduler Day – 5:15 PM Occurrences - 5:30 PM, 6 PM and so on.
Task configured to run every 30 minutes, with `startTime` defined as 3:30 PM. Max occurences - 10	New Scheduler Day – 5:15 PM Occurences – 5:30 pm, 6 pm, 6:30 pm, 7 pm, 7:30 pm, 8 pm Notification will be generated as the first 4 occurrences had elapsed

Task configured to run every 30 minutes, with startTime defined as 3:30 PM.

No invocation limits specified.

New Scheduler Day – 5:15 PM

Occurrences - 5:30 PM, 6 PM and so on.

Task configured to run every 30 minutes, with startTime defined as 3:30 PM.

Max occurences - 10

New Scheduler Day – 5:15 PM

Occurences – 5:30 pm, 6 pm, 6:30 pm, 7 pm, 7:30 pm, 8 pm

Notification will be generated as the first 4 occurrences had elapsed

At the end of these two stages, the necessary schedules have been setup.

One Nightly per Day

The Scheduler has an additional validation for Nightly tasks named the One Nightly per Day rule. This rule is turned on by default, meaning that the Scheduler will try to ensure that two consecutive Nightly cycles are not run on the same calendar day (based on the time zone set). For example, consider the case where the Nightly cycle is setup with the WEEKLY frequency, and is scheduled to run at 10 am on Sunday and then 7 pm on Monday. If this validation is not enforced, the Scheduler would schedule the Nightly cycle at 10 am and then again at 7 pm on Sunday itself.

In such cases, if this rule is in place, the Scheduler bumps the Nightly Cycle to the same time for the next day. A Notification is also created to signal that the Nightly has been adjusted in adherence to this rule.

Note:

As stated previously, the default is to enforce this validation. This behavior can be changed by updating the System Option EnsureOneNightlyPerDay and setting it to FALSE on the System Configuration – System Options screen.

Execution

At the scheduled time, when a Scheduler Task instance fires, the first thing it does is to perform the following validations.

Ensure the Scheduler is enabled for the Schedule.
Ensure the Schedule is not in PATCH mode.
Ensure the Scheduler Day associated with the Task instance, is in fact an active Scheduler Day.
Ensure the Nightly Cycle has not started if the task instance is configured to not run while Nightly is running.
Ensure the task has not reached its invocation limit.

Once these validations have passed, the task instance performs the following actions.

Create a new Execution Request to execute the relevant Batch entity, that was configured.
Create a Scheduler Task Run Instance, to record the Execution Request ID or any other information in case of invocation errors.

Notifications

The Scheduler generates the following Notifications, at different points of execution.

Notification Type	Description
SchedulerTaskFailed	This signals that something went wrong, when executing the Scheduler Task Instance.
SchedulerTaskSkipped	On failure to schedule an `ENABLED` task.
SchedulerTaskCancelled	This is created when the scheduler is `DISABLED`, resulting in the scheduler tasks being cancelled.
SchedulerTaskDelayed	Occurs when we try to run the task manually from the Batch Monitoring screen, and the time has passed.
SchedulerTaskOccurenceSkipped	Occurs when the Scheduler has to adjust the invocations for a task instance, as the occurrence time for some invocations has passed.
SingleNightlyPerDayValidation	This is created, when the Scheduler applies the One Nightly per Day rule to the Nightly task and bumps it by a day.

Handling Restarts

The Scheduler is capable of re-initializing itself and is therefore able to handle unexpected or scheduled server restarts or repave events. To do so, the Scheduler runs an Initializer task every 2 minutes, from when the server starts up. The objectives of this task are

Identify all SCHEDULED task instances across all the Schedules, and verify that for each of them, a timer exists. In case a timer is found, nothing needs to be done. Otherwise, the timer is created.
The Initializer also cancels timers that don’t have a corresponding task instance in SCHEDULED status.

Note:

In cases where the timer needs to be created, the Scheduler uses the same rules stated earlier for scheduling task instances. The Scheduler does what it can to ensure valid occurrences in the future are not missed.

Handling Daylight Savings

The Scheduler makes use of the ZonedDateTime classes in the JDK to perform date/time calculations specific to time zone regions. It is therefore necessary for the JDK to be always patched to the latest version, to ensure the latest time zone data is used by the Scheduler.

To better understand the behavior of the Scheduler around Daylight Savings, see the example below.

Timezone Region – Chicago, Illinois, USA

On Mar 10^th, 2024, the clock is adjusted after 1:59:59 AM to 3:00 AM, thereby moving an hour ahead. There is therefore, no 2AM on Mar 10^th (Chicago).
On Nov 5th, 2023, the clock is adjusted after 1:59:59 AM back to 1:00 AM, thereby moving an hour back. Therefore, the times between 1 AM and 2 AM occur twice on this day.

Let us consider, the following tasks scheduled at these times (CST)

Task 1 – 12:30 am
Task 2 – 1:00 am
Task 3 – 1:30 am
Task 4 – 2:00 am
Task 5 – 2:30 am
Task 6 – 3:00 am

Task - Date	Mar 9th	Mar 10th	Nov 4th	Nov 5th
Task 1 (Chicago)	12:30 AM	12:30 AM	12:30 AM	12:30 AM
Task 1 (UTC)	6:30 AM	6:30 AM	5:30 AM	5:30 AM
Task 2 (Chicago)	1:00 AM	1:00 AM	1:00 AM	1:00 AM
Task 2 (UTC)	7:00 AM	7:00 AM	6:00 AM	6:00 AM
Task 3 (Chicago)	1:30 AM	1:30 AM	1:30 AM	1:30 AM
Task 3 (UTC)	7:30 AM	7:30 AM	6:30 AM	6:30 AM
Task 4 (Chicago)	2:00 AM	3:00 AM	2:00 AM	2:00 AM
Task 4 (UTC)	8:00 AM	8:00 AM	7:00 AM	8:00 AM
Task 5 (Chicago)	2:30 AM	3:30 AM	2:30 AM	2:30 AM
Task 5 (UTC)	8:30 AM	8:30 AM	7:30 AM	8:30 AM
Task 6 (Chicago)	3:00 AM	3:00 AM	3:00 AM	3:00 AM
Task 6 (UTC)	9:00 AM	8:00 AM	8:00 AM	9:00 AM

Daylight Time start – Moves forward an hour

Daylight Time ends – Moves back an hour

Observations

On Mar 10^th, tasks scheduled between 2 AM and 3AM, run as if they were scheduled between 3 and 4 AM.
On Nov 5^th, there exists a 1.5 hour gap between the 1:30 AM and the 2 AM tasks.