The Scheduler Utility

Introduction

The scheduler utility allows users with AllegroGraph superuser privileges to schedule times when scripts will be run. Such events can be scheduled to run once only or repeatedly (daily, monthly, or on the same day every week). Email addresses can be specified to receive notifications of success or failure and to see the results of running the scripts.

Events can be scheduled in AGWebView, with agtool, and using the HTTP/REST interface. In this document we will mostly discuss the WebView interface, with some notes on the agtool and the HTTP/REST interface at the end.

As said, only users with AllegroGraph superuser privileges can schedule events. Write permission in the scheduler directory (defined below) is also needed to write scripts.

The scheduler maintains a log of scheduled events and their results. All scheduled events and their results are visible to any AllegroGraph superuser, both events they scheduled and events scheduled by others.

As well as scheduling times for a script to be run, email tests can be made by scheduling a notify event. When a notify event runs, a test success email is sent to a specified success list of email addresses, and a test failure email is sent to a failure list of addresses. These emails are simply tests and say

This is sample successful response to event "testevent5".  
Time: 2018-10-10T08:05:00-08:00

sent to the success list and

This is sample failing response to event "testevent5".  
Time: 2018-10-10T08:05:01-08:00

sent to the failure list. If these emails arrive, that means notifications of successes or failures when running scripts will likely also arrive.

Scheduling script events is described below in the Script Events section. Scheduling email test events is described below in the Notify Events section.

Security

Scripts are run by the uid which is running the AllegroGraph server. This means that the script acts as if run by an AllegroGraph user with AllegroGraph superuser privileges. For that reason, only users with AllegroGraph superuser privileges can schedule events.

Administrators may consider restricting write permission in the scheduler directory (where scripts to be run must be located) in order to ensure scripts are appropriate and that scripts added by different users do not conflict with each other.

Accessing the scheduler in AGWebView

The scheduler page is accessed by selecting Event Scheduler from the menu displayed by clicking on the user name to the upper right in New WebView and the User [username] menu in the traditional WebView menu bar:

That displays the Scheduler page which, in traditional WebView, displays existing events and allows scheduling new ones and in New WebView displays existing events and, in the upper right, has a link to schedule new events. From then on things are similar and we describe the traditional WebView look and feel.

That page has two fields: Scheduled Events and Scheduler Log. The Scheduled Events field lists events scheduled in the future. The Scheduler Log field lists event scheduling, deletions, and results.

Users without AllegroGraph privileges do not see the Event Scheduler menu item.

Buttons under Scheduled Events

Refresh: Refresh the display of scheduled events.
Delete: Delete selected scheduled events.
Add Event: Schedule a new event.

Button under Scheduler Log

The single Refresh button refreshes the log.

Script Events

In order to schedule a script event, the SchedulerDir configuration directive must have a value when the server is started. Its value must be a directory. See Top-level directives for the event scheduler in Server Configuration and Control for information on this directive. The scripts to run must be in that directory or in a subdirectory of that directory. If you try to schedule a script event when that directive does not have a value, an error will be signaled.

In our example, our configuration file agraph.cfg contains the following:

SchedulerDir /mydir/ag650/scheduler/

As it happens, /mydir/ag650/ is the AllegroGraph root directory but it is not required that the SchedulerDir be located there.

We have a repository named kennedy and we create a script file in /mydir/ag650/scheduler/ named myscript.sh with the following contents:

#!/bin/bash  
/mydir/ag650/bin/agtool load http://test:xyzzy@localhost:11650/repositories/kennedy /home/myhomedir/kennedy.nt

We set the mode of the file so it can be executed:

% chmod +x /mydir/ag650/scheduler/myscript.sh

Now we are ready to schedule a script event.

Log into AGWebView as an AllegroGraph superuser
Display the Scheduled Events page by choosing Event Scheduler from the User [username] menu.
Click on the Add Event button under the (possibly empty) list of scheduled events.
Fill in the dialog that appears.
Click on the Add Event button at the bottom of the dialog.

Here is a picture of the dialog filled in so that (1) myscript.sh will run at the appointed time, and (2) a success or failure notification will be emailed to [email protected] after the system has (tried to) run the script:

A filled in script event dialog

Here are the fields we filled in (some already have suggested values):

Day: the date and time when the script should be run for the first time. The time must be in the future. Time is browser time, not server time. There is a drop-down calendar that can be used to fill in the date, which can also be typed in.
Repeat every: events can be scheduled to repeat. That is not set up in this example. See Repeating events below for more information.
Repeat until: See Repeating events below for more information.
Do: the choices are script (chosen) and notify (see Notify events below).
Script file to run: the name of the script file along with its path relative to the directory specified by the SchedulerDir configuration directive. The file must be in that directory or one of its subdirectories. Simply specifying a absolute path of a script file will not work. The mode of the specified file must allow execution. (So myscript.sh for a file in the SchedulerDir directory, and subdir/myscript.sh for a file in the subdir subdirectory of the SchedulerDir. /mydir/ag650/scheduler/myscript.sh will not work even if SchedulerDir is /mydir/ag650/scheduler/. ../another-dir/myscript.sh also will not work.)
Event Name: the name of the event. This name identifies it in the schedule on the Scheduled Events page and also in email notifications. This field is optional. A name will be generated if it is not set.
Email on success: if specified, the email address(es) to which success notification emails will be sent. This field is optional. Multiple addresses are comma-separated.
Email on failure: if specified, the email address(es) to which failure notification emails will be sent. This field is optional. Multiple addresses are comma-separated.

The Close Dialog button closes the dialog. The Add Event button schedules the event.

We click the Add Event button and the Scheduled Events page looks like this:

Scheduled Events page with one event scheduled

We see our event is the Scheduled Events list and we see in the Scheduler Log that we scheduled the event.

When the event runs, here is what the Scheduled Events page looks like (after the Scheduled Events and the Scheduler Log have been refreshed):

Event schedule after and event runs

We see that the Scheduled Events list is now empty and two more entries have been added to the log: that the event ran and that it succeeded. Because we requested that an email be sent on success, [email protected] received an email with subject Event "load1" ran successfully and body

2018-10-10T13:37:03| Load finished 1 source in 00:00:01 (1.00 seconds).   
Triples added:         1,214, Average Rate:    1213.00 tps.

Notify Events

A notify event simply tests whether emails that inform about success or failure are properly sent and received. The emails do not contain any additional (user-specified) information. If email addresses are specified for both Email on success and Email on failure, two emails will be sent. After a notify event runs, the log will indicate the result.

In order for a notify event to run, the SchedulerSMTPConfig configuration directive must be set. See Top-level directives for the event scheduler in Server Configuration and Control for information on this directive. That directive also must be set for success and failure emails to be sent in scripting events.

The value of the SchedulerSMTPConfig directive must be an SMTPHost ID defined by an SMTPHost directive.

If SchedulerSMTPConfig is not set, it is still possible to schedule notify events. The system assumes the server will be stopped and restarted with the directive set prior to the event being run. If that does not happen, the event will fail and that will be noted in the Scheduler log along with the reason.

If SchedulerSMTPConfig is not set, the following message is displayed at the top of the Schedule Event dialog:

Note: There is no SchedulerSMTPConfig in the AllegroGraph  
configuration file (usually agraph.cfg). As a result notifications  
cannot be sent until the the server is restarted with a  
schedulerSMTPConfig specified.

Repeating events

You can cause an event to be regularly repeated by specifying values for these boxes in the Add Event dialog:

Repeat every: Initially never, can be one of day, month, and Monday through Sunday. Then the event will be repeated on that schedule (every day, month, or specified day of the week).
Repeat until: If specified, the value must be a day in the future. After that day, the event stops running. If that day is a day on which the event is supposed to run (say the event should run every Monday and the Repeat until date is a Monday), the event runs on that day but never again.

Other Event Scheduling Notes

If the server is not running when an event is supposed to run, the event does not run when the server is restarted. Instead the event is logged as Not Run with the reason Time for the event passed without the event being run.
The event log is not persistent. When the server is stopped, log entries are cleared. The log contains fairly minimal information about events and what happens to them. Emails sent on success or failure are more informative, with success emails containing the output of the script along with other information.
Events that are scheduled to run in the future are remembered if the server is stopped. Events whose time is past when the server is restarted do not run (as said above) but the fact that they did not run is noted in the log. Events whose time is still in the future when the server is restarted will run at their appointed time just as if the server never stopped (assuming the server is indeed running at the event time).

Scheduling an event with agtool

The agtool general command utility is the general tool for running most AllegroGraph tasks at a command prompt. The agtool program takes as its first argument the utility to be run. agtool scheduler performs tasks associated with the event scheduler.

As with all agtool utilities, passing the --help argument provides information about how the utility is to be used:

bin/agtool scheduler --help  
Usage: agtool scheduler COMMAND [ OPTIONS ] ...  
 
where COMMAND is one of:  
* help - Display scheduler usage.  
* delete-events - Delete events.  
* log - Display the log of events  
* events - List pending events.  
* create-event - Create a new event.  
 
To describe a particular command run:  
agtool scheduler COMMAND --help

As shown, the commands mimic what is available using the AGWebView interface, allowing display of pending events (what is shown in the Scheduled Events area), the log (what is shown in the Scheduler Log area), and event creation and deletion. Here are a couple of examples:

bin/agtool scheduler create-event --script myscript.sh \  
--server http://test:xyzzy@localhost:11650 \  
--dateTime 2018-10-12T09:37:00-07:00 \  
--emailSuccess [email protected] --emailFailure [email protected]

This creates a script event to run at 9:37 AM PDT. We look at the events scheduled (command events, the results have been truncated for readability):

bin/agtool scheduler events --server http://test:xyzzy@localhost:11650  
EventID   eventName   owner        runAt [...]   action   script [...]  
 41  ev-2-3748350948   test   2018-10-12T09:37:00-07:00  script   myscript.sh

After 9:37 AM has past, here is the log:

bin/agtool scheduler log --server http://test:xyzzy@localhost:11650 LogID Time EventID EventName Owner Type Message 1 2018-10-12T08:35:49-08:00 41 ev-2-3748350948 test New Event Create new event to run at 2018-10-12T09:37:00-07:00 2 2018-10-12T08:37:00-08:00 41 ev-2-3748350948 test Run run event 3 2018-10-12T08:37:04-08:00 41 ev-2-3748350948 test Script Success script completed with code 0

Note: OS Authentication does not apply to agtool scheduler: If the user who starts the AllegroGraph server runs agtool on the machine where the server is running, many utilities run as if run by an AllegroGraph user with superuser privileges. This is known as OS Authentication. It does not apply to the agtool scheduler utility. Thus in the commands above, the username and password are specified in the server specification provided as the value of the --server argument.

Scheduling an event with the HTTP/REST interface

The HTTP reference document lists all HTTP/REST services for AllegroGraph. The services relating to the event scheduler start with scheduler/.