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 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
application/json

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
Type

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

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
application/json

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"
    ]
}