Running a Report Asynchronously

In order to run a report asynchronously, the v2/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:

<reportExecutionRequest>
    <reportUnitUri>/supermart/details/CustomerDetailReport</reportUnitUri>
    <async>true</async>
    <freshData>false</freshData>
    <saveDataSnapshot>false</saveDataSnapshot>
    <outputFormat>html</outputFormat>
    <interactive>true</interactive>
    <ignorePagination>false</ignorePagination>
    <pages>1-5</pages>
    <parameters>
        <reportParameter name="someParameterName">
            <value>value 1</value>
            <value>value 2</value>
        </reportParameter>
        <reportParameter name="someAnotherParameterName">
            <value>another value</value>
        </reportParameter>
    </parameters>
</reportExecutionRequest>

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

Report Execution Properties

Property

Required or Default

Description

reportUnitUri

Required

Repository path (URI) of the report to run. For commercial editions with organizations, the URI is relative the the logged-in user’s organization.

outputFormat

Required

Specifies the desired output format: pdf, html, xls, xlsx, rtf, csv, xml, docx, odt, ods, jprint.

freshData

false

When data snapshots are enabled, specifies whether the report should get fresh data by querying the data source or if false, use a previously saved data snapshot (if any). By default, if a saved data snapshot exists for the report it will be used when running the report.

saveDataSnapshot

false

When data snapshots are enabled, specifies whether the data snapshot for the report should be written or overwritten with the new data from this execution of the report.

interactive

true

In a commercial editions of the server where HighCharts are used in the report, this property determines whether the JavaScript necessary for interaction is generated and returned as an attachment when exporting to HTML. If false, the chart is generated as a non-interactive image file (also as an attachment).

ignorePagination

false

When set to true, the report is generated as a single long page. This can be used with HTML output to avoid pagination.

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.

transformerKey

Optional

Advanced property used when requesting a report as a JasperPrint object. This property can specify a JasperReports Library generic print element transformers of class net.sf.jasperreports.engine.export. GenericElementTransformer. These transformers are pluggable as JasperReports. extensions

attachmentsPrefix

attachments

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

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

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

parameters

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 is still executing (<status>execution</status>).

<reportExecution>
    <currentPage>1</currentPage>
    <exports>
        <export>
            <id>html</id>
            <status>queued</status>
        </export>
    </exports>
    <reportURI>/supermart/details/CustomerDetailReport</reportURI>
    <requestId>677629003_1355225037212_1</requestId>
    <status>execution</status>
</reportExecution>

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.

Version: 
Feedback