Scheduler Swiftlet

Overview

The Scheduler Swiftlet enables time-based scheduling of jobs and message deliveries within the SwiftMQ router. It provides a flexible mechanism to define schedules, calendars, and job groups, allowing users to automate actions such as sending messages to queues or topics at specific times or intervals. The Swiftlet supports complex scheduling expressions and calendar-based inclusion/exclusion rules for fine-grained control.

Features

Job Scheduling

The Scheduler Swiftlet allows users to define job schedules that determine when specific jobs are executed. Each schedule specifies the job group, job name, time expression, optional calendar, and date range. Schedules can be enabled or disabled, and optionally log their execution events to the SwiftMQ log. The schedule supports two main time expression formats:

• at expressions: Specify one or more exact times of day (e.g., at 09:00, 17:00).
• repeat expressions: Specify a start time, stop time, delay interval, and optional repeat count (e.g., start 08:00 stop 18:00 delay 1h repeat 10).

Schedules can also define a maximum runtime, after which the job will be forcibly stopped if still running. Parameters can be passed to jobs via the schedule configuration.

Time Expressions

Time expressions control when a schedule triggers. The at expression allows specifying one or more fixed times per day (e.g., at 10:00, 14:30:00). The repeat expression enables periodic execution within a time window, with a configurable delay and optional repeat count (e.g., start 09:00 stop 17:00 delay 30m repeat 16).

Job Parameters

Schedules can pass parameters to jobs. Parameters are defined as name/value pairs and are validated against the job's parameter definitions, including mandatory checks.

Schedule State and History

Each active schedule maintains its current state (e.g., SCHEDULED, RUNNING, STOPPED, JOB ERROR) and a history of recent state changes, including timestamps and error messages if applicable.

Configuration Example:

<swiftlet name="sys$scheduler">
  <schedules>
    <schedule name="daily-report" enabled="true" logging-enabled="true" job-group="Scheduler" job-name="Message Sender" date-from="2024-01-01" date-to="2024-12-31" time-expression="at 09:00"/>
  </schedules>
</swiftlet>

Calendar Support

Calendars provide inclusion or exclusion rules that can be referenced by schedules to control on which days jobs are allowed to run. Calendars can be of type include or exclude, and can be based on another calendar (base calendar). Calendars support enabling rules for specific weekdays, month days (including the last day of the month), annual days (specific day/month combinations), and arbitrary date ranges. These rules can be combined for complex scheduling scenarios, such as excluding weekends, holidays, or maintenance windows.

Weekday, Monthday, Annual Day, and Date Range Rules

Calendars can enable or disable scheduling for specific weekdays (Sunday through Saturday), specific days of the month (1-31 and last), specific annual days (e.g., 25 December), and arbitrary date ranges (e.g., 2024-07-01 to 2024-07-15).

Base Calendars and Exclusion Logic

A calendar can reference a base calendar, inheriting its rules. The type attribute determines whether the calendar acts as an inclusion or exclusion filter. When multiple rules are enabled, a date must satisfy all enabled criteria to be considered valid for scheduling.

Configuration Example:

<swiftlet name="sys$scheduler">
  <calendars>
    <calendar name="no-weekends" type="exclude" enable-weekdays="true">
      <weekdays day-01="false" day-02="true" day-03="true" day-04="true" day-05="true" day-06="true" day-07="false"/>
    </calendar>
  </calendars>
</swiftlet>

Job Groups and Registered Jobs

Jobs are organized into job groups. Each job group contains one or more jobs (job factories), each with its own parameter definitions and description. The Scheduler Swiftlet manages job group registration and allows dynamic addition and removal of jobs. The built-in 'Message Sender' job is used for scheduled message delivery.

Message Sender Job

The 'Message Sender' job is a built-in job that delivers a previously stored message to a target queue or topic at the scheduled time. The job retrieves the message by its schedule ID, sets the appropriate destination and expiration, and sends it to the specified queue or topic. The message properties used for scheduling (prefixed with JMS_SWIFTMQ_SCHEDULER) are removed before delivery.

Configuration Example:

<swiftlet name="sys$scheduler">
  <usage>
    <job-groups>
      <job-group name="Scheduler">
        <jobs>
          <job name="Message Sender"/>
        </jobs>
      </job-group>
    </job-groups>
  </usage>
</swiftlet>

Internal Queue Naming

• swiftmqscheduler — Request queue used internally for scheduling and message retrieval.
• sys$scheduler — Internal queue used by the Scheduler Swiftlet for storing scheduled messages.

Configuration Guide

Schedule a Daily Message Delivery Except on Weekends

Use this scenario to deliver a message to a queue every weekday at 09:00, excluding weekends. A calendar is defined to exclude Saturdays and Sundays, and the schedule references this calendar.

1. Define a calendar named no-weekends with type set to exclude and enable-weekdays enabled. Set day-01 (Sunday) and day-07 (Saturday) to false, all others to true.
2. Create a schedule referencing the no-weekends calendar, with a time expression of at 09:00, and specify the job group and job name as 'Scheduler' and 'Message Sender'.

<swiftlet name="sys$scheduler">
  <calendars>
    <calendar name="no-weekends" type="exclude" enable-weekdays="true">
      <weekdays day-01="false" day-02="true" day-03="true" day-04="true" day-05="true" day-06="true" day-07="false"/>
    </calendar>
  </calendars>
  <schedules>
    <schedule name="weekday-delivery" enabled="true" calendar="no-weekends" job-group="Scheduler" job-name="Message Sender" time-expression="at 09:00"/>
  </schedules>
</swiftlet>

Schedule a Job to Run Every Hour During Business Hours

This scenario configures a job to run every hour from 08:00 to 18:00 each day. The repeat time expression is used to specify the interval.

1. Create a schedule with a time expression: start 08:00 stop 18:00 delay 1h.
2. Set the job group and job name as required.

<swiftlet name="sys$scheduler">
  <schedules>
    <schedule name="hourly-job" enabled="true" job-group="Scheduler" job-name="Message Sender" time-expression="start 08:00 stop 18:00 delay 1h"/>
  </schedules>
</swiftlet>

Configuration Reference

The top-level entity in routerconfig.xml is <swiftlet name="sys$scheduler">.

<calendars> in <swiftlet name="sys$scheduler">

Calendars

Each <calendar> entry is identified by its name attribute (the Calendar).

Parameter	Type	Default	Mandatory	Reboot Required	Description
type	String	exclude	No	No	Calendar Type (choices: include, exclude)
base-calendar	String	—	No	No	Calendar which is Base for this Calendar
enable-weekdays	Boolean	false	No	No	Enable Week Days on this Calendar
enable-monthdays	Boolean	false	No	No	Enable Month Days on this Calendar
enable-monthdays-last	Boolean	false	No	No	Enable Last Month Day on this Calendar
enable-annualdays	Boolean	false	No	No	Enable Annual Days on this Calendar
enable-dateranges	Boolean	false	No	No	Enable Dange Ranges on this Calendar

<swiftlet name="sys$scheduler">
  <calendars>
    <calendar name="..."/>
  </calendars>
</swiftlet>

<annualdays> in <calendars>

Annual Days

Each <annualday> entry is identified by its name attribute (the Annual Day).

Parameter	Type	Default	Mandatory	Reboot Required	Description
day	String	—	Yes	No	Day (choices: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31)
month	String	—	Yes	No	Month (choices: January, February, March, April, May, June, July, August, September, October, November, December)

<swiftlet name="sys$scheduler">
  <calendars>
    <calendar name="...">
      <annualdays>
        <annualday name="..." day="..." month="..."/>
      </annualdays>
    </calendar>
  </calendars>
</swiftlet>

<date-ranges> in <calendars>

Date Ranges

Each <date-range> entry is identified by its name attribute (the Date Range).

Parameter	Type	Default	Mandatory	Reboot Required	Description
from	String	—	Yes	No	From Date
to	String	—	Yes	No	To Date

<swiftlet name="sys$scheduler">
  <calendars>
    <calendar name="...">
      <date-ranges>
        <date-range name="..." from="..." to="..."/>
      </date-ranges>
    </calendar>
  </calendars>
</swiftlet>

<weekdays> in <calendars>

Week Days

Parameter	Type	Default	Mandatory	Reboot Required	Description
day-01	Boolean	false	No	No	Sunday
day-02	Boolean	false	No	No	Monday
day-03	Boolean	false	No	No	Tuesday
day-04	Boolean	false	No	No	Wednesday
day-05	Boolean	false	No	No	Thursday
day-06	Boolean	false	No	No	Friday
day-07	Boolean	false	No	No	Saturday

<monthdays> in <calendars>

Month Days

Parameter	Type	Default	Mandatory	Reboot Required	Description
day-01	Boolean	false	No	No	01.
day-02	Boolean	false	No	No	02.
day-03	Boolean	false	No	No	03.
day-04	Boolean	false	No	No	04.
day-05	Boolean	false	No	No	05.
day-06	Boolean	false	No	No	06.
day-07	Boolean	false	No	No	07.
day-08	Boolean	false	No	No	08.
day-09	Boolean	false	No	No	09.
day-10	Boolean	false	No	No	10.
day-11	Boolean	false	No	No	11.
day-12	Boolean	false	No	No	12.
day-13	Boolean	false	No	No	13.
day-14	Boolean	false	No	No	14.
day-15	Boolean	false	No	No	15.
day-16	Boolean	false	No	No	16.
day-17	Boolean	false	No	No	17.
day-18	Boolean	false	No	No	18.
day-19	Boolean	false	No	No	19.
day-20	Boolean	false	No	No	20.
day-21	Boolean	false	No	No	21.
day-22	Boolean	false	No	No	22.
day-23	Boolean	false	No	No	23.
day-24	Boolean	false	No	No	24.
day-25	Boolean	false	No	No	25.
day-26	Boolean	false	No	No	26.
day-27	Boolean	false	No	No	27.
day-28	Boolean	false	No	No	28.
day-29	Boolean	false	No	No	29.
day-30	Boolean	false	No	No	30.
day-31	Boolean	false	No	No	31.
last	Boolean	false	No	No	Last Day in Month

<schedules> in <swiftlet name="sys$scheduler">

Job Schedules

Each <schedule> entry is identified by its name attribute (the Job Schedule).

Parameter	Type	Default	Mandatory	Reboot Required	Description
enabled	Boolean	false	No	No	Schedule enabled/disabled
logging-enabled	Boolean	false	No	No	If true, start/stop are logged in SwiftMQ's log file
calendar	String	—	No	No	Apply this Calendar
job-group	String	—	Yes	No	Job Group
job-name	String	—	Yes	No	Job Name
date-from	String	now	Yes	No	From Date
date-to	String	forever	Yes	No	To Date
max-runtime	String	—	No	No	n(s|m|h), e.g. 30m
time-expression	String	—	Yes	No	(at HH:mm[:ss][, HH:mm[:ss]...]) | (start HH:mm[:ss] stop HH:mm[:ss] delay n(s|m|h [repeat n])

<swiftlet name="sys$scheduler">
  <schedules>
    <schedule name="..." job-group="..." job-name="..." date-from="..." date-to="..." time-expression="..."/>
  </schedules>
</swiftlet>

<parameters> in <schedules>

Parameters

Each <parameter> entry is identified by its name attribute (the Parameter).

Parameter	Type	Default	Mandatory	Reboot Required	Description
value	String	—	Yes	No	Value

<swiftlet name="sys$scheduler">
  <schedules>
    <schedule name="...">
      <parameters>
        <parameter name="..." value="..."/>
      </parameters>
    </schedule>
  </schedules>
</swiftlet>

Related Documents

• Streams Swiftlet