Scheduling custom server tasks

i2 Analyze supports the development of custom 'tasks' that the server executes on a user-defined schedule. A task is simply a Java class that implements a specific interface and performs a custom action when invoked.

Creating a custom task

The task class must implement the IScheduledTask interface, which is provided by the disco-api.jar file in the deployment toolkit.

The IScheduledTask interface defines the following methods:

  • run()

    The run() method contains the code that performs the custom action. This method is called periodically, based on the schedule specified in the deployment properties file.

  • onStartup()

    The onStartup() method contains any necessary start-up or initialization code. It also receives an IScheduledTaskObjects parameter that provides access to other i2 Analyze APIs that can be used inside the running task. For example, the scheduler tracer can be used for logging, and the alert manager can be used to send alerts.

    This method is called whenever the server initializes an instance of a task, such as when it starts.

  • close()

    The close() method contains any necessary tear-down or finalization code. This method is called whenever the server removes an instance of a task, such as when it stops.

Note: Writing implementations of the onStartup() and close() methods is optional. They have default implementations that do nothing.

If the custom task fails for any reason, you can control the subsequent behavior by throwing a CustomTaskFailedException from the run() method. Depending on how the exception is constructed, the server might re-run the task immediately, or when it is next scheduled, or never.

Note: If an exception other than a CustomTaskFailedException escapes from the run() method, the custom task is canceled and will not run again until the scheduler is reinitialized - when the server is restarted, for example.

Deploying a custom task

To deploy a custom task, the Java class (and any supporting classes) must be packaged in a .jar file. You must then copy this .jar file to the configuration part of the toolkit. Place it the WEB-INF/lib sub-folder of the opal-services fragment, in the toolkit/configuration/fragments folder.

Note: A new fragment specifically for custom tasks is also an option, provided that it is also added to the topology.xml file for the deployment.

Configuration

In order for the i2 Analyze server to discover the custom task, entries that identify it must be present in one of the settings files. A typical location for these entries is the toolkit/configuration/fragments/opal-services/WEB-INF/classes/DiscoServerSettingsCommon.properties file.

The new entries have two parts, in the following format:

CustomTaskScheduler.<TaskName>.Class=<ImplementationClass>
CustomTaskScheduler.<TaskName>.Expression=<CronExpression>

Here, <TaskName> is a name that identifies a particular task instance; <ImplementationClass> is the fully qualified class name for the implementation of that task; and <CronExpression> is a cron schedule expression for when the task should run.

The format of the cron expression is:

<minute> <hour> <day-of-month> <month> <day-of-week>

For example, a cron expression of 0 0 * * * results in a task running at midnight every day. See the UNIX cron format documentation for more information.

The following settings define two different tasks that use two different classes, on two different schedules:

CustomTaskScheduler.AlertUsersBeforeDeletingCharts.Class=com.example.alert.ScheduledTask
CustomTaskScheduler.AlertUsersBeforeDeletingCharts.Expression=0 0 * * *

CustomTaskScheduler.TableCleaner.Class=com.example.cleaner.CleanupTask
CustomTaskScheduler.TableCleaner.Expression=0 */4 * * *

Deployment

When the .jar file is copied into the toolkit, and the DiscoServerSettingsCommon.properties file is updated with the custom task class name and the cron schedule, the task is ready for deployment to the i2 Analyze server.

To deploy the custom task to the i2 Analyze server, run setup -t deployLiberty to update the configuration with your changes. Then, to set up the task to run according to its defined schedule, run setup -t startLiberty.

Monitoring a custom task

The scheduler log stores information about the state of all configured tasks, including when a task was last run, when it will next run, whether it has failed, and so on.

The scheduler log can be found in the IBM_i2_Scheduler.log file, inside the i2 Analyze server.

Note: If a custom task is configured to use the scheduler tracer (IScheduledTaskObjects.getSchedulerTracer()) in its onStartup() method, then anything logged through that object is also written to the IBM_i2_Scheduler.log file.