The jobs Service

URL

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs?<arguments>

Description

Performs a case-insensitive string search for this value anywhere within the label property of every job.

The name of the user who scheduled the report, if necessary in the format <username>%7C<organization> (%7C is the | character).

Optional URI (repository path) of a report, report option, or dashboard to list all of its jobs. You may need to encode the / characters in the URI with %2F. When specified, the results are only for the given resource.

Searches for jobs that match the JSON jobModel, which is a fragment of a job descriptor containing one or more properties to be matched. This argument lets you search for any parameter of the job descriptor, for example the trigger, exclusion calendar, output format, recipient email, or FTP output. Because the JSON fragment appears as an argument in the URL, it must be properly URL-encoded (percent-encoded) as shown in the example below.

Specifies the number of jobsummary descriptors in the results. The default is -1 for no limit and thus all results are returned. When used with the offset parameter, it can be used to implement pagination of results.

Specifies the index of the first jobsummary to be returned. When used with the limit parameter, it can be used to implement pagination.

Possible values are: NONE, SORTBY_JOBID, SORTBY_JOBNAME, SORTBY_REPORTURI, SORTBY_REPORTNAME, SORTBY_REPORTFOLDER, SORTBY_OWNER, SORTBY_STATUS, SORTBY_LASTRUN, SORTBY_NEXTRUN

Determines the sort order: ascending if true, descending if false or omitted. This has no effect when sortType is not specified.

Options

accept: application/xml

accept: application/json

Typical Return Values on Failure

URL

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/

Options

accept: application/job+xml

accept: application/job+json

Typical Return Values on Failure

The time and date that the job was first created, managed internally by the server.

The ID of the job assigned by the server. Use this ID to read, modify, or delete the job.

An internal version number that has no outside use.

The owner and creator of this job, including the organization name. Note that only administrators can view other users' jobs.

A name for the job, like the label of a resource in the repository.

A description string for the job, often describes the trigger and chosen output.

The default value is DEFAULT, and for scheduling a report no other value is accepted. In a schedule for a dashboard, DEFAULT indicates that output will be a screenshot in the chosen format, for example an image in a Word file. When this is set to DASHBOARD_DETAILED for a dashboard schedule, the dashlets are exported as individual reports sequentially into the same file. Not all output formats are available depending on the value of exportType (see next property).

Contains a list of output formats, each to be generated in a separate output file when the job is triggered. The possible values depend on the resource and the exportType above:

The XLS and XLS_NOPAG (Excel 2003) output formats are deprecated. You can use XLSX and XLSX_NOPAG (Excel 2016) instead. Older jobs that are still running a request for XLS or XLS_NOPAG outputs, generate output in the XLSX or XLSX_NOPAG format.

The time zone to use when running the report or dashboard, for example "America/Los_Angeles". By default the scheduler runs the report or dashboard using the server's default time zone. The time zone names are those supported by java.time.ZoneID, which are defined in the tz database.

The trigger time zone and the output time zone have different purposes, even if they are often set to the same value. The trigger time zone determines when the job will run, whereas the output time zone affects any time or date calculations in the report or dashboard. The time zone specified in a data source also affects times and dates in the output.

The locale to use when running the report or dashboard, if it is based on a Domain with locales defined. By default the scheduler runs the report or dashboard using the server's default locale. If the report or dashboard is not based on a Domain with locales, this value has no effect. Use a Java locale string that is also defined in your Domain, for example fr (French) or fr_CA (French from Canada).

The basename of the file for the generated report output. Each output format appends its corresponding file extension to this name. This name may also have a time stamp appended as specified in Job Output Properties. This final output name is then used in all locations where the file is saved: repository, file system, FTP, and email attachment.

A container for the properties that define the repository URI of the report, report option, or dashboard and its input controls. See Source and Input Controls.

A container for one of the triggers specified in Simple Trigger or Calendar Trigger. The trigger determines how often the job runs and the date and times at which it runs.

A container for properties that define the folders and filenames for the output files that are generated each time a scheduled job runs successfully. Its properties are defined in Job Output Properties and the optional FTP Output.

A container for properties that define email recipients when a job runs successfully. You can customize the contents of the email and whether the report output files are sent as attachments or links. For more information, see Job Output Email.

A container for the following properties.

A mandatory property that defines the repository URI of the report, report option, or dashboard to run for this job. The repository URI is relative to the scope of the user credentials used to authenticate the REST call.

When scheduling a dashboard, the default output is a screenshot and these properties specify the dimensions in pixels of the dashboard canvas. The images in the output will have these dimensions, even inside another format such as PDF. The default size is 1280 width by 800 height.

A container for the following properties, itself contained in a required trigger. For input, you must specify either the simpleTrigger or the calendarTrigger.

An internal ID of the simple trigger that has no outside use.

An internal version number that has no outside use.

The timezone for all dates and times used by the trigger, for example "America/Los_Angeles". By default, the trigger uses the same time zone as the server. The time zone names are those supported by java.time.ZoneID, which are defined in the tz database.

Determines when the job becomes active and sets the base time at which recurrence starts. Supported values:

START_TYPE_NOW - The job starts immediately, and the trigger fires right away. This is the default value when this property is omitted.

START_TYPE_SCHEDULE - The job starts at the startDate, at which time it will fire.

The date and time at which the job will start, required when startType=START_TYPE_SCHEDULE. The simple trigger will fire at this time, and it will begin its recurrence at this time. The format is "yyyy-MM-dd HH:mm" and the timezone property is applied.

The date and time at which the job will stop. The trigger will not fire after this time, even if any occurrences still remain, unless a misfire occurs and the misfire policy allows it. The format is "yyyy-MM-dd HH:mm" and the timezone property is applied.

An integer that defines how many times the trigger will fire, provided the recurrence intervals happen before the endDate.

The time interval between firings of the trigger, with the interval unit provided in the next property.

The unit of time for the recurrence interval. Supported values: MINUTE, HOUR, DAY, or WEEK. For units greater than MINUTE, the startType and startDate determine the basis for recurrence. For example, if the trigger fires immediately and recurs every 2 days, it will fire at the current time on the subsequent days.

The name of a previously defined exclusion calendar. An exclusion calendar defines a set of dates or times when the job will not run, for example a list of holidays. You can update the exclusion calendar without changing the job. For information about creating and modifying exclusion calendars, see The calendars Service.

No instruction (same behavior as option -1 below). Does not trigger the job that misfired, and takes no action. Because the trigger did not fire, the number of occurrences is not decremented. This is the default behavior if no misfireInstruction is defined. The trigger will fire the next time according to the recurrence value and unit, as if the misfire had fired at the proper time.

Ignore misfire policy. Instructs the scheduler that the trigger will never be evaluated for a misfire situation, and that the scheduler will simply try to fire it as soon as it can, and then update the trigger as if it had fired at the proper time. This value has the same effect as 0: take no action and do not change the number of occurrences.

Called the smart policy. Instructs the scheduler that upon a misfire situation, the custom updateAfterMisfire method will be called on the trigger to determine the misfire action. In this case, you must define and enable a custom trigger class on the server, which is beyond the scope of this documentation.

Run now: instructs the scheduler to trigger now, which is the time the misfire is detected. If the outage covers several trigger times, they will each have a misfire, and with this value, they will each run now.

Instructs the scheduler that upon a misfire situation, the SimpleTrigger will be re-scheduled to 'now' (even if the associated calendar excludes 'now') with the repeat count left as-is. This does obey the trigger end-time, so if 'now' is after the end-time, the trigger will not fire.

Instructs the scheduler that upon a misfire situation, the SimpleTrigger will be re-scheduled to 'now' (even if the associated Calendar excludes 'now') with the repeat count set to what it would be, if it had not missed any firings. This does obey the trigger end-time, so if 'now' is after the end-time the Trigger will not fire.

Ignores any missed firings of the trigger (no action is taken for the missed firing), but the repeat count is set to what it would be if the trigger had fired normally. The trigger will fire at the next scheduled time after the current time, taking into account any associated exclusion calendar or end time. The effect is that missed trigger occurrences will be skipped.

A container for the following properties, itself contained in a required trigger. For input, you must specify either the simpleTrigger or the calendarTrigger.

An internal ID of the calendar trigger that has no outside use.

An internal version number that has no outside use.

The timezone for all dates and times used by the trigger, for example "America/Los_Angeles". By default, the trigger uses the same time zone as the server. The time zone names are those supported by java.time.ZoneID, which are defined in the tz database.

Determines when the job becomes active. Supported values:

START_TYPE_NOW - The job starts immediately, and the trigger may fire right away. This is the default value when this property is omitted.

START_TYPE_SCHEDULE - The trigger will not fire until the specified startDate.

The date and time at which the job will be active, required when startType=START_TYPE_SCHEDULE. The trigger will not fire before this time; it will only fire for calendar occurrences that happen after this time. The format is "yyyy-MM-dd HH:mm" and the timezone property is applied.

The date and time at which the job will stop. The trigger will not fire after this time, unless a misfire occurs and the misfire policy allows it. The format is "yyyy-MM-dd HH:mm" and the timezone property is applied.

The name of a previously defined exclusion calendar. An exclusion calendar defines a set of dates or times when job will not run, for example a list of holidays. You can update the exclusion calendar without changing the job. For information about creating and modifying exclusion calendars, see The calendars Service.

Specifies the minute or minutes at which the trigger fires on a given hour. The value can consist of the following tokens:

Specifies the hour or hours during which the trigger fires on a given day. The minutes property determines when during the hour that the trigger will fire, possibly multiple times. All hours are specified in 24-hour format. The value can consist of the following tokens:

A list of month values during which the trigger fires. Can be used in addition to weekDays or monthDays below to suppress the trigger during certain months. The month values are 1 for January and 12 for December. In JSON, it has the following syntax:

"months": {
    "month": ["3", "6", "9", "12"]
}

Determines how the trigger days are defined:

Specifies a list of days of the week on which the trigger fires, to be repeated every week. This is required if daysType=WEEK, and ignored otherwise. The day values are 1 for Sunday and 7 for Saturday. On the designated days, the trigger fires at the time or times defined by the hours and minutes properties. In JSON, it has the following syntax:

"weekDays": {
    "day": ["1", "4", "6"]
}

Specifies the days of the month on which the trigger fires, to be repeated every month. This is required if daysType=MONTH, and ignored otherwise. On the designated days, the trigger fires at the time or times defined by the hours and minutes properties. The value can consist of the following tokens:

No instruction (same behavior as option -1 below). Does not trigger the job that misfired, and takes no action. This is the default behavior if no misfireInstruction is defined. The trigger will fire the next time according to the times and days that were defined.

Ignore misfire policy. Instructs the scheduler that the trigger will never be evaluated for a misfire situation, and that the scheduler will simply try to fire it as soon as it can, and then update the trigger as if it had fired at the proper time. This value has the same effect as 0: take no action and wait for the next calendar trigger.

Called the smart policy. Instructs the scheduler that upon a misfire situation, the custom updateAfterMisfire method will be called on the trigger to determine the misfire action. In this case, you must define and enable a custom trigger class on the server, which is beyond the scope of this documentation.

Run now: instructs the scheduler to trigger now, which is the time the misfire is detected. If the outage covers several trigger times, they will each have a misfire, and with this value, they will each run now.

A container for the following properties.

An internal ID of the repository destination that has no outside purpose.

An internal version number that has no outside purpose.

A boolean that determines whether the output is written as file resources in the repository. The default value is true. Use the next two parameters to specify the location of the files. When false, no output is written to the repository, local file system, or remote FTP, and the output files are sent only by email if configured.

A boolean that determines if the output is written to the default folder: /public/Samples/Reports or /public/Samples/Dashboards (these folders can be configured as described in the JasperReports Server Administrator Guide). By default, this is false and you must specify the folderURI.

Defines a folder in the repository where the output file resources will be saved. This repository URI is relative to the scope of the user who authenticates the REST call. This property is required if you do not use the default output folder above.

A string that becomes the description of the output file resources in the repository.

A boolean that indicates whether output files have the time stamp pattern in the next parameter appended to the base filename. The default value is false.

A string containing "yyyyMMddHHmm" tokens to append a timestamp to the base filename. This takes effect if sequentialFilenames is true. For example, an hourly trigger might use "yyyyMMdd-HHmm" but a daily trigger only "yyyy-MM-dd". Characters in the pattern must be valid in file names where the output is being written (repository, local file system, or remote FTP). There is an implicit "-" (dash) character added between the base file name and the pattern, for example the pattern "MM-dd" becomes basename-02-14.pdf.

A boolean to determine the behavior when a newly generated output file has the same name as a previous one. When true, the new file will overwrite the old one; when false, the old file is not overwritten and the new file is not stored, though it will be sent by email if configured. The default value is true. Use the sequentialFilenames and timestampPattern to create unique file names if you wish to store every generated output.

Specifies a path in the local file system (of the JasperReports Server host) for writing output files. The user running the server process must have write permission in that location. When specified, file system output is always in addition to repository output, and the output will be written to both the repository and the local folder.

Before setting this property, the server must be configured to allow it. In the file .../WEB-INF/applicationContext.xml, you must set the enableSaveToHostFS property to true. However, this setting also enables file system output from the scheduler user interface for all users, which could be a security risk.

The file names to be written are the same as for the repository, therefore the baseOutputFilename and sequential pattern must be valid on the host file system. The file overwrite and sequential filename behavior also apply to file system output.

A container for the following properties, itself contained in repositoryDestination.

Type of FTP connection requested: ftp (default), ftps, or sftp.

The domain and host name of the FTP server, for example "ftp.example.com".

Integer value that specifies the port number of the FTP server. The default value depends on the connection type: ftp = 21, ftps = 990, and sftp = 22.

The login user name for the FTP server.

The login password for the given userName on the FTP server.

The path of the folder where the job output resources should be created.

Specifies the security mode for FTPS, Implicit if true (default) or Explicit if false. If implicit is true, the default port is set to 990.

Specifies the secure socket protocol to be used, for example SSL or TLS.

Specifies the PROT command for FTP. Supported values:

Specifies the protection buffer size: a decimal integer from 0 to (2^32)-1. The default is 0.

When using SFTP authentication, store the SSH key file in the repository and specify its repository URI in this property. For more information about secure files in the repository, see the JasperReports Server Administrator Guide.

This container and the following properties are optional. When omitted, the report output is not sent by email.

An internal ID of the mailNotification container that has no outside purpose.

An internal version number that has no outside purpose.

A list of addresses to which job output emails are sent. This property is required if you are sending output email.

A list of addresses to which job output emails are CC'd.

A list of addresses to which job output emails are BCC'd.

A string that is used as a subject line for all output emails from this job.

A string that is used in the body of output emails for this job, unless HTML output is selected for the email body below.

Determines whether output files are attached to the notification email. Each value has a different behavior and you must set this property based on your other properties:

SEND - The links to the report output in the repository are appended to the message body, and no files are attached. This option is valid only if saveToRepository is set to true in the job descriptor.

SEND_ATTACHMENT - The output files are sent as individual attachments to the email.

SEND_EMBED - The HTML output is embedded in email body, and any other output files are sent as individual attachments. This option is valid only if HTML output is specified in outputFormats for a report.

SEND_ATTACHMENT_ZIP_ALL - The output files are sent as a single zipped attachment to the email.

SEND_EMBED_ZIP_ALL_OTHERS - The HTML output is embedded in the email body, and any other output files are sent as a single zipped attachment. This option is valid only if HTML output is specified in outputFormats for a report.

A boolean that suppresses the output email when the report is empty (successful completion but no content).

Two legacy properties that do not affect email notification. Use the properties in the alert container below to specify failure notifications.

This container and the following properties are optional. When omitted, the server sends only the default notifications listed above.

An internal ID of the alert container that has no outside purpose.

An internal version number that has no outside purpose.

Selects which job status events trigger an email notification: ALL, FAIL_ONLY, SUCCESS_ONLY, or NONE. This property is required if you are sending status email, however NONE is the same as not specifying alert.

A list of addresses to which job status emails are sent. This property is required if you are sending status email.

A string that is used as a subject line for all status email from this job.

A string that is used in the body of an email for a successful job completion.

A string that is used in the body of an email when the job fails. Additional information can be added to failure notifications with the following two properties.

Appends the job info (label and id) to the email body.

URL

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/

Content

A well-formed XML or JSON job descriptor as described in The job Descriptor. You need only specify the relevant properties in the job descriptor; do not include any null properties.

Options

accept: application/job+xml

accept: application/job+json

Typical Return Values on Failure

URL

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/state/

Typical Return Values on Failure

URL

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/

Content

A complete, well-formed XML or JSON job descriptor, as described in The job Descriptor. It may include null properties and other default values that are ignored when using the descriptor as input, as in the result of Viewing a Job Definition.

Options

accept: application/job+xml

accept: application/job+json

Typical Return Values on Failure

URL

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs?<arguments>

Description

Can be used multiple times to create a list of job IDs to update.

Specify true when you send a new trigger type. By default, this is false, and the trigger can be updated but not changed to a different type.

Content

A well-formed jobModel descriptor, which is a fragment of a job descriptor containing only the properties to be updated. See the examples below.

Options

accept: application/json

accept: application/xml

Typical Return Values on Failure

URL

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/pause/

Content

An array or list of job IDs to pause. See the example below. If the body of the request is empty, or the list is empty, all jobs in the scheduler will be paused.

Options

accept: application/json

accept: application/xml

Typical Return Values on Failure

URL

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/resume/

Content

An array or list of job IDs to resume. See the example below. If the body of the request is empty, or the list is empty, all paused jobs in the scheduler will resume.

Options

accept: application/json

accept: application/xml

Typical Return Values on Failure

URL

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/restart/

Content

An array or list of job IDs to restart. See the example below.

Options

accept: application/json

accept: application/xml

Typical Return Values on Failure

URL

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/

Typical Return Values on Failure

URL

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs?<arguments>

Description

Enter as many job IDs as you want to delete, for example:

?id=5594&id=5640&id=5762

Options

accept: application/xml

accept: application/json

Typical Return Values on Failure

Configuration File

.../WEB-INF/applicationContext-cascade.xml

Description