Reports on the server can be executed asynchronously using the Report Scheduling API. Asynchronous report execution involves defining the report job and using the report scheduling service to schedule it.

Report Jobs

A report job definition consists of:

Two types of recurrence are supported by default:

A report job definition is an instance of the com.jaspersoft.jasperserver.api.engine.scheduling.domain.ReportJob

bean class. To instantiate a new report job definition, you'd use code similar to the following:

The job source is created as a sub-bean:

The job trigger is used to specify when the job should occur. The basic com.jaspersoft.jasperserver.api.engine.scheduling.domain.ReportJobTrigger

bean type is abstract; two concrete types extend it: com.jaspersoft.jasperserver.api.engine.scheduling.domain.ReportJobSimpleTrigger and com.jaspersoft.jasperserver.api.engine.scheduling.domain.ReportJobCalendarTrigger.

For example, to create a job that fires 20 times every 10 days you would use code similar to this:

Next, you need to specify the job output attributes. To set the output filename and format, use code similar to the following:

You can send your output to several different locations; the most common output destination is the repository. Alternative output locations include an FTP server or a user’s local drive. To output to the jasperserver repository, use code similar to this:

To upload the output to an FTP server instead of the repository, use code similar to this:

To send the output to a user’s local drive, use code similar to this:

job.getContentRepositoryDestination().setOutputLocalFolder("C:UsersJSmithJRS");[/code]                    

Optionally, you can instruct the reporting scheduler to send a notification once the job completes. This notice normally goes to the user who created the report:

You can also optionally email an alert to the job creator, an administrative user, or both. For example, to send an alert when the job fails, use code similar to the following:

Report Job Model

A report job model allows you to specify scheduling and output attributes for multiple report jobs at the same time. A report job model takes a list of report job IDs and a single set of attributes for all report jobs in the list.

A report job model definition consists of:

You need to define only those attributes you want to update; empty attributes are left unchanged in the original report jobs.

A report job model definition is an instance of the com.jaspersoft.jasperserver.api.engine.scheduling.domain.ReportJobModel

bean class, which extends ReportJob.

To instantiate a new report job model definition, you'd use code similar to the following:

To set the destination, mail notification, and schedule for a report job model, you'd use code similar to the following:

Any report job attributes not updated by ReportJobModel remain unchanged. In the example above, the existing email recipient, subject, and message remain the same for the updated jobs, as well as any existing alerts.

The report scheduling service also uses ReportJobModel to retrieve a list of all active report jobs that match the attributes specified in the report job model. The list of report jobs retrieved via ReportJobModel can be sorted using the ReportJobSortType subclass of ReportJobModel. See Report Scheduling Service for more information.

Report Job Summary

Report job summaries hold information returned by the scheduler service. The ReportJobSummary class has a number of methods that allow you to retrieve specific information about the summary. Some useful methods are:

Report Job ID Holder

The ReportSchedulingService assigns every active report job a report job ID. This ID can be wrapped using the ReportJobIDHolder class. ReportJobIDHolder is used by some report scheduling API methods.

Report Scheduling Service

The scheduling service is used to schedule a report job and provide information about existing jobs. The built-in scheduling service implementation consists of a Hibernate-based component that persists job definitions and a Quartz scheduler that schedules and fires the jobs.

Once a report job definition is created, it's passed to the scheduling service:

The scheduling service also contains methods for the removing one or more existing report jobs: removeScheduledJob and removeScheduledJobs.

To load the full report job definition for a job, use the getScheduledJob method. You can alter the job definition then update it using the updateScheduledJob service method.

You can alter and update a list of report jobs using the updateScheduledJobs service method. updateScheduledJob takes a ReportJobModel and updates the specified jobs to match the attributes in the ReportJobModel. Unspecified attributes remain unchanged. The trigger is handled somewhat differently from the other attributes. A Boolean parameter, replaceTriggerIgnoreType, specifies one of two options:

For example, to update two report jobs, including the trigger, to match the parameters in a specified report job model, you'd use code similar to the following:

Two methods of the scheduling service let you retrieve a list of jobs. The retrieved list consists of instances of com.jaspersoft.jasperserver.api.engine.scheduling.domain.ReportJobSummary that contain basic job attributes, plus runtime attributes like job status and previous/next fire times.

For example to get all active jobs that match a report job model, you'd use code similar to the following:

To get all scheduled jobs whose next fire time is between startDate and endDate, you'd use code similar to the following. The next fire time is the value retrieved by ReportJobSummary.getNextFireTime.

The pause and resume methods let you pause or resume a list of jobs. To pause all the jobs retrieved by the previous call, use code similar to the following. If an alert is set, pausing the job triggers the alert:

The pauseByID and resumeByID methods let you pause or resume a ReportJobIDHolder list.

Report Jobs Scheduler

The ReportJobsScheduler service includes methods for adding, getting, and deleting calendars. Calendars in ReportJobsScheduler service are implementations of the Quartz Calendar interface. They specify times during which scheduled jobs do not fire. For information about Quartz calendars, see the Quartz API documentation.

For example, to register the Quartz calendar, myHolidayCalendar(), with the ReportJobsScheduler, you'd use code similar to the following:

Other methods allow you to delete a calendar, retrieve a calendar by name, or get a list of the names of all registered calendars: deleteCalendar, getCalendar, and getCalendarNames.

Once you've added a calendar, you can use it in any number of job triggers. For example, to create a trigger that tells a job to run every Monday at 1:00 A.M., unless it's a United States holiday as specified in myHolidayCalendar(), you'd use code similar to the following:

  ReportJobCalendarTrigger weeklyTrigger = new ReportJobCalendarTrigger();    weeklyTrigger.setMinutes("0");    weeklyTrigger.setHours("1");    weeklyTrigger.setDaysTypeCode(weeklyTrigger.DAYS_TYPE_WEEK);    weeklyTrigger.setWeekDays(2); //sets the day of the week; Monday is 2    weeklyTrigger.setTimezone("America/Los_Angeles");    weeklyTrigger.setStartType(weeklyTrigger.START_TYPE_NOW);    weeklyTrigger.setCalendarName("US Holiday Calendar");       //tells the job not to run on holidays as specified by this calendar[/code]                    

You can use a trigger like this to set the holiday calendar for a number of ReportJobs using ReportJobModel. Set replaceTriggerIgnoreType to true to ensure that the trigger is updated for all ReportJobs.