4.) Scheduler

4.1.) Introduction

EspressReport has a scheduler interface through which reports can be exported at a specific time or specific intervals.  This allows EspressReport to handle mundane tasks such as exporting reports than having a user log in at a specific time and explicitly perform the operation.  For more information on how to use Scheduler, please see Section 13 - Scheduling of the Designer guide.

When writing Scheduler API code, two main classes are used; ScheduleObject, which is used to give details on the schedule job, and ScheduleModifier, which is used to alter Scheduler.

Both ReportAPIWithChart.jar and Scheduler.jar (in the EspressReport/lib directory) need to be added to the CLASSPATH for any code using the Scheduler.

All examples and code given in the manual assume that EspressManager is running locally (i.e., on your local machine) and default port number (22071).  You can change this by going to the source code (<EspressReport-installation-directory>/help/manual/code/src directory), editing the code to enter the new connection information and recompiling the code.  If you wish to, you can move the newly compiled code to the <EspressReport-installation-directory>/help/manual/code/classes directory before running it.

4.2.) Connecting to EspressManager

You cannot run Scheduler (or any Scheduler code) without connecting to EspressManager first.  Depending on whether EspressManager is running as an application or a servlet, you can use API methods to specify connection information.

4.2.1.) EspressManager running as application

If EspressManager is running as an application, you can use API methods to specify the IP address/machine name where EspressManager is located and the port number EspressManager is listening on.

You use the following two API methods to set the connection information:

For example, the following lines of code:

will connect to EspressManager running on someMachine and listening on somePortNumber.

Please note that if EspressManager connection information is not specified, the code will attempt to connect to EspressManager on the local machine and listening to the default port number (22071).

Please note that these methods exist in the QbScheduler and ScheduleModifier classes.

4.2.2.) EspressManager running as servlet

If EspressManager is running as a servlet, you can use the following methods:

For example, the following lines of code:

will connect to EspressManager running at http://someMachine:somePortNumber/EspressReport/servlet.

Please note that these methods exist in the QbScheduler and ScheduleModifier classes.

4.3) Invoking Scheduler Graphical Interface

Scheduler can be called from Report API in either an application or an applet.  The following example, which can run as an applet or application, invokes Scheduler by constructing a QbScheduler Object:

Full Source Code

A few "set" methods are also available if the programmer wishes to configure the Scheduler Interface to open with specific features turned on or off.  Here are two methods that can be used to set the root directory for browsing and to set the "insert command" feature on of off:

4.4) Scheduling an Export

You can schedule a report to be exported using Scheduler.  The following code, given below, shows how to do this:

Full Source Code

Note that any references to a data source, or a report file, using the relative URL reference (e.g. help/manual/code/templates/Account.rpt) are relative to the directory from where EspressManager is running in.

The above code schedules a report (Account.rpt) to be exported to DHTML, in the default export directory and sets the export to take place once and in 1 minute.

The examples below show how to set up a periodic schedule:

Full Source Code

The above code snippet shows how to schedule a job to run every 5 minutes (or every day depending on which section of the code you comment).

The following code snippet shows to schedule a job to run at certain time periods:

Full Source Code

You can also specify the parameters when scheduling a parameterized chart or report to be exported.  The following code shows how:

Full Source Code

A security level for the report can also be specified.  The following code shows how to specify a security level (for report cells and/or query parameters):

Full Source Code

You can also specify the schedules to be sent to one or more email addresses, either as a link or an attachment.  The following code shows how to send a scheduled job which contains a non-parameterized report to multiple recipients:

Full Source Code

Similarly, emails can be sent for each parameter set chosen for a parameterized report/chart when scheduling an export.  Note that atleast one email address must be specified for each parameter set and the same recipient can be used for multiple parameter sets.

Full Source Code

The scheduled reports can also be stored in a web-accessible location and the URL sent via email to various recipients.  The following code shows how:

Full Source Code

4.5.) Scheduling a Command

In addition to scheduling exports, you can also schedule commands to be run at a specific time (or time interval).  The code remains the same as the one for scheduling exports except the command to be executed is specified (rather than the report location, export format and export location).

Full Source Code

4.6.) Removing a Schedule

In addition to adding schedules, you can also use the API to remove any schedules.  This is done by getting a list of all the jobs scheduled and then delete a particular job.

The following code shows how to delete a particular job:

Full Source Code

Note that the above code removes the first job in the schedule list. The job may not be visible if it has been already marked for deletion. The recommended approach is to go through the vector and search each ScheduleObject by the name and then deleting the correct one.

4.7.) Getting Details of a Failed Schedule

Sometimes, a schedule job may fail for some reason or another.  EspressManager keeps a track of all the failed jobs so that its details can be obtained later.  The following code shows how to obtain the details:

Full Source Code

You can also set up an email to be sent in case the schedule fails.  The following code illustrates how:

Full Source Code

4.8.) ICallBackScheduler Interface

You can also create additional code that performs certain actions based on the scheduler performing a job (whether successful or not).  This code implements the ICallBackScheduler interface and specifies what to do when a job has been successfully completed or not.

Please note that after creating the code you need to change ServerCommands.txt (in the <EspressReport-installation-directory>/userdb directory) and add the following:

The following code shows how to use the ICallBackScheduler interface:

To use the above code, add the following to ServerCommands.txt:

Make sure that CallBackScheduler is in the CLASSPATH.  The code will then print messages at the end of each job saying whether the job was run successfully or not.

4.9.) Scheduler Listener

EspressReport allows scheduled reports to be modified via custom code using server extensions.  These custom classes will intercept reports before they are exported and allow users to implement additional business logic to the scheduling process.

To use the Scheduler Listener, you will have to write your own custom class that implements SchedulerListener.  Given below is an example:

The above example prints a simple System.out.println statement before exporting either the report.

To use any custom class implementing SchedulerListener, you will have to implement another custom class implementing DefaultListenerManager.  For example:

To use the above code, add the following to ServerCommands.txt:

Make sure that both MyEspressReportListenerManager and MyEspressReportSchedulerListener are in the CLASSPATH.

4.10.) Report Bursting

You can also use the Report Bursting feature in Scheduler using the API.  Note that the report must use a database as the datasource and must be grouped in order for the report to be bursted.

Given below is an example on how to use report bursting:

Full Source Code

The above code bursts all groups and sends out an email using a report column as the source for the addresses.

Note that in the above code, column 16 doesn't exist in the template.  The method is provided in the example to show how to pass in the email column for bursting.

4.11.) Javadoc

Javadoc for the entire API is provided along with EspressReport.  It is located at <EspressReport-installation-directory>/help/EspressReportapidocs/index.html.

4.12.) Summary

EspressReport API provides an easy-to-use and powerful API to query the scheduler interface as well as add and remove schedules.  You can also write code to perform your own action when a job has been completed successfully (or not) in Scheduler.

Please note that the API requires a JDK 1.4 or above.  The EspressReport API has been tested on Windows, Solaris, Linux, AIX and HP platforms.