The scheduler is an Ebase Server component that can be used to routinely execute both the provided Ebase scheduled tasks or customer written scheduled tasks. The scheduler supports both single (once only) executions and also periodic executions: either hourly, daily, weekly or monthly. In addition, execution of a scheduled task can be triggered from an external system or from an operating system script. Each scheduled task execution produces a task log which can be viewed online via the Ebase Designer.

Scheduler execution and startup parameters

The scheduler is a component of the Ebase Server and is started automatically when the server is started. It is activated periodically as specified in the Ufs.schedulerWakeupInterval parameter in the UFSSetup.properties file, and then executes any tasks with a next execution date less than or equal to the current date and time. Ufs.schedulerWakeupInterval defaults to 10 minutes if not specified. (See Ebase Startup Parameters for more information)

Maintaining scheduled tasks and viewing task logs

Scheduler administration is a component of the Ebase Designer and is accessed via the Tools menu (Tools -> Scheduler). It provides all the facilities necessary to maintain scheduled tasks:

Display of scheduled tasks
Creation and maintenance of scheduled tasks
Association of triggers with tasks
Display of task logs

The initial display is shown below. The scheduled tasks are sorted in order of their next execution time and date.

To edit an existing task, double click on it, or select the task and click Edit task. To create a new task, click the New Task button. In both cases, the scheduled task maintenance dialog shown below is displayed.

Program information

Task id: is a unique numerical id automatically assigned by the system.

Description: should be used to describe the function of the scheduled task

Program: either select a supplied Ebase provided scheduled tasks from the dropdown list or enter the full Java class name of a custom scheduled task. When a program is entered, the system will attempt to find the specified program and present a list of parameters that the program accepts.

Program parameters: this is a list of all parameters that can be passed to the selected program. Only the Value column can be entered and a valid value should be set according to the Type i.e.

Type	Values
Character	Any value
Integer	Any integer value e.g. 1234, 12
Numeric	Any numeric value e.g. 1.234
Boolean	true or false

Values for all required parameters must be specified

Schedule Information

Choose a schedule type from the radio button options. Once only tasks are periodically deleted from the database if they have no next execution date specified. If None is selected, the task will not be automatically scheduled for execution regardless of the next execution date and time fields. None should be used for triggered tasks that do not also need to be scheduled by time/date.

Interval is enabled for schedule types in seconds, minutes, hours and days. This is the amount of time in the respective schedule type that the trigger will wait until next execution. Example: A schedule type of minutes and an interval of 10 will execute the task every 10 minutes. Weekly, monthly and yearly will run once from the next execution time for that specific time frame. Example: schedule type set to weekly will execute the task once a week from the next execution time.

Note that if an interval of seconds or minutes is specified, then parameter Ufs.schedulerWakeupInterval in UFSSetup.properties may need to be adjusted. This parameter specifies, in seconds, the interval at which the scheduler wakes up and looks for work. For example, if a task is scheduled to run every 5 minutes, this parameter should have a value of 60 (wakes up every 1 minute to check for work). The default value for Ufs.schedulerWakeupInterval is 600 (10 minutes).

Check Can be triggered if the task can be triggered by an external event. Note that a task can be both scheduled (as described by schedule type) and triggered. (See triggering task execution)

Trigger id specifies the unique trigger identifier that is used to trigger execution of the task e.g. MY_TRIGGER. (See triggering task execution)

Synchronous execution indicates that the triggering system will only receive a response when the task is completed. (See synchronous and asynchronous task execution)

Next execution date and time can be changed at will. Dates should be entered in the format specified in the Ufs.dateFormat parameter in the Ebase setup properties file. Absence of values in the next execution date and time fields effectively stops the task executing.

The suspend execution checkbox can be checked to suspend execution of the task. Note that triggered execution is still possible.

View scheduled task logs

Click the View Logs tab of the Scheduler display. All task logs will be displayed in reverse order of execution i.e. the most recent tasks are displayed first. Periodic execution of the TaskLog Maintenance scheduled task is recommended to prevent this list becoming very large. (See Ebase provided scheduled tasks). Double click on a task log to display it.

Triggering task execution

A task can be triggered for execution by either:

The ebasetrigger command
Via URL using an XML interface

In both cases, a trigger id is provided by the caller, and the scheduled task with the corresponding trigger id is executed.

Synchronous and asynchronous execution

Execution of a triggered task can be either synchronous or asynchronous. With synchronous execution, the calling process is notified on completion of the triggered task. With asynchronous execution, the calling process is notified as soon as the triggered task has been scheduled for execution.

Verbose mode

When verbose mode is specified, the full execution log of the triggered task is returned to the caller. This option is only meaningful when used together with synchronous execution.

Return codes

A return code is always provided from the Java program called by ebasetrigger. The possible return codes are:

0 Task execution completed successfully

4 Task execution completed successfully, but warning messages have been issued. One or more items may not have been executed

8 Task execution failed

12 Task execution not started - system error occurred

16 Task execution not started – input is invalid

The return code is always returned as a message to the console e.g.

“Returncode 0 received from Ebase Server.”

In addition, the return code is also returned from the Java program to the ebasetrigger script.

Using the ebasetrigger command

This consists of both the ebasetrigger.bat (for use by Windows systems) and ebasetrigger.sh (for use by Linux and Unix systems) commands and their associated file systems. These commands are supplied in the External /ebasetrigger directory of the Ebase product distribution. The entire ebasetrigger directory is required for execution of the commands and this can be copied to external systems as required. The ebasetrigger command can be executed from any system that has network access to the Ebase server.

Prerequisites for using ebasetrigger

ebasetrigger.bat and ebasetrigger.sh are scripts that result in execution of a Java program, and therefore Java must be installed on the executing system. If necessary, the full path to the java command can be specified by editing the script file(s) where the java command can be found close to the bottom.

Ebasetrigger.properties file

File ebasetrigger.properties in the properties directory specifies the URL of the trigger servlet on the Ebase server e.g.

serverURL=http://myhost:3030/ufs/ScheduledTaskTrigger

serverURL is a required property. The host, port and web application parts of the URL should be changed to match the location of the Ebase Server. The servlet name – ScheduledTaskTrigger – should not normally be changed. In addition, the following optional properties can be specified. These act as defaults for all ebasetrigger commands that use the properties file unless the corresponding parameter is specified as part of the ebasetrigger command.

ExecutionMode: can have values sync or async

Verbose: can have values true and false

User: Ebase userid

Password: Ebase password

ebasetrigger command syntax

The syntax is as follows:

ebasetrigger [-help] –user userid –password pwd [-sync/-async] [-verbose] triggerid [P1=value1] [P2=value2 ....]

where…

user userid specifies the Ebase userid (required unless user is specified in the ebasetrigger.properties file)

password pwd specifies the Ebase password (required unless password is specified in the ebasetrigger.properties file)

help shows usage syntax (optional)

sync indicates execution is synchronous (optional)

async indicates execution is asynchronous (optional)

verbose all messages will be issued to the caller (optional)

triggerid trigger id (required)

Pn=valuen any number of name/value parameter pairs to be passed to the Ebase triggered task (optional)

examples:

ebasetrigger ABCD

ebasetrigger –user fred –password bloggs –sync ABCD

ebasetrigger –user fred –password bloggs –sync –verbose ABCD

ebasetrigger –sync –verbose ABCD PNAME=Fred OPTION1=true OPTION2=false

where ABCD is the trigger id, and PNAME, OPTION1 and OPTION2 are parameters accepted by the triggered task.

Using the XML interface

The XML interface is provided as part of the Ebase Server by the ScheduledTaskTrigger servlet, which accepts an EbaseTriggerRequest document and responds with an EbaseTriggerResponse document.

The EbaseTriggerRequest document is illustrated below:

<ParameterName>PNAME</ParameterName>

</Parameter>

<ParameterName>OPTION1</ParameterName>

</Parameter>

<ParameterName>OPTION2</ParameterName>

<ParameterValue>false</ParameterValue>

</Parameter>

</Parameters>

</EbaseTriggerRequest>

where the <Synchronous>, <Verbose> and <Parameters> tags are optional. The minimum requirement is as follows:

</EbaseTriggerRequest>

The system will respond with an EbaseTriggerResponse document which is illustrated below:

<ExecutionLog>Execution completed with return code 0</ExecutionLog>

</EbaseTriggerResponse>

If the task is executed with the verbose and synchronous options, the <ExecutionLog> element will contain the complete execution log for the task.

Logging of triggered tasks

All task logs for triggered tasks are saved in the same way as for scheduled tasks, and these can be viewed online. (See View scheduled task logs)

Ebase provided scheduled tasks

The following Ebase scheduled tasks are provided and can be selected from the program pulldown list:

Batch Execution

This program executes batches in background. It accepts the following parameters:

Name	Description
BATCH_NAME	Name of batch to execute. * can be used as a mask character e.g. A* indicates all batches beginning with A. * alone indicates all batches.
INCLUDE_ERRORS	Enter 'true' or 'false' to indicate whether or not the program should re-execute batches with status Error.

(See Ebase Batch System for more information)

Batch Maintenance

This program deletes batches with status 'OK' from the database. (See Ebase Batch System for more information)

Name	Description
NO_DAYS	Number of days to keep batches before deletion

Snapshot Maintenance

This program deletes expired snapshots from the database. Snapshots are created by the Snapshot Manager. This program accepts no parameters.

Saved Forms Maintenance

This program deletes expired saved forms from the database. Saved forms are created by end users using the save/restore feature. This program accepts no parameters. (See Save/Restore Feature for more information)

Scheduled Task Maintenance

This program deletes single execution scheduled tasks (schedule type 'O') from the database after they have executed. . This program accepts no parameters.

Scheduled Task Logs Maintenance

This program deletes scheduled task logs from the database after the specified number of days.

Name	Description
NO_DAYS	Number of days to keep task logs before deletion

Form Runner

This program executes the specified form, running the before-form and after-form events. All other events are ignored. It is not possible at this time to pass parameters to the form.

Name	Description
FORM_ID	The name of the form to run

Writing a custom scheduled task

Custom scheduled tasks can be scheduled for execution by the Scheduler in the same way as Ebase supplied scheduled tasks. Each scheduled task runs a custom written Java program that must conform to the following specification:

Must extend com.ebasetech.ufs.batch.ExecutableTask
Must have a single public execute() method. The parameter types must be one of the following types: String, Integer, Float, BigDecimal, Boolean. These parameters will then be displayed in the scheduler dialog above.
Must provide a getParameters() method (see example below).
Must return with an integer to indicate execution status (constants are provided)
The class file must be on the classpath of the Ebase Server.

The program can log messages by using the log(messageString) method. Start and end messages are automatically created and do not need to be added.

To terminate abnormally, the program can throw a ScheduledTaskAbortException.

The class will need to include the following import statement:

import com.ebasetech.ufs.batch.*;

and have the ufs.jar file on the compile classpath. This jar file is located in .../ufs/UfsServer/tomcat/webapps/ufs/WEB-INF/lib.

To make the program available to the Ebase Server either:

Add the custom task jar file to .../ufs/UfsServer/tomcat/webapps/ufs/WEB-INF/lib
Add the .class file to .../ufs/UfsServer/tomcat/webapps/ufs/WEB-INF/classes

Example:

import com.ebasetech.ufs.batch.*;

public class ScheduledTaskLogsMaintenance extends ExecutableTask

{

private static final String PARAMETER_NO_DAYS = "NO_DAYS";

private static final String PARAMETER_NO_DAYS_DESCRIPTION = "Number of days";

private static final int DEFAULT_NO_DAYS = 30;

public int execute( ) throws ScheduledTaskAbortException

{

/* Get Parameters */

int noDays;

Integer noDaysInt = (Integer)getParameterValue( PARAMETER_NO_DAYS );

if ( noDaysInt == null )

{

noDays = DEFAULT_NO_DAYS;

}

else

{

noDays = noDaysInt.intValue();

}

log( "Deleting scheduled task logs older than " +

beforeDate.substring( 6 ) +

SystemDate.DATE_DELIMITER +

beforeDate.substring( 4, 6 ) +

SystemDate.DATE_DELIMITER +

beforeDate.substring( 0, 4 ) );

/* Now perform the task function */

deleteLogs( beforeDate );

return STATUS_OK;

}

public List getParameters( )

{

ArrayList list = new ArrayList(1);

ScheduledTaskParameter parm = new ScheduledTaskParameter(

PARAMETER_NO_DAYS, ExecutableTask.PARAMETER_TYPE_INTEGER, PARAMETER_NO_DAYS_DESCRIPTION );

list.add( parm );

return list;

}

Security

The scheduler administration dialogs are protected by the Ebase security system, authorization DESIGNER_SCHEDULER_ADMINISTRATION. (See Ebase Security Authorizations for more information)