The calendars Service

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
Type

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:

<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 – 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:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportJobCalendar>
  <baseCalendar>
    <calendarType>base</calendarType>
    <excludeDates/>
    <description>Base calendar description</description>
    <excludeDays/>
    <timeZone>GMT+03:00</timeZone>
  </baseCalendar>
  <calendarType>daily</calendarType>
  <excludeDates/>
  <description>Main calendar description</description>
  <excludeDays/>
  <invertTimeRange>false</invertTimeRange>
  <rangeEndingCalendar  >2012-03-20T14:44:37.353+03:00</rangeEndingCalendar>
  <rangeStartingCalendar>2012-03-20T14:43:37.353+03:00</rangeStartingCalendar>
  <timeZone>GMT+03:00</timeZone>
</reportJobCalendar>

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
Triggers?

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 calendar descriptor (see examples below).

Return Value on Success

Typical Return Values on Failure

200 OK – The calendars are updates.

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.
<?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>2012-03-20</excludeDay>
    <excludeDay>2012-03-21</excludeDay>
    <excludeDay>2012-03-22</excludeDay>
  </excludeDays>
</reportJobCalendar>
Cron calendar – Defines the days and times to exclude as a cron expression.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportJobCalendar>
  <calendarType>cron</calendarType>
  <description>Cron format 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.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportJobCalendar>
  <calendarType>daily</calendarType>
  <description>Daily calendar description</description>
  <invertTimeRange>false</invertTimeRange>
  <rangeEndingCalendar>2012-03-20T14:44:37.353+03:00</rangeEndingCalendar>
  <rangeStartingCalendar>2012-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.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportJobCalendar>
  <calendarType>holiday</calendarType>
  <description>Holiday calendar description</description>
  <excludeDays>
    <excludeDay>2012-03-20</excludeDay>
    <excludeDay>2012-03-21</excludeDay>
    <excludeDay>2012-03-22</excludeDay>
  </excludeDays>
  <timeZone>GMT+03:00</timeZone>
</reportJobCalendar>
Weekly calendar – Defines a set of days to be excluded each week.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportJobCalendar>
  <calendarType>weekly</calendarType>
  <description>test description</description>
  <excludeDaysFlags>
    <excludeDayFlag>false</excludeDayFlag> <!--SUNDAY--->
    <excludeDayFlag>true</excludeDayFlag>  <!--MONDAY--->
    <excludeDayFlag>false</excludeDayFlag>  <!--TUESDAY--->
    <excludeDayFlag>true</excludeDayFlag>  <!--WEDNESDAY--->
    <excludeDayFlag>false</excludeDayFlag>  <!--THURSDAY--->
    <excludeDayFlag>true</excludeDayFlag>  <!--FRIDAY--->
    <excludeDayFlag>false</excludeDayFlag>  <!--SATURDAY--->
  </excludeDaysFlags>
  <timeZone>GMT+03:00</timeZone>
</reportJobCalendar>
Monthly calendar – Defines the dates to exclude every month.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportJobCalendar>
  <calendarType>monthly</calendarType>
  <description>Monthly calendar description</description>
  <excludeDaysFlags>
    <excludeDayFlag>true</excludeDayFlag> <!--01--->
    <excludeDayFlag>false</excludeDayFlag> <!--02--->
    <excludeDayFlag>true</excludeDayFlag> <!--03--->
    <excludeDayFlag>false</excludeDayFlag> <!--04--->
    <excludeDayFlag>true</excludeDayFlag> <!--05--->
    <excludeDayFlag>false</excludeDayFlag> <!--06--->
    <excludeDayFlag>true</excludeDayFlag> <!--07--->
    <excludeDayFlag>false</excludeDayFlag> <!--08--->
    <excludeDayFlag>true</excludeDayFlag> <!--09--->
    <excludeDayFlag>false</excludeDayFlag> <!--10--->
    <excludeDayFlag>true</excludeDayFlag> <!--11--->
    <excludeDayFlag>false</excludeDayFlag> <!--12--->
    <excludeDayFlag>false</excludeDayFlag> <!--13--->
    <excludeDayFlag>true</excludeDayFlag> <!--14--->
    <excludeDayFlag>false</excludeDayFlag> <!--15--->
    <excludeDayFlag>false</excludeDayFlag> <!--16--->
    <excludeDayFlag>false</excludeDayFlag> <!--17--->
    <excludeDayFlag>false</excludeDayFlag> <!--18--->
    <excludeDayFlag>false</excludeDayFlag> <!--19--->
    <excludeDayFlag>false</excludeDayFlag> <!--20--->
    <excludeDayFlag>false</excludeDayFlag> <!--21--->
    <excludeDayFlag>false</excludeDayFlag> <!--22--->
    <excludeDayFlag>false</excludeDayFlag> <!--23--->
    <excludeDayFlag>false</excludeDayFlag> <!--24--->
    <excludeDayFlag>false</excludeDayFlag> <!--25--->
    <excludeDayFlag>false</excludeDayFlag> <!--26--->
    <excludeDayFlag>false</excludeDayFlag> <!--27--->
    <excludeDayFlag>false</excludeDayFlag> <!--28--->
    <excludeDayFlag>false</excludeDayFlag> <!--29--->
    <excludeDayFlag>false</excludeDayFlag> <!--30--->
    <excludeDayFlag>false</excludeDayFlag> <!--31--->
</excludeDaysFlags>
<timeZone>GMT+03:00</timeZone>
</reportJobCalendar>
Version: 
Feedback