As described in The reports Service , synchronous report execution blocks the client waiting for the response. When managing large reports that may take minutes to complete, or when running a large number of reports simultaneously, synchronous report execution slows down the client or uses many threads, each waiting for a report.
The rest_v2/reportExecutions service provides asynchronous report execution, so that the client does not need to wait for report output. Instead, the client obtains a request ID and periodically checks the status of the report to know when it is ready (also called polling). When the report is finished, the client can download the output. Alternatively, the client can check when specific pages are finished and download available pages. The client can also send an asynchronous request for other export formats (PDF, Excel, and others) of the same report. Again the client can check the status of the export and download the result when the export has completed.
Reports being scheduled on the server also run asynchronously, and reportExecutions allows you to access jobs that are triggered by the scheduler. Finally, the reportExecutions service allows the client to stop and remove any report execution or job that has been triggered.
This chapter includes the following sections:
| • | Running a Report Asynchronously |
| • | Polling Report Execution |
| • | Requesting Page Status |
| • | Requesting Report Execution Details |
| • | Requesting Report Output |
| • | Requesting Report Bookmarks |
| • | Exporting a Report Asynchronously |
| • | Modifying Report Parameters |
| • | Polling Export Execution |
| • | Finding Running Reports and Jobs |
| • | Stopping Running Reports and Jobs |
| • | Removing a Report Execution |
Running a Report Asynchronously
In order to run a report asynchronously, the reportExecutions service provides a method to specify all the parameters needed to launch a report. Report parameters are all sent as a reportExecutionRequest object. The response from the server contains the request ID needed to track the execution until completion.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions | ||
| Content-Type | Content | ||
| application/xml application/json | A complete ReportExecutionRequest in either XML or JSON format. See the example and table below for an explanation of its properties. | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content contains a ReportExecution descriptor. See below for an example | 403 Forbidden – When the logged-in user does not have permission to access the report in the request. 404 Not Found – When the report URI specified in the request does not exist. | ||
The following example shows the structure of the ReportExecutionRequest:
/supermart/details/CustomerDetailReport true 900 false false html true false 1-5 value 1 value 2 another value [/code] |
The following table describes the properties you can specify in the ReportExecutionRequest:
When successful, the reply from the server contains the reportExecution descriptor. This descriptor contains the request ID and status needed in order for the client to request the output. There are two statuses, one for the report execution itself, and one for the chosen output format.
The following descriptor shows that the report is still executing (<status>execution</status>).
The value of the async property in the request determines whether or not the report output is available when the response is received. Your client should implement either synchronous or asynchronous processing of the response depending on the value you set for the async property.
Polling Report Execution
When requesting reports asynchronously, use the following method to poll the status of the report execution. The request ID in the URL is the one returned in the reportExecution descriptor.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID/status/ | ||
| Options | Sample Return Value | ||
| accept: application/xml (default) | |||
| accept: application/status+xml | input.controls.validation.error Input controls validation failure Specify a valid value for type Integer. failed[/code] | ||
| accept: application/json | |||
| accept: application/status+json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content contains the report status, as shown above. In the extended format, error reports contain error messages suitable for display. | 404 Not Found – When the specified requestID does not exist. | ||
Requesting Page Status
When requesting reports asynchronously, you can also poll the status of a specific page during the report execution. The request ID in the URL is the one returned in the reportExecution descriptor.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID/pages/pageNumber/status | ||
| Options | Sample Response Content | ||
| accept: application/status+json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content contains the page status, as shown above. | 404 Not Found – When the request ID specified in the request does not exist. | ||
Requesting Report Execution Details
Once the report is ready, your client must determine the names of the files to download by requesting the reportExecution descriptor again. Specify the requestID in the URL as follows:
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID | ||
| Options | |||
| accept: application/xml accept: application/json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content contains a ReportExecution descriptor. See below for an example. | 404 Not Found – When the request ID specified in the request does not exist. | ||
The reportExecution descriptor now contains the list of exports for the report, including the report output itself and any other file attachments. File attachments such as images and JavaScript occur only with HTML export.
Requesting Report Output
After requesting a report execution and waiting synchronously or asynchronously for it to finish, your client is ready to download the report output.
Every export format of the report has an ID that is used to retrieve it. For example, the HTML export in the previous example has the ID 195a65cb-1762-450a-be2b-1196a02bb625. To download the main report output, specify this export ID in the following method:
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID/exports/ exportID/outputResource | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content is the main output of the report, in the format specified by the contentType property of the outputResource descriptor, for example: text/html | 400 Bad Request – When invalid values are provided for export options in the request body. 404 Not Found – When the request ID specified in the request does not exist. | ||
For example, to download the main HTML of the report execution response above, use the following URL:
GET http://localhost:8080/jasperserver-pro/rest_v2/reportExecutions/b487a05a-4989-8b53-b2b9-b54752f998c4/exports/195a65cb-1762-450a-be2b-1196a02bb625/outputResource
| | JasperReports Server does not support exporting Highcharts charts with background images to PDF, ODT, DOCX, or RTF formats. When exporting or downloading reports with Highcharts that have background images to these formats, the background image is removed from the chart. The data in the chart is not affected. |
To download file attachments for HTML output, use the following method. You must download all attachments to display the HTML content properly. The given URL is the default path, but it can be modified with the attachmentsPrefix property in the reportExecutionRequest, as described in Running a Report Asynchronously.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID/exports/exportID/attachments/fileName | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content is the attachment in the format specified in the contentType property of the attachment descriptor, for example: image/png | 404 Not Found – When the request ID specified in the request does not exist. | ||
For example, to download the one of the images for the HTML report execution response above, use the following URL:
Requesting Report Bookmarks
Some reports have additional meta-information associated with them, such as bookmarks and indexes of report sections or parts. Clients can use this information to create a table of contents for the report with links to the bookmarks and parts that are defined by the report. After running a report, you can request this information using the same request ID.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID/info | ||
| Options | Sample Response Content | ||
| accept: application/json accept: application/xml | A structure that contains bookmarks and report parts, as shown below. | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content contains the report meta-information, as shown below. | 404 Not Found – When the request ID specified in the request does not exist. | ||
Example of a request URL:
JSON:
Exporting a Report Asynchronously
After running a report and downloading its content in a given format, you can request the same report in other formats. As with exporting report formats through the user interface, the report does not run again because the export process is independent of the report.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID/exports/ | ||
| Content-Type | Content | ||
| application/xml application/json | Send an export descriptor in either XML or JSON format to specify the format and details of your request. For example: html 10-20 ./images/[/code] | ||
| Options | |||
| accept: application/xml (default) accept: application/json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content contains an exportExecution descriptor. See below for an example. | 404 Not Found – When the request ID specified in the request does not exist. | ||
The following example shows the exportExecution descriptor that the server sends in response to the export request:
Modifying Report Parameters
You can update the report parameters, also known as input controls, through a separate method before running a report execution again. For more operations with input controls, see The inputControls Service.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID/parameters | ||
| Argument | Type/Value | Description | |
| freshData | true | When data snapshots are enabled, you must set this to true to force the server to get fresh data when you change parameters. This overrides the default valeu of false, as explained in the table of properties in Running a Report Asynchronously. | |
| Media-Type | Content | ||
| application/json | |||
| application/xml | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 204 No Content – There is no content to return. | 404 Not Found – When the request ID specified in the request does not exist. | ||
Polling Export Execution
As with the execution of the main report, you can also poll the execution of the export process. This service supports the extended status value that includes an appropriate message.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID/exports/ | ||
| Options | Sample Return Value | ||
| accept: application/xml (default) | |||
| accept: application/status+xml | |||
| accept: application/json | |||
| accept: application/status+json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content contains the export status, as shown above. In the extended format, error reports contain error messages suitable for display. | 404 Not Found – When the specified request ID does not exist. | ||
For example, to get the status of the HTML export in the previous example, use the following URL:
GET http://localhost:8080/jasperserver-pro/rest_v2/reportExecutions/912382875_1366638024956_2/exports/195a65cb-1762-450a-be2b-1196a02bb625/status
When the status is "ready" your client can download the new export output and any attachments as described in Requesting Report Output. For example:
Finding Running Reports and Jobs
The reportExecutions service provides a method to search for reports that are running on the server, which includes asychronous reports that are still running and those that are finished but still in the cache and available by their request ID.
The search for reports also includes report jobs triggered by the scheduler, both running and finished but still in the cache.
To search for running or finished reports, use the search arguments with the following URL:
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions?<arguments> | ||
| Argument | Type/Value | Description | |
| reportURI | Optional String | This string matches the repository URI of the running report, relative the currently logged-in user’s organization. | |
| jobID | Optional String | For scheduler jobs, this argument matches the ID of the job that triggered the running report. | |
| jobLabel | Optional String | For scheduler jobs, this argument matches the name of the job that triggered the running report. | |
| userName | Optional String | For scheduler jobs, this argument matches the user ID that created the job. | |
| fireTimeFrom | Optional | For scheduler jobs, the fire time arguments define a range of time that matches if the job that is currently running was triggered during this time. You can specify either or both of the arguments. Specify the date and time in the following pattern: yyyy-MM-dd'T'HH:mmZ. | |
| fireTimeTo | |||
| Options | |||
| accept: application/xml (default) accept: application/json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content is a descriptor for each of the matching results. | 204 No Content – When the search results are empty. | ||
The response contains a list of summary reportExecution descriptors, for example in XML:
Given the request ID, you can obtain more information about each result by downloading the full reportExecution descriptor, as described in Requesting Report Execution Details.
For security purposes, the search for running reports has the following restrictions:
| • | The system administrator (superuser) can see and cancel any report running on the server. |
| • | An organization admin (jasperadmin) can see every running report, but can cancel only the reports that were started by a user of the same organization or one of its child organizations. |
| • | A regular user can see every running report, but can cancel only the reports that he initiated. |
Stopping Running Reports and Jobs
To stop a report that is running and cancel its output, use the PUT method and specify a status of "cancelled" in the body of the request.
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID/status/ | ||
| Content-Type | Content | ||
| application/xml application/json | Send a status descriptor in either XML or JSON format with the value cancelled. For example: XML: <status>cancelled</status> JSON: { "value": "cancelled" } | ||
| Options | |||
| accept: application/xml (default) accept: application/json | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – When the report execution was successfully stopped, the server replies with the same status: XML: <status>cancelled</status> JSON: { "value": "cancelled" } 204 No Content – When the report specified by the request ID is not running, either because it finished running, failed, or was stopped by another process. | 404 Not Found – When the request ID specified in the request does not exist. | ||
Removing a Report Execution
Deleting a report that has been executed removes it from the cache and makes its output no longer available. If the report execution is still running, it is stopped automatically then removed.
| Method | URL | ||
| DELETE | http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID | ||
| Return Value on Success | Typical Return Values on Failure | ||
| 204 No Content – The report execution was successfully removed. | 404 Not Found – When the request ID specified in the request does not exist. | ||
Recommended Comments
There are no comments to display.