Scheduler Swiftlet

Overview

The Scheduler Swiftlet enables the scheduling and execution of jobs and message deliveries within the SwiftMQ router. It provides a flexible mechanism to define time-based triggers, associate them with jobs, and optionally apply complex calendar rules for inclusion or exclusion of specific dates. Schedules can be configured to deliver messages to queues or topics, or to invoke custom jobs registered by other Swiftlets.

Features

Job Scheduling and Execution

The Scheduler Swiftlet allows users to define job schedules that specify when and how jobs should be executed. Each schedule is associated with a job group and job name, and can be enabled or disabled individually. Schedules support two main types of time expressions: at expressions for specific times, and repeat expressions for repeated execution within a time window. When a schedule triggers, the associated job is instantiated and executed, with optional runtime parameters supplied. The Swiftlet maintains a history of state transitions and exceptions for each active schedule, providing traceability and operational insight.

Time Expressions

Schedules use a flexible time expression syntax: - at expressions: Specify one or more exact times (e.g., at 10:00, 14:30:00). - repeat expressions: Define a start time, stop time, delay between executions, and optional repeat count (e.g., start 09:00 stop 17:00 delay 30m repeat 10). This enables both one-off and recurring job executions.

Job Groups and Factories

Jobs are organized into job groups. Each group contains one or more job factories, which are responsible for creating job instances. The Scheduler Swiftlet registers a default job group and job for message delivery, but other Swiftlets can register custom job factories to extend scheduling capabilities.

Schedule State and History

Each active schedule maintains a state (e.g., SCHEDULED, RUNNING, STOPPED, DISABLED, etc.) and records a history of recent state changes and exceptions. This information is available for operational monitoring and troubleshooting.

Configuration Example:

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

Calendar-Based Scheduling

Calendars provide fine-grained control over when schedules are considered valid. Each calendar can include or exclude specific days based on week days, month days, annual days, or date ranges. Calendars can also be based on other calendars, allowing for hierarchical inclusion/exclusion logic. When a schedule references a calendar, its triggers will only fire on dates considered valid by the calendar's rules.

Calendar Types and Rules

Calendars can be of type include or exclude. They support enabling week days (e.g., only Mondays and Wednesdays), month days (e.g., the 1st and 15th of each month), the last day of the month, specific annual days (e.g., holidays), and arbitrary date ranges. These rules can be combined for complex scheduling requirements.

Base Calendars

A calendar can reference a base calendar, inheriting its rules and further refining them. This allows for modular and reusable calendar definitions.

Configuration Example:

<swiftlet name="sys$scheduler">
  <calendars>
    <calendar name="workdays" type="include" enable-weekdays="true">
      <weekdays day-02="true" day-03="true" day-04="true" day-05="true" day-06="true"/>
    </calendar>
  </calendars>
</swiftlet>

Message Delivery Scheduling

The Scheduler Swiftlet provides a built-in job group and job factory for scheduled message delivery. Users can schedule messages to be delivered to a queue or topic at specific times or intervals. The message content and destination are specified as part of the schedule's parameters. The system ensures that messages are delivered reliably, and supports expiration and removal of scheduler-related message properties before delivery.

Message Sender Job

The built-in job named Message Sender retrieves the scheduled message from the internal queue, removes scheduler-specific properties, sets the appropriate destination and expiration, and delivers the message to the specified queue or topic.

Configuration Example:

<swiftlet name="sys$scheduler">
  <schedules>
    <schedule name="send-alert" enabled="true" job-group="Scheduler" job-name="Message Sender" date-from="2024-01-01" date-to="2024-12-31" time-expression="at 09:00">
      <parameters>
        <parameter name="ID" value="alert-message-id"/>
      </parameters>
    </schedule>
  </schedules>
</swiftlet>

Internal Queue Naming

• swiftmqscheduler — Request queue for scheduling messages and jobs.
• sys$scheduler — Internal queue for storing scheduled messages.

Configuration Guide

Schedule a Job Only on Workdays

Use a calendar to restrict a schedule to run only on weekdays (Monday through Friday). This is useful for business processes that should not run on weekends.

1. Define a calendar named workdays with type include and enable only Monday through Friday.
2. Create a schedule and reference the workdays calendar.

<swiftlet name="sys$scheduler">
  <calendars>
    <calendar name="workdays" type="include" enable-weekdays="true">
      <weekdays day-02="true" day-03="true" day-04="true" day-05="true" day-06="true"/>
    </calendar>
  </calendars>
  <schedules>
    <schedule name="weekday-job" enabled="true" job-group="Scheduler" job-name="Message Sender" calendar="workdays" time-expression="at 10:00"/>
  </schedules>
</swiftlet>

Define a Repeating Schedule with Limited Executions

Configure a schedule to run every 30 minutes between 09:00 and 12:00, but only repeat 5 times per day. This is useful for batch jobs with a limited number of executions.

1. Create a schedule with a repeat time expression specifying start, stop, delay, and repeat count.

<swiftlet name="sys$scheduler">
  <schedules>
    <schedule name="batch-job" enabled="true" job-group="Scheduler" job-name="Message Sender" time-expression="start 09:00 stop 12:00 delay 30m repeat 5"/>
  </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