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 may not want to run it on holidays. The list of excluded days and times is called a calendar, and a calendar may be defined as a list of annual dates, a weekly or monthly pattern, or a cron expression.
The rest_v2/jobs/calendars service defines any number of exclusion calendars that are stored in the repository. 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 modify an exclusion calendar and update all of the report jobs that used it. Therefore, you can update the calendar of holidays every year and not need to modify any report jobs.
This chapter includes the following sections:
| • | Creating an Exclusion Calendar |
| • | Listing All Calendar Names |
| • | Viewing an Exclusion Calendar |
| • | Updating an Exclusion Calendar |
| • | Deleting an Exclusion Calendar |
| • | Error Messages |
Creating an Exclusion Calendar
The PUT method creates a named exclusion calendar that you can use when scheduling reports. Specify a unique name for the calendar in the URL. The body of the request determines the type of the calendar, as shown in the examples below the table.
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/<calendarName> | ||
| 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 calendar is created, and the body of the response contains the calendar definition, similar to the one that was sent. | 400 Bad Request – When the calendar name already exists or the descriptor is missing a parameter (the error message describes the missing parameter). | ||
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. |
JSON:
XML:
| • | Cron calendar – Defines the days and times to exclude as a cron expression. |
JSON:
XML:
| • | Daily calendar – Defines a time range to exclude every day. |
JSON:
XML:
| • | Holiday calendar – Defines a set of days to exclude that can be updated every year. |
JSON:
XML:
| • | Weekly calendar – Defines a set of days to be excluded each week. |
JSON:
| • | Monthly calendar – Defines the dates to exclude every month. |
JSON:
Listing All 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. You may specify only one calendarType parameter. When calendarType isn't specified, all calendars names are returned. If calendarType has an invalid value, an empty collection is returned. | |
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – Body contains a list of calendar names. | 401 Unauthorized | ||
The list of calendar names in the result has the following format in XML:
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 – The body contains the definition of the requested calendar. | 404 Not Found – When the specified calendar name does not exist. | ||
The calendar descriptor in a successful response has the following JSON format:
| • | Annual calendar: |
| • | Cron calendar: |
| • | Daily calendar: |
| • | Holiday calendar: |
| • | Weekly calendar (day flags are Sunday to Saturday): |
| • | Monthly calendar (day flags are dates from 1 to 31): |
Updating an Exclusion Calendar
Use the PUT method to update a calendar that already exists, with the option to update all the jobs that use it.
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/<calendarName>?<args> | ||
| Argument | Type/Value | Description | |
| replace? | true | Set to true to modify an existing calendar with the given name. When this argument is omitted or false, an error is returned (see below). | |
| update | true / false | Whether or not to update existing triggers that reference this calendar. When triggers are updated, the new calendar is in effect on existing scheduled reports. | |
| Content-Type | Content | ||
| application/xml | A well-formed XML or JSON calendar descriptor. See Creating an Exclusion Calendar for examples of each type of calendar. You can specify any type of exclusion calendar such as weekly, monthly, or cron, regardless of the current type. | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The calendar is updated, and the body of the response contains the new calendar definition, similar to the one that was sent. | 400 Bad Request – When the replace parameter is false or omitted, or the calendar definition is not valid. 404 Not Found – When the specified calendar name does not exist. | ||
For example, you can make the following request to replace the calendar named weeklyCalendar. Note that the calendar name does not change, and it will contain a daily calendar, which is not good naming practice.
| Request |
|
| Body |
If the replace parameter is false or omitted, the error is as follows:
| Response | 400 Bad Request |
| Body |
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. | ||
Error Messages
When creating or updating a calendar, the error messages can be expected in the following cases.
| • | Creating an annual calendar that is missing a mandatory parameter: |
| Request |
|
| Body |
Expected Reply:
| Response | 400 Bad Request |
| Body |
| • | Creating a cron calendar that is missing a mandatory parameter: |
| Request |
|
| Body |
Expected Reply:
| Response | 400 Bad Request |
| Body |
| • | Creating a daily calendar that is missing the mandatory start-range parameter: |
| Request |
|
| Body |
Expected Reply:
| Response | 400 Bad Request |
| Body |
| • | Creating a daily calendar that is missing the mandatory end-range parameter: |
| Request |
|
| Body |
Expected Reply:
| Response | 400 Bad Request |
| Body |
| • | Creating a holiday calendar that is missing a mandatory parameter: |
| Request |
|
| Body |
Expected Reply:
| Response | 400 Bad Request |
| Body |
| • | Creating a weekly calendar that is missing a mandatory parameter: |
| Request |
|
| Body |
Expected Reply:
| Response | 400 Bad Request |
| Body |
| • | Creating a monthly calendar that is missing a mandatory parameter: |
| Request |
|
| Body |
Expected Reply:
| Response | 400 Bad Request |
| Body |
Recommended Comments
There are no comments to display.