Author: Franz Incorporated

Copyright (c) 2005 - 2026 Franz, Incorporated
Last updated 27 May 2026 at 10:34

# The Scheduler Utility

- Documentation Index
  - Release Notes
  - Quick Start
  - SSL/TLS Quick Start
  - Introduction
  - Setup and Configuration
    - Download
    - Server Installation
    - Server Configuration and Control
    - WebView
    - Database Upgrading
    - Managing Users
  - Server Management
    - Performance Tuning
    - Deleting Duplicate Triples
    - Purging Deleted Triples
    - Auditing
    - Managing Users
    - Replication
    - Point-in-Time Recovery
    - Transaction Log Archiving
    - Security Overview
    - Security Implementation
  - Tools
    - agtool
    - Data Loading
    - Data Export
    - Backup and Restore
    - Querying
    - RDFS++
    - Materializer
    - Event Scheduler
    - SHACL
  - Details
    - Triple Indices
    - Freetext Indices
    - Encoded IDs
    - Connection Pooling
    - N-dimensional Geospatial Overview
    - 2-D Geospatial
    - Temporal
    - Social Network
    - JavaScript
    - Datatypes
    - Data Conversion (Rapper)
    - Stored Procedures
    - Triple Attributes
    - Lineparse Format
  - Querying
    - SPARQL documentation summary
    - SPARQL Reference
    - SPIN
    - SPARQL Magic Properties
    - Prolog
  - 3rd-party tools
    - Solr text Indices
    - MongoDB integration
    - TopBraid Composer Plugin
    - Cloudera
  - Client APIs
    - Gruff
    - GraphTalker
    - REST/HTTP interface
    - HTTP reference
    - Javadocs (Sesame and Jena)
    - Python API
    - Lisp Reference
    - JavaScript
  - Tutorials
    - N-dimensional Geospatial
    - SPARQL Tutorial
    - Java Sesame
    - Java Jena
    - Python Sesame
    - Lisp
    - Prolog
    - More...
  - Other
    - Conferences and Seminars
    - Source Code on Github
    - Amazon EC2
    - Copyrights
  - Franz, Inc.

- Introduction
- Security
- Accessing the scheduler in WebView
- Script Events
- Notify Events
- Repeating events
- Other Event Scheduling Notes
- Scheduling an event with agtool
- Scheduling an event with the HTTP/REST interface

Documentation Index

## 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 WebView

The scheduler page is accessed by selecting Event Scheduler from the menu displayed by clicking on the user name to the upper right in 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.

1. Log into AGWebView as an AllegroGraph superuser
2. Display the Scheduled Events page by choosing Event Scheduler from the User [username] menu.
3. Click on the Add Event button under the (possibly empty) list of scheduled events.
4. Fill in the dialog that appears.
5. 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 myemail@franz.com after the system has (tried to) run the script:

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:

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):

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, myemail@franz.com 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 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

1. 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.

2. 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.

3. 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 myemail@franz.com --emailFailure myemail@franz.com

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/.