Universal Messaging Scheduling : Writing Schedule Scripts
Universal Messaging scheduling works by interpreting scripts written using a simple grammar. Administrators of realms can deploy as many scheduling scripts as they wish to each Realm Server.
This section will cover the basic structure of a Universal Messaging scheduling script, and then show how to write a script and deploy it to the Realm Server.
Follow the links below to view the guide for each of these:
Scheduling Grammar
The grammar for scheduling scripts is extremely simple to understand. The script must conform to a predefined structure and include elements that map to the grammar expected by the Realm Server Scheduler Engine.
In its simplest form the Universal Messaging scheduler syntax starts with the command 'scheduler'. This tells the parser that a new scheduler task is being defined. This is followed by the name of the scheduler being defined, this is a user defined name. For example:
scheduler myScheduler {
}
Within this structure, triggers and tasks are defined. A task is the actual operation the server will perform, and it can be executed at a certain time or frequency, or when a condition occurs. Within the scheduler context the following verbs can be used to define tasks to be executed.
declare : Used to define the name of a trigger for later user
initialise : Is the first thing run when a scheduler is started (also run when the realm server starts up)
every : Used to define a time/calendar based event
when : Used to define a conditional trigger and the list of tasks to execute when it fires
else : Used after a conditional trigger that will fire if the condition evaluates to false
The following shows the basic grammar and structure of a scheduling script.
/*
Comment block
*/
scheduler <User defined Name> {
declare <TRIGGER_DECLARATION>+
initialise {
<TASK_DECLARATION>+
}
/*
Time based tasks
*/
every <TIME_EXPRESSION> {
<TASK_DECLARATION>+
}
when ( <TRIGGER_EXPRESSION> ) {
<TASK_DECLARATION>+
} else {
<TASK_DECLARATION>+
}
where :
TRIGGER_DECLARATION ::= <TRIGGER> <NAME> (<TRIGGER_ARGUMENT_LIST>)
TRIGGER_ARGUMENT_LIST ::= Valid comma separated list of arguments for the trigger
TRIGGER_EXPRESSION ::=
<TRIGGER_EXPRESSION> <LOGICAL_OPERATOR> <TRIGGER_EXPRESSION> | <TRIGGER> | <NAME> <COMPARISON_OPERATOR> <VALUE>
TIME_EXPRESSION ::=
<HOURLY_EXPRESSION> | <DAILY_EXPRESSION> | <WEEKLY_EXPRESSION> | <MONTHLY_EXPRESSION> | <YEARLY_EXPRESSION>
HOURLY_EXPRESSION ::= <MINUTES>
DAILY_EXPRESSION ::= <HOUR> <COLON> <MINUTES>
WEEKLY_EXPRESSION ::= <DAYS_OF_WEEK> <SPACE> <HOUR> <COLON> <MINUTES>
MONTHLY_EXPRESSION ::= <DAY_OF_MONTH> <SPACE> <HOUR> <COLON> <MINUTES>
YEARLY_EXPRESSION ::= <DAY_OF_MONTH> <HYPHEN> <MONTH> <SPACE> <HOUR> <COLON> <MINUTES>
MINUTES ::= Minutes past the hour, i.e. a value between 00 and 59
HOUR ::= Hour of the day, i.e. a value between 00 and 23
DAYS_OF_WEEK ::=
<DAY_OF_WEEK> | <DAY_OF_WEEK> <SPACE> <DAY_OF_WEEK>
DAY_OF_WEEK ::= Mo | Tu | We | Th | Fr | Sa | Su
DAY_OF_MONTH ::= Specific day of the month to perform a task, i.e. a value between 01 and 28
MONTH ::= The month of the year, JAN, FEB, MAR etc.
NAME ::= The variable name for a trigger
COMPARISON_OPERATOR ::= > | => | < | <= | == | !=
LOGICAL_OPERATOR ::= AND | OR
COLON ::= The ":" character
SPACE ::= The space character
HYPHEN ::= The "-" character
+ ::= indicates that this can occur multiple times
VALUE ::= Any valid string or numeric value.
Declarations
The declarations section of the script defines any triggers and assigns them to local variable names. The grammar notation defined above specifies that the declaration section of a schedule script can contain multiple declarations of triggers. For example, the following declarations section would be valid based on the defined grammar:
declare Config myGlobalConfig ("GlobalValues");
declare Config myAuditConfig ( "AuditSettings");
declare Config myTransConfig ( "TransactionManager");
The above declarations define 3 variables that refer to the the Config trigger. The declared objects can be used in a time based trigger declaration, conditional triggers and to perform tasks on.
Initialise
The initialise section of the schedule script defines what tasks are executed straight away by the server when the script is deployed. These initial tasks are also executed every time the Realm Server is started. An example of a valid initialise section of a schedule script is shown below:
initialise {
Logger.report("Realm optimisation script and monitor startup initialising");
myAuditConfig.ChannelACL("false");
myAuditConfig.ChannelFailure("false");
myGlobalConfig.MaxBufferSize(2000000);
myGlobalConfig.StatusBroadcast(2000);
myGlobalConfig.StatusUpdateTime(86400000);
myTransConfig.MaxTransactionTime(3600000);
Logger.setlevel(4);
}
The example above ensures that each time a server starts, the tasks declared are executed. Using the variables defined in the declarations section, as well as the Logger task, the server will always ensure that the correct configuration values are set on the server whenever it starts.
Every Clause
The every clause defines those tasks that are executed at specific times and frequencies as defined in the grammar above. Tasks can be executed every hour at a specific time pas the hour, every day at a certain time, every week on one or more days at specific times or day, every month on a specific day of the month and a specific day of the year.
The grammar above defines how to declare an every clause. Based on this grammar the following examples demonstrate how to declare when to perform tasks :
Hourly Example (Every half past the hour, log a message to the realm server log)
every 30 {
Logger.report("Hourly - Executing Tasks");
}
Daily Example (Every day at 18:00, perform maintenance on the customerSales channel )
every 18:00 {
Logger.report("Daily - performing maintenance");
Store.maintain("/customer/sales");
}
Weekly Example (Every week, on sunday at 17:30, purge the customer sales channel)
every Su 17:30 {
Logger.report("Weekly - Performing Purge");
Store.purge("/customer/sales");
}
Monthly Example (Every 1st of the month, at 21:00, stop all interfaces and start them again)
every 01 21:00 {
Logger.report("Monthly - Stopping interfaces and restarting");
Interface.stopAll();
Interface.startAll();
}
Yearly Example (Every 1st of the January, at 00:00, stop all interfaces and start them again)
every 01-Jan 00:00 {
Logger.report("Yearly - Stopping interfaces and restarting");
Interface.stopAll();
Interface.startAll();
}
When Clause
The when clause defines a trigger that evaluates a specific value and executes a task if the evaluation result is 'true'. The grammar for the when clause is defined above. The following example shows a valid when clause :
when (MemoryManager.FreeMemory < 30000000) {
Logger.report("Memory below 30M, performing some clean up");
FlushMemory(true);
}
The above example will trigger the Realm Server JVM to call garbage collection when the amount of free memory drops to below 30MB.
Else Clause
The else clause defines an alternative action to the when clause if the when clause evaluates to 'false'. The grammar for the else clause is defined above. The following example shows a valid when clause :
when (MemoryManager.FreeMemory < 30000000) {
Logger.report("Memory below 30M, performing some clean up");
FlushMemory(true);
} else {
Logger.report("Memory not below 30M, no clean up required");
}
The above example will trigger the Realm Server JVM to call garbage collection when the amount of free memory drops to below 30MB.
To view a sample scheduling script, see the section
Scheduler Examples.