Jump to content
  • This documentation is an older version of JasperReports Server REST API Reference. View the latest documentation.

    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:

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

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

    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


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...