The scheduler allows a job to be defined with a list of excluded days or times when you do not want the job to run. For example, if you have a report scheduled to run every business day, you want to exclude holidays that change every year. The list for excluded days and times is defined as a calendar, and there are various ways to define the calendar.
The rest_v2/jobs/calendars service defines any number of exclusion calendars. When scheduling a report, reference the name of the calendar to exclude, and the scheduler automatically calculates the correct days to trigger the report. The scheduler also allows you to update an exclusion calendar and update all of the report jobs that used it. Therefore, you can update the calendar of excluded holidays every year and not need to modify any report jobs.
This chapter includes the following sections:
| • | Listing All Registered Calendar Names |
| • | Viewing an Exclusion Calendar |
| • | Deleting an Exclusion Calendar |
| • | Adding or Updating an Exclusion Calendar |
Listing All Registered Calendar Names
The following method returns the list of all calendar names that were added to the scheduler.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/?<argument> | ||
| Argument | Type/Value | Description | |
| calendar | optional string | A type of calendar to return: annual, cron, daily, holiday, monthly, or weekly. See Adding or Updating an Exclusion Calendar for a description of the various types. You may specify only one calendarType parameter. When calendarType isn't specified, all calendars names are returned. If calendarType has an invalid value, then an empty collection is returned. | |
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – Body is XML that contains a list of calendar names. | 401 Unauthorized | ||
The list of calendar names in the result has the following XML format:
Viewing an Exclusion Calendar
The following method takes the name of an exclusion calendar and returns the definition of the calendar:
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/<calendarName>/ | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – Body is XML that contains the requested calendar. | 404 Not Found – When the specified calendar name does not exist. | ||
The calendar descriptor in the result has the following XML format:
Deleting an Exclusion Calendar
Use the following method to delete a calendar by name.
| Method | URL | ||
| DELETE | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/<calendarName>/ | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The calendar has been deleted. | 404 Not Found – When the specified calendar name does not exist. | ||
Adding or Updating an Exclusion Calendar
This method creates a named exclusion calendar that you can use when scheduling reports. If the calendar already exists, you have the option of replacing it and updating all the jobs that used it.
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/<calendarName>?<args> | ||
| Argument | Type/Value | Description | |
| replace? | true / false | If true, any existing calendar with the same name is overwritten. When this argument is omitted, it is false by default. | |
| update | true / false | Whether or not to update existing triggers that referenced the already existing calendar so that they are based on the new trigger. | |
| Content-Type | Content | ||
| application/xml | A well-formed XML or JSON calendar descriptor (see examples below). | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The calendars are updated. | 404 Not Found – When the specified calendar name does not exist. | ||
The following examples show the types of exclusion calendars that you can add to the scheduler:
| • | Annual calendar – A list of days that you want to exclude every year. |
| • | Cron calendar – Defines the days and times to exclude as a cron expression. |
| • | Daily calendar – Defines a time range to exclude every day. |
| • | Holiday calendar – Defines a set of days to exclude that can be updated every year. |
| • | Weekly calendar – Defines a set of days to be excluded each week. |
| • | Monthly calendar – Defines the dates to exclude every month. |
Recommended Comments
There are no comments to display.