Jump to content
Changes to the Jaspersoft community edition download ×
  • This documentation is an older version of JasperReports® IO User Guide. View the latest documentation.

    As described in REST API Reference - 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. 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.

    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>/jrio/rest_v2/reportExecutions

    Content-Type

    Content

    application/json

    A complete ReportExecutionRequest in 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

    404 Not Found – When the report URI specified in the request does not exist.

    The following example shows the structure of the ReportExecutionRequest:

    The following table describes the properties you can specify in the ReportExecutionRequest:

    Property

    Required or Default

    Description

    reportUnitUri

    Required

    Repository path (URI) of the report to run.

    outputFormat

    Required

    Specifies the desired output format:

    Regular output:

    html, pdf, csv, docx, pptx, xls, xlsx, rtf, odt, ods, xml

    Metadata output:

    data_csv, data_xls, data_json

    ignorePagination

    Optional

    When set to true, the report is generated as a single long page. This can be used with HTML output to avoid pagination. When omitted, the ignorePagination property on the JRXML, if any, is used.

    pages

    Optional

    Specify a page range to generate a partial report. The format is:
    <startPageNumber>-<endPageNumber>

    async

    false

    Determines whether reportExecution is synchronous or asynchronous. When set to true, the response is sent immediately and the client must poll the report status and later download the result when ready. By default, this property is false and the operation will wait until the report execution is complete, forcing the client to wait as well, but allowing the client to download the report immediately after the response.

    attachmentsPrefix

    attachments

    For HTML output, this property specifies the URL path to use for downloading the attachment files (JavaScript and images). The full path of the default value is:

    {contextPath}/rest_v2/reportExecutions/{reportExecutionId}/exports/{exportExecutionId}/attachments/

    You can specify a different URL path using the placeholders {contextPath}, {reportExecutionId}, and {exportExecutionId}.

    baseUrl

    String

    Specifies the base URL that the report will use to load static resources such as JavaScript files.

    parameters

    see example

    A list of input control parameters and their values.

    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 was placed in the report execution queue ("status":"queued"):

    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.

    This service supports the extended status value that includes an appropriate message.

    Method

    URL

    GET

    http://<host>:<port>/jrio/rest_v2/reportExecutions/requestID/status/

    Options

    Sample Return Value

    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 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>/jrio/rest_v2/reportExecutions/requestID

    Options

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

    When requesting reports asynchronously, use the following method to poll the page status during the report execution. The executionId in the URL is the one returned in the reportExecution descriptor. This service returns a response containing reportStatus, pageFinal, and pageTimestamp attributes.

    Method

    URL

    GET

    http://<host>:<port>/jrio/rest_v2/reportExecutions/{executionId}/pages/{pageNumber}/status

    Options

    Sample Return Value

    accept: application/json

    { "value": "ready" }[/code]                    

    accept: application/status+json

    {    "reportStatus": "ready",    "pageTimestamp": "0",     "pageFinal": "true" }[/code]                    

    Return Value on Success

    Typical Return Values on Failure

    200 OK – The content contains the page status, as shown above. In the extended format, error reports contain error messages suitable for display.

    404 Not Found – When the request ID specified in the request does not exist.

    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>/jrio/rest_v2/reportExecutions/requestID/exports/ exportID/outputResource

    Response Header

    Description

    output-final

    This value indicates whether the output is in its final form or not. When false, report items such as total page count are not finalized, but output is available early. You should reload the output resource again until this value is true.

    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

    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/jrio/rest_v2/reportExecutions/b487a05a-4989-8b53-b2b9-b54752f998c4/exports/195a65cb-1762-450a-be2b-1196a02bb625/outputResource

    note-icon-ns_28x28.png.72b12ee9961b6b09f479af76e9ebf1a2.png

    JasperReports IO 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>/jrio/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:

    GET http://localhost:8080/jrio/rest_v2/reportExecutions/912382875_1366638024956_2/exports/html/attachments/img_0_46_0

    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>/jrio/rest_v2/reportExecutions/requestID/exports/

    Content-Type

    Content

    application/json

    Send an export descriptor in JSON format to specify the format and details of your request. For example:

    {    "outputFormat": "html",    "pages": "10-20",    "attachmentsPrefix": "./images/"}[/code]                    

    Options

    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 an existing report execution again. Use the following method to reexecute the report with a different set of parameter values:

    Method

    URL

    POST

    http://<host>:<port>/jrio/rest_v2/reportExecutions/requestID/parameters

    Media-Type Content

    application/json

    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>/jrio/rest_v2/reportExecutions/requestID/exports/
    exportID/status

    Options

    Sample Return Value

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

    GET http://localhost:8080/jrio/rest_v2/reportExecutions/912382875_1366638024956_2/exports/195a65cb-1762-450a-be2b-1196a02bb625/outputResource

    GET http://localhost:8080/jrio/rest_v2/reportExecutions/912382875_1366638024956_2/exports/195a65cb-1762-450a-be2b-1196a02bb625/images/img_0_46_0

    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>/jrio]/rest_v2/reportExecutions/requestID/status/

    Content-Type

    Content

    application/json

    Send a status descriptor in JSON format with the value cancelled. For example:

    JSON: { "value": "cancelled" }

    Options

    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:

    { "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 Report Execution

    Use the DELETE method to remove a report execution from cache. If the report execution is still running, it will be stopped automatically and then removed.

    Method

    URL

    DELETE

    http://<host>:<port>/jrio/rest_v2/reportExecutions/<executionID>

    Options

    accept: application/json

    Return Value on Success

    Typical Return Values on Failure

    204 No Content – When the specified execution ID is not found on the server.

    204 No Content – When the specified execution ID is not found on the server.


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...