The rest_v2/jobs service provides the interface to schedule reports and manage scheduled reports (also called jobs). This service provides an API to scheduler features that were introduced in JasperReports Server 4.7, such as bulk updates, pausing jobs, FTP output and exclusion calendars.
This chapter includes the following sections:
| • | Listing Report Jobs |
| • | Extended Job Search |
| • | Viewing a Job Definition |
| • | Scheduling a Report |
| • | Viewing Job Status |
| • | Editing a Job Definition |
| • | Updating Jobs in Bulk |
| • | Pausing Jobs |
| • | Resuming Jobs |
| • | Restarting Failed Jobs |
| • | Deleting Jobs |
| • | Specifying FTP Output |
| • | Specifying File System Output |
Listing Report Jobs
Use the following method to list jobs, either all jobs managed by the scheduler or the jobs for a specific report:
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs | ||
| Argument | Type/Value | Description | |
| reportUnitURI? | /path/to/report | Optional URI of a report or report option to list all of its jobs. When specified, the results are only for the specified report or report option. | |
| Options | |||
| accept: application/xml accept: application/json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The body contains and array or list of jobsummary descriptors. | 404 Not Found – When no job is found. | ||
The jobs are described in a jobsummary element such as the following example:
| | The jobsummary XML element returned by the rest_v2/jobs service has a different structure than the element with the same name returned by the deprecated rest/jobsummary (v1) service. |
Extended Job Search
The GET method is also used for more advanced job searches. You can search by owner or for strings in the label, or you can match arbitrary fields of the job descriptor with a special syntax. You can also control the pagination and sorting order of the reply.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs?<arguments> | ||
| Argument | Type/Value | Description | |
| label | string | Performs a case-insensitive string search for this value anywhere within the label field of every job. | |
| owner | string | The name of the user who scheduled the report, in the format username|organization. | |
| reportUnitURI? | /path/to/report | Specify the URI of a report or report option to list all of its jobs. | |
| example? | JSON jobModel | Searches for jobs that match the JSON jobModel, which is a fragment of a job descriptor containing one or more fields to be matched. Because the JSON fragment appears as an argument to the URL, it must be properly URL-encoded (percent-encoded). See the example below. | |
| limit | integer | Turns on pagination of the result by specifying the number of jobsummary descriptors per results page. The default is -1 for no limit and thus no pagination (all results are returned together). | |
| offset | integer | Determines the page number in paginated results by specifying the index of the first jobsummary to be returned. | |
| sortType |
| Possible values are: NONE, SORTBY_JOBID, SORTBY_JOBNAME, SORTBY_REPORTURI, SORTBY_REPORTNAME, SORTBY_REPORTFOLDER, SORTBY_OWNER, SORTBY_STATUS, SORTBY_LASTRUN, SORTBY_NEXTRUN | |
| isAscending | true / false | Determines the sort order: ascending if true, descending if false or omitted. | |
| Options | |||
| accept: application/xml accept: application/json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The body contains and array or list of jobsummary descriptors that match the search criteria. | 404 Not Found – When no matching job is found in the server. | ||
The body of the response contains jobsummary elements, in the same format as shown in Listing Report Jobs.
The example parameter lets you specify a search on fields in the job descriptor, such as output formats. You can specify any field in the job descriptor or in any of its nested structures. Some fields may be specified in both the example parameter and in a dedicated parameter, for example label. In that case, the search specified in the example parameter takes precedence.
For example, you can search for all jobs that specify an output format of PDF. The JSON jobModel to specify this field is:
{"outputFormat":"PDF"}
And the corresponding URI, with proper encoding, is:
http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs?example=
%7b%22outputFormat%22%3a%22PDF%22%7d
Viewing a Job Definition
Once you search for and find the ID of a job, use the GET method with that specific job ID to retrieve its detailed information.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/ | ||
| Options | |||
| accept: application/job+xml accept: application/job+json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The body contains a descriptor with all details about the job. | 404 Not Found – When the specified job is not found in the server. | ||
The GET method returns a descriptor that fully describes all the aspects of a scheduled job, such as recurrence, parameters, output, email notifications, and alerts, if any. For additional options around file output, see Specifying FTP Output and Specifying File System Output.
JSON:
XML:
Scheduling a Report
To schedule a report, create its job descriptor similar to the one returned by the GET method, and use the PUT method of the jobs service. Specify the report being scheduled inside the job descriptor. You do not need to specify any job IDs in the descriptor, because the server will assign them.
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/ | ||
| Content-Type | Content | ||
| application/job+xml application/job+json | A well-formed XML or JSON job descriptor as described. | ||
| Options | |||
| accept: application/job+xml accept: application/job+json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 201 Created – The body contains the job descriptor of the newly created job. It is similar to the one that was sent but now contains the jobID for the new job. | 404 Not Found – When the report specified in the job descriptor is not found in the server. | ||
When you schedule a report, you need only specify the relevant fields in the job descriptor. For example in JSON:
The response of the PUT request is the same as the GET request shown in Viewing a Job Definition. It includes all the fields of the job descriptor, including the server-assigned ID and all the null fields.
Viewing Job Status
The following method returns the current run time state of a job:
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/state/ | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – Body contains the status descriptor. | 404 Not Found – When the specified <jobID> does not exist. | ||
Editing a Job Definition
The POST method replaces the entire definition of a job with a new descriptor. To modify an existing job definition, use the GET method to read its job descriptor, modify the descriptor as required, then use the POST method of the jobs service.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/ | ||
| Content-Type | Content | ||
| application/job+xml application/job+json | A well-formed XML or JSON job descriptor. The request can include either a complete descriptor such as the result of a GET request described in Viewing a Job Definition, or it can be a minimally sufficient descriptor as shown in Scheduling a Report. | ||
| Options | |||
| accept: application/job+xml accept: application/job+json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The response include the complete job descriptor, for an example, see Viewing a Job Definition. | 404 Not Found – When the specified <jobID> does not exist. | ||
Updating Jobs in Bulk
The POST method also supports other parameters to perform bulk updates on scheduled jobs.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs?<arguments> | ||
| Argument | Type/Value | Description | |
| id? | jobID string | Can be used multiple times to create a list of job IDs to update. | |
| replace | true / false | 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. See below. | |
| Content-Type | Content | ||
| application/json application/xml | A well-formed jobModel descriptor, which is a fragment of a job descriptor containing only the fields to be updated. See example below. | ||
| Options | |||
| accept: application/json accept: application/xml | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The array or list of jobs that were restarted. | 404 Not Found – When the specified <jobID> does not exist. | ||
In this usage, the POST method allows you to send a partial job description, called a jobModel, that contains any subset of the job descriptor's fields. This update applies to one or more jobs whose ID is specified by the id argument. For example, the following simple request will update the job description in several jobs:
However, the jobModel provides two mechanisms to create complex updates:
| • | You can describe nested structures by using the nestedNameModel equivalent element. Like the jobModel, nested model elements contain only the subset that you want to modify. Thus you could change one value within a parameter, the end date within a schedule, or an email address within a notification. |
| • | You can remove the definition of an element by using the isElementNameModified element and giving it the value true. This indicates that the element's new value is null, and thus that the element should be removed altogether from the job descriptor. |
In the following example, the description will be removed from the target jobs, and their triggers will be modified. Note that XML descriptors do not use the trigger element and thus do not have a triggerModel element:
The response has an array or list of jobId elements that were updated:
JSON: {"jobId":[8321,8322]}XML: <jobIdList> <jobId>8321</jobId> <jobId>8322</jobId> </jobIdList>[/code] |
Pausing Jobs
The following method pauses currently scheduled job execution. Pausing keeps the job schedule and all other details but prevents the job from running. It does not delete the job.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/pause/ | ||
| Content-Type | Content | ||
| application/xml application/json | An array or list of job IDs to pause. See 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 | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The array or list of jobs that were paused. |
| ||
The request and the response have the same format, an array or list of jobId elements:
JSON: {"jobId":[1236,1237,1238,1239]}XML: <jobIdList> <jobId>1236</jobId> <jobId>1237</jobId> <jobId>1238</jobId> <jobId>1239</jobId> </jobIdList>[/code] |
Resuming Jobs
Use the following method to resume any or all paused jobs in the scheduler. Resuming a job means that any defined trigger in the schedule that occurs after the time it is resumed will cause the report to run again. Missed schedule triggers that occur before the job is resumed are never run.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/resume/ | ||
| Content-Type | Content | ||
| application/xml application/json | An array or list of job IDs to resume. See 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 | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The array or list of jobs that were resumed. |
| ||
The request and the response have the same format, an array or list of jobId elements:
JSON: {"jobId":[1236,1237]}XML: <jobIdList> <jobId>1236</jobId> <jobId>1237</jobId> </jobIdList>[/code] |
Restarting Failed Jobs
Use the following method to rerun failed jobs in the scheduler. For each job to be restarted, the scheduler creates an immediate single-run copy of job, to replace the one that failed. Therefore, all jobs listed in the request body will run once immediately after issuing this command. The single-run copies have a misfire policy set so that they do not trigger any further failures (MISFIRE_ INSTRUCTION_IGNORE_MISFIRE_POLICY). If the single-run copies fail themselves, no further attempts are made automatically.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/restart/ | ||
| Content-Type | Content | ||
| application/xml application/json | An array or list of job IDs to restart. See example below. | ||
| Options | |||
| accept: application/json accept: application/xml | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The array or list of jobs that were restarted. |
| ||
The request and the response have the same array or list of jobId elements:
JSON: {"jobId":[8321,8322]}XML: <jobIdList> <jobId>8321</jobId> <jobId>8322</jobId> </jobIdList>[/code] |
Deleting Jobs
Use the DELETE method to remove jobs from the scheduler. There are two forms to specify a single job or multiple jobs to delete.
| Method | URL | ||
| DELETE | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs/<jobID>/ | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The body contains the ID of the deleted job. | 404 Not Found – When the specified job is not found in the server. | ||
| Method | URL | ||
| DELETE | http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs?<arguments> | ||
| Argument | Type/Value | Description | |
| id | Multiple String | Enter as many job IDs as you want to delete, for example: ?id=5594&id=5645&id=5761 | |
| Options | |||
| accept: application/xml accept: application/json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content is a list of deleted jobs, as shown in the example below. |
| ||
The list of deleted jobs in the response has an array or list of jobId elements:
JSON: {"jobId":[5594,5645,5761]}XML: <jobIdList> <jobId>5594</jobId> <jobId>5645</jobId> <jobId>5761</jobId> </jobIdList>[/code] |
Specifying FTP Output
The REST service allows a job to specify output to remote files through FTP (File Transfer Protocol). In addition to the repository location, you can specify an FTP server and path where JasperReports Server will write the output files when the job runs. You also need to provide a username and password to access the FTP server.
To specify these parameters, add the outputFTPInfo element to the XML job descriptor, as shown in the following example:
FTP output is always specified in addition to repository output, and the output will be written to both the repository and the FTP location. You cannot specify FTP output alone. The file names to be written are the same ones that are generated by the job output, as specified by the baseOutputFilename, sequential pattern if any, and format extensions such as .pdf. Similarly, the file overwrite and sequential filename behavior specified for repository output also apply to FTP output.
As of JasperReports Server 6.3, FTP output also supports SSH private keys stored in the repository for authentication. All of the fields for the outputFTPInfo element are described in the following table:
| Field | Description | JSON Example | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| type | Type of FTP connection requested: ftp (default), ftps, or sftp. | "type": "{ftp|ftps|sftp}" | ||||||||||||
| serverName | The host name of the FTP server. | "serverName": "ftp.example.com" | ||||||||||||
| port | Integer value that specifies the port number of the ftp server. The default value depends on the connection type: ftp = 21, sftp = 22, and ftps = 990. | "port": 21 | ||||||||||||
| userName | The login user name for the FTP server. | "userName": "anonymous" | ||||||||||||
| password | The login password for the given userName on the FTP server. | "password": "securePassword" | ||||||||||||
| folderPath | The path of the folder where the job output resources should be created. | "folderPath": "/path/to/folder" | ||||||||||||
| implicit | 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. | "implicit": {true|false} | ||||||||||||
| protocol | Specifies the secure socket protocol to be used, for example SSL or TLS. | "protocol": "TLS" | ||||||||||||
| prot | Specifies the PROT command for FTP. Supported values:
| "prot": "C" | ||||||||||||
| pbsz | Specifies the protection buffer size: 0 to (2^32)-1 decimal integer. The default is 0. | "pbsz": 0 | ||||||||||||
| sshKey | Repository URI of the SSH private key resource (used for SFTP authentication). | "sshKey": "/sshKeys/myOpenSSHKey" | ||||||||||||
| sshPassphrase | The passphrase for the SSH private key (used for SFTP authentication). | "sshPassphrase": "mySecurePhrase" |
Administrators can store SSH key files in the repository by right-clicking a folder and selecting Add Resource > File > Secure File from the context menu. For more information, see the JasperReports Server Administrator Guide.
Specifying File System Output
When configured, you can also specify a path on the local file system to write job output. The user running the server process must have write permission in that location.
In order for file system output to work, the server must be properly configured. In the file .../WEB-INF/applicationContext.xml, you must set the enableSaveToHostFS property to true. As described in the configuration chapter of the JasperReports Server Administrator Guide, this setting also enables file system output from the scheduler user interface for all users, which could be a security risk.
To create a job with file system output, add the outputLocalFolder element to the XML job descriptor, as shown in the following example:
As with FTP output, file system output is always specified in addition to repository output, and the output will be written to both the repository and the local folder. The file names to be written are the same ones that are generated by the job output, as specified by the baseOutputFilename, sequential pattern if any, and format extensions such as .pdf. Similarly, the file overwrite and sequential filename behavior specified for repository output also apply to file system output.
Recommended Comments
There are no comments to display.