The reportExecutions Service

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. 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 any report execution or job that has been triggered.

This chapter includes the following sections:

Running a Report Asynchronously
Polling Report Execution
Requesting Report Execution Details
Requesting Report Output
Exporting a Report Asynchronously
Modifying Report Parameters
Polling Export Execution
Finding Running Reports and Jobs
Stopping Running Reports and Jobs

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:

<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 to the logged-in user’s organization.

outputFormat

Required

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

As of JasperReports Server 6.0, it is also possible to specify json if your reports are designed for data export. For more information, see the JasperReports Library samples documentation.

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).

allowInlineScripts

true Affects HTML export only. If true, then inline scripts are allowed, otherwise no inline script is included in the HTML output.

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.

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 Library extensions.

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. You can also set the deploy.base.url property in the .../WEB-INF/js.config.properties file to set this value permanently. If both are set, the baseUrl parameter in this request takes precedence.

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 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>f3a9805a-4089-4b53-b9e9-b54752f91586</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.

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. As of JasperReports Server 5.6, this service supports the extended status value that includes an appropriate message.

Method

URL

GET

http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions/requestID/status/

Options

Sample Return Value

accept: application/xml (default)

<status>ready</status>

accept: application/status+xml

<status>
    <errorDescriptor>
        <errorCode>input.controls.validation.error</errorCode>
        <message>Input controls validation failure</message>
        <parameters>
            <parameter>Specify a valid value for type Integer.
            </parameter>
        </parameters>
    </errorDescriptor>
    <value>failed</value>
</status>

accept: application/json

{ "value": "ready" }

accept: application/status+json

{
    "value": "failed",
    "errorDescriptor": {
        "message": "Input controls validation failure",
        "errorCode": "input.controls.validation.error",
        "parameters": ["Specify a valid value for type Integer."]
    }
}

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>/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.

{
    "status": "ready",
    "totalPages": 47,
    "requestId": "b487a05a-4989-8b53-b2b9-b54752f998c4",
    "reportURI": "/reports/samples/AllAccounts",
    "exports": [{
        "id": "195a65cb-1762-450a-be2b-1196a02bb625",
        "options": {
            "outputFormat": "html",
            "attachmentsPrefix": "./images/",
            "allowInlineScripts": false
        },
        "status": "ready",
        "outputResource": {
            "contentType": "text/html"
        },
        "attachments": [{
            "contentType": "image/png",
            "fileName": "img_0_46_0"
        },
        {
            "contentType": "image/png",
            "fileName": "img_0_0_0"
        },
        {
            "contentType": "image/jpeg",
            "fileName": "img_0_46_1"
        }]
    },
    {
        "id": "4bac4889-0e63-4f09-bbe8-9593674f0700",
        "options": {
            "outputFormat": "html",
            "attachmentsPrefix": "{contextPath}/rest_v2/reportExecutions/{reportExecutionId}/exports/{exportExecutionId}/attachments/",
            "baseUrl": "http://localhost:8080/jasperserver-pro",
            "allowInlineScripts": true
        },
        "status": "ready",
        "outputResource": {
            "contentType": "text/html"
        },
        "attachments": [{
            "contentType": "image/png",
            "fileName": "img_0_0_0"
        }]
    }]
}

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

Response Header

Description

output-final

As of JasperReports Server 5.6, 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/jasperserver-pro/rest_v2/reportExecutions/b487a05a...

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 Report Execution Properties.

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:

GET http://localhost:8080/jasperserver-pro/rest_v2/reportExecutions/91238287...

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:

<export>
    <outputFormat>html</outputFormat>
    <pages>10-20</pages>
    <attachmentsPrefix>./images/</attachmentsPrefix>
</export>

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:

<exportExecution>
    <id>html;attachmentsPrefix=./images/</id>
    <status>ready</status>
    <outputResource>
        <contentType>text/html</contentType>
    </outputResource>
</exportExecution>

Modifying Report Parameters

As of JasperReports Server 5.6, 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

default=true

When data snapshots are enabled, new parameters must force the server to get fresh data by querying the data source. This overrides the default in Report Execution Properties.

Media-Type Content

application/json

[
    {
        "name":"someParameterName",
        "value":["value 1", "value 2"]
    },
    {
        "name":"someAnotherParameterName",
        "value":["another value"]
    }
]
application/xml
<reportParameters>
    <reportParameter name="Country_multi_select">
        <value>Mexico</value>
    </reportParameter>
     <reportParameter name="Cascading_state_multi_select">
        <value>Guerrero</value>
        <value>Sinaloa</value>
    </reportParameter>
</reportParameters>

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. As of JasperReports Server 5.6, 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/
exportID/status

Options

Sample Return Value

accept: application/xml (default)

<status>ready</status>

accept: application/status+xml

<status>
    <errorDescriptor>
        <errorCode>input.controls.validation.error</errorCode>
        <message>Input controls validation failure</message>
        <parameters>
            <parameter>Specify a valid value for type Integer.</parameter>
        </parameters>
    </errorDescriptor>
    <value>failed</value>
</status>

accept: application/json

{ "value": "ready" }

accept: application/status+json

{
    "value": "failed",
    "errorDescriptor": {
        "message": "Input controls validation failure",
        "errorCode": "input.controls.validation.error",
        "parameters": ["Specify a valid value for type Integer."]
    }
}

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/91238287...

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/jasperserver-pro/rest_v2/reportExecutions/91238287...

GET http://localhost:8080/jasperserver-pro/rest_v2/reportExecutions/91238287...

Finding Running Reports and Jobs

The reportExecutions service provides a method to search for reports that are running on the server, including report jobs triggered by the scheduler.

To search for running 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
Date/Time

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:

<reportExecutions>
    <reportExecution>
        <reportURI>repo:/supermart/details/CustomerDetailReport</reportURI>
        <requestId>2071593484_1355224559918_5</requestId>
    </reportExecution>
</reportExecutions>

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 is 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.

Version: 
Feedback
randomness