This describes how to use the Task Planner public API to create, remove or execute tasks.

To use the Task Planner API you need to create your own plugin which has taskplanner as a dependency.

@PluginInfo( 
id = "myPlugin", 
dependencies = "taskplanner", 
...

See Plugins Guide for instructions how to create your own plugin.

To manage your task, the class com.inet.taskplanner.server.api.TaskPlanner is the central point where you add or remove tasks. The class com.inet.taskplanner.server.api.TaskDefinition represents a single task.

Tasks can be added to and removed from the Task Planner. See the API documentation of the classes for how to set up tasks with triggers, jobs and result actions.

The TaskDefinition only contains settings of your task, it does not contain execution or status information.

Many predefined components like triggers and result actions come with a builder class which simplifies the construction of these components. We recommend using those Builder classes.

• com.inet.taskplanner.server.api.trigger.CronTriggerBuilder
• com.inet.taskplanner.server.api.trigger.FileChangeTriggerBuilder
• com.inet.taskplanner.server.api.trigger.ServerStartTriggerBuilder
• com.inet.taskplanner.server.api.trigger.TimeTriggerBuilder
• com.inet.taskplanner.server.api.action.EmailResultActionBuilder
• com.inet.taskplanner.server.api.action.FileSystemResultActionBuilder
• com.inet.taskplanner.server.api.action.NextTaskActionBuilder
• com.inet.taskplanner.server.api.action.PrintResultActionBuilder

This sets up a task which generates a report once a week at 10 am (on the current weekday) and sends it to some recipients via email. Note that this example uses the Render Reports plugin.

TaskDefinition task = new TaskDefinition( "Send Reports every Week" );
task.setDescription( "Send the request report every two weeks to Steve" );
 
TriggerDefinition triggerDefinition = new TimeTriggerBuilder().withHourAndMinute( 10, 00 ).withRepeating( RepeatInterval.WEEKLY ).create();
task.addTrigger( triggerDefinition );
 
// create job definition
JobDefinition job = new JobDefinition( ReportJobFactory.EXTENSION );
job.setProperty( UrlConstants.REPORTS, "file:C:/report/request.rpt" );
job.setProperty( UrlConstants.EXPORT_FMT, Engine.EXPORT_HTML );
 
// optional prompts
PromptDescription[] prompts = new PromptDescription[1];
prompts[0] = new PromptDescription( "surname", null, Field.STRING, "Steve" );
job.setProperty( ReportJobFactory.PROMPTS, new com.inet.lib.json.Json().toJson(prompts) );
 
task.addJob( job );
 
ResultActionDefinition emailAction = new EmailResultActionBuilder( "Request Report", "This is the weekly request report. --- ONDA Inc.---", "steve.smith@dummydata.com", "d.smith@dummydata.com" ).create();
task.addResultAction( emailAction );
 
TaskPlanner.getInstance().addTask( task, GUID.valueOf("<TaskOwnerGUID>") );

In some circumstances you may want to perform some task just once and forget it afterwards. In this case, the method com.inet.taskplanner.server.api.TaskPlanner.executeTask(TaskDefinition, String) can be used. This will only execute the jobs and actions without saving any settings or execution information.

TaskDefinition task = new TaskDefinition( "Send Server Warning" );
ResultActionDefinition emailAction = new EmailResultActionBuilder( "Server needs help", "The server needs your attention", "webadmin@dummydata.com" ).create();
task.addResultAction( emailAction );
 
TaskPlanner.getInstance().executeTask(task, "System");

Note that the execution is not performed synchronously - if you want to wait until the execution is done then you must wait on the Future returned by the executeTask method.

Each task belongs to - and will be executed by - the owner. If you have activated System Permissions in your application, then you need to make sure that the owner of a task has the appropriate permissions to execute the configured actions. See the description of the triggers, jobs and result actions for information which permissions are required.

In order to verify whether your settings are correct you can invoke the validate method on your TaskDefinition object. Note that this does not detect missing permissions.

To acquire execution information about a task, use the method com.inet.taskplanner.server.api.TaskPlanner.getTaskExecution(GUID). This includes past execution times, task owner, and other values.

A task is persisted automatically when it is added to the Task Planner. The tasks are stored in the user data of the task owner. If you delete the user data of a user, then you will also delete its tasks. If you backup the user data, then it will include the user's tasks.

To get the next scheduled time of execution of time triggers, do the following:

TriggerDefinition timeTriggerDefinition = new TimeTriggerBuilder().withHourAndMinute( 10, 30 ).withRepeating( RepeatInterval.DAILY ).create();
List<ZonedDateTime> nextExecutionTimes = new TimeTriggerFactory().getNextExecutionTimes( timeTriggerDefinition );

and for cron triggers, please use:

TriggerDefinition cronTriggerDefinition = CronTriggerBuilder.create( "30 10 * * ?" );
List<ZonedDateTime> nextExecutionTimes = new CronTriggerFactory().getNextExecutionTimes( cronTriggerDefinition );