Jump to content
Changes to the Jaspersoft community edition download ×
  • This documentation is an older version of JasperReports Server REST API Reference. View the latest documentation.

    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:

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

    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)

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

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

    note-icon-ns_28x28.png.e1ae5f578a1d039091f35719b86bf130.png

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

    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

    As of JasperReports Server 5.6, you can update the report parameters, also known as input controls before running report executions.

    Method

    URL

    GET

    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

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

    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/html/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/jasperserver-pro/rest_v2/reportExecutions/912382875_1366638024956_2/exports/html/outputResource

    GET http://localhost:8080/jasperserver-pro/rest_v2/reportExecutions/912382875_1366638024956_2/exports/html/images/img_0_46_0

    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:

    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.


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...