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 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. 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:
• | 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:
{ "calendarType":"annual", "description":"Annual calendar description", "excludeDays": [ "2021-03-20", "2021-03-21", "2021-03-22"], "timeZone":"GMT+03:00" } |
XML:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <reportJobCalendar> <calendarType>annual</calendarType> <description>Annual calendar description</description> <timeZone>GMT+03:00</timeZone> <excludeDays> <excludeDay>2021-03-20</excludeDay> <excludeDay>2021-03-21</excludeDay> <excludeDay>2021-03-22</excludeDay> </excludeDays> </reportJobCalendar> |
• | Cron calendar – Defines the days and times to exclude as a cron expression. |
JSON:
{ "calendarType":"cron", "description":"Cron calendar description", "cronExpression":"0 30 10-13 ? * WED,FRI", "timeZone":"GMT+03:00" } |
XML:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <reportJobCalendar> <calendarType>cron</calendarType> <description>Cron calendar description</description> <cronExpression>0 30 10-13 ? * WED,FRI</cronExpression> <timeZone>GMT+03:00</timeZone> </reportJobCalendar> |
• | Daily calendar – Defines a time range to exclude every day. |
JSON:
{ "calendarType":"daily", "description":"Daily calendar description", "invertTimeRange":false, "rangeEndingCalendar":"2020-20T14:44:37.353+03:00", "rangeStartingCalendar":"2020-03-20T14:43:37.353+03:00", "timeZone":"GMT+03:00" } |
XML:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <reportJobCalendar> <calendarType>daily</calendarType> <description>Daily calendar description</description> <invertTimeRange>false</invertTimeRange> <rangeEndingCalendar>2020-03-20T14:44:37.353+03:00</rangeEndingCalendar> <rangeStartingCalendar>2020-03-20T14:43:37.353+03:00</rangeStartingCalendar> <timeZone>GMT+03:00</timeZone> </reportJobCalendar> |
• | Holiday calendar – Defines a set of days to exclude that can be updated every year. |
JSON:
{ "calendarType":"holiday", "description":"Holiday calendar (observed)", "excludeDays": [ "2020-01-01", "2020-01-20", "2020-02-17", "2020-05-25", "2020-07-03", "2020-09-07", "2020-10-12", "2020-11-11", "2020-11-26", "2020-12-25" ], "timeZone":"GMT+03:00" } |
XML:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <reportJobCalendar> <calendarType>holiday</calendarType> <description>Holiday calendar (observed)</description> <excludeDays> <excludeDay>2021-03-20</excludeDay> <excludeDay>2020-01-01</excludeDay> <excludeDay>2020-01-20</excludeDay> <excludeDay>2020-02-17</excludeDay> <excludeDay>2020-05-25</excludeDay> <excludeDay>2020-07-03</excludeDay> <excludeDay>2020-09-07</excludeDay> <excludeDay>2020-10-12</excludeDay> <excludeDay>2020-11-11</excludeDay> <excludeDay>2020-11-26</excludeDay> <excludeDay>2020-12-25</excludeDay> </excludeDays> <timeZone>GMT+03:00</timeZone> </reportJobCalendar> |
• | Weekly calendar – Defines a set of days to be excluded each week. |
JSON:
{ "calendarType": "weekly", "description": "Weekly calendar description", "excludeDaysFlags": [ true, /*Sunday*/ false, /*Monday*/ false, /*Tuesday*/ false, /*Wednesday*/ false, /*Thursday*/ false, /*Friday*/ false /*Saturday*/ ], "timeZone": "GMT+03:00" } |
• | Monthly calendar – Defines the dates to exclude every month. |
JSON:
{ "calendarType":"monthly", "description":"Monthly calendar description", "excludeDaysFlags": [ true, /* 1*/ false, /* 2*/ false, /* 3*/ false, /* 4*/ false, /* 5*/ false, /* 6*/ false, /* 7*/ false, /* 8*/ false, /* 9*/ false, /*10*/ false, /*11*/ false, /*12*/ false, /*13*/ false, /*14*/ false, /*15*/ false, /*16*/ false, /*17*/ false, /*18*/ false, /*19*/ false, /*20*/ false, /*21*/ false, /*22*/ false, /*23*/ false, /*24*/ false, /*25*/ false, /*26*/ false, /*27*/ false, /*28*/ false, /*29*/ false, /*30*/ false /*31*/ ], "timeZone":"GMT+03:00" } |
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:
<calendarNameList> <calendarName>name1</calendarName> <calendarName>name2</calendarName> </calendarNameList> |
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: |
{ "calendarType": "annual", "description": "Annual calendar description", "timeZone": "GMT+03:00", "excludeDays": [ "2012-03-20", "2012-03-21", "2012-03-22" ] } |
• | Cron calendar: |
{ "calendarType": "cron", "description": "Cron calendar description", "timeZone": "GMT+03:00", "excludeDays": null, "cronExpression": "0 30 10-13 ? * WED,FRI" } |
• | Daily calendar: |
{ "calendarType": "daily", "description": "Daily calendar description", "timeZone": "GMT+03:00", "excludeDays": null, "rangeStartingCalendar": 1332243817353, "rangeEndingCalendar": 1332243877353, "invertTimeRange": false } |
• | Holiday calendar: |
{ "calendarType": "holiday", "description": "Holiday calendar (observed)", "timeZone": "GMT+03:00", "excludeDays": [ "2020-01-01", "2020-01-20", "2020-02-17", "2020-05-25", "2020-07-03", "2020-09-07", "2020-10-12", "2020-11-11", "2020-11-26", "2020-12-25" ] } |
• | Weekly calendar (day flags are Sunday to Saturday): |
{ "calendarType": "weekly", "description": "Weekly calendar description", "excludeDays": null, "excludeDaysFlags": [ true, false, false, false, false, false, false ], "timeZone":"GMT+03:00" } |
• | Monthly calendar (day flags are dates from 1 to 31): |
{ "calendarType":"monthly", "description":"Monthly calendar description", "excludeDaysFlags": [ true, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false ], "timeZone":"GMT+03:00" } |
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 |
PUT http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/ weeklyCalendar?replace=true&updateTriggers=true Content-Type=application/json |
Body |
{ "calendarType":"daily", "description":"test description", "invertTimeRange":false, "rangeEndingCalendar":"2012-03-20T14:44:37.353+03:00", "rangeStartingCalendar":"2012-03-20T14:43:37.353+03:00", "timeZone":"GMT+03:00" } |
If the replace parameter is false or omitted, the error is as follows:
Response |
400 Bad Request |
Body |
{ "message": "Resource 'weeklyCalendar' already exists", "errorCode": "resource.already.exists", "parameters": [ "weeklyCalendar" ] } |
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 |
PUT http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/annualCalendar Content-Type=application/json |
Body |
{ "calendarType":"annual", "description":"Annual calendar description", "timeZone":"GMT+03:00" } |
Expected Reply:
Response |
400 Bad Request |
Body |
{ "message": "mandatory parameter 'reportJobCalendar.excludeDays' not found", "errorCode": "mandatory.parameter.error", "parameters": [ "reportJobCalendar.excludeDays" ] } |
• | Creating a cron calendar that is missing a mandatory parameter: |
Request |
PUT http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/cronCalendar Content-Type=application/json |
Body |
{ "calendarType":"cron", "description":"Cron calendar description", "timeZone":"GMT+03:00" } |
Expected Reply:
Response |
400 Bad Request |
Body |
{ "message": "mandatory parameter 'reportJobCalendar.cronExpression' not found", "errorCode": "mandatory.parameter.error", "parameters": [ "reportJobCalendar.cronExpression" ] } |
• | Creating a daily calendar that is missing the mandatory start-range parameter: |
Request |
PUT http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/dailyCalendar Content-Type=application/json |
Body |
{ "calendarType":"daily", "description":"Daily calendar description", "invertTimeRange":false, "rangeEndingCalendar":"2021-03-20T14:44:37.353+03:00", "timeZone":"GMT+03:00" } |
Expected Reply:
Response |
400 Bad Request |
Body |
{ "message": "mandatory parameter 'reportJobCalendar.rangeStartingCalendar' not found", "errorCode": "mandatory.parameter.error", "parameters": [ "reportJobCalendar.rangeStartingCalendar" ] } |
• | Creating a daily calendar that is missing the mandatory end-range parameter: |
Request |
PUT http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/dailyCalendar Content-Type=application/json |
Body |
{ "calendarType":"daily", "description":"Daily calendar description", "invertTimeRange":false, "rangeStartingCalendar":"2012-03-20T14:43:37.353+03:00", "timeZone":"GMT+03:00" } |
Expected Reply:
Response |
400 Bad Request |
Body |
{ "message": "mandatory parameter 'reportJobCalendar.rangeEndingCalendar' not found", "errorCode": "mandatory.parameter.error", "parameters": [ "reportJobCalendar.rangeEndingCalendar" ] } |
• | Creating a holiday calendar that is missing a mandatory parameter: |
Request |
PUT http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/holidayCalendar Content-Type=application/json |
Body |
{ "calendarType":"holiday", "description":"Holiday calendar description", "timeZone":"GMT+03:00" } |
Expected Reply:
Response |
400 Bad Request |
Body |
{ "message": "mandatory parameter 'reportJobCalendar.excludeDays' not found", "errorCode": "mandatory.parameter.error", "parameters": [ "reportJobCalendar.excludeDays" ] } |
• | Creating a weekly calendar that is missing a mandatory parameter: |
Request |
PUT http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/weeklyCalendar Content-Type=application/json |
Body |
{ "calendarType":"weekly", "description":"Weekly calendar description", "timeZone":"GMT+03:00" } |
Expected Reply:
Response |
400 Bad Request |
Body |
{ "message": "mandatory parameter 'reportJobCalendar.excludeDaysFlags' not found", "errorCode": "mandatory.parameter.error", "parameters": [ "reportJobCalendar.excludeDaysFlags" ] } |
• | Creating a monthly calendar that is missing a mandatory parameter: |
Request |
PUT http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/calendars/monthlyCalendar Content-Type=application/json |
Body |
{ "calendarType":"monthly", "description":"Monthly calendar description", "timeZone":"GMT+03:00" } |
Expected Reply:
Response |
400 Bad Request |
Body |
{ "message": "mandatory parameter 'reportJobCalendar.excludeDaysFlags' not found", "errorCode": "mandatory.parameter.error", "parameters": [ "reportJobCalendar.excludeDaysFlags" ] } |