The HTTP interface provides an easy way to implement the API for accessing repository objects. However, the HTTP interface is not embeddable in the same way that the web services and Java APIs can be embedded in non-Jaspersoft applications. Rather, the HTTP interface is used primarily as shortcuts or entry points to commonly used features or content. Typically, the HTTP interface is accessed programmatically by generating the URL that returns HTML that displays either the desired object (in the case of report execution and repository URLs) or the content of repository objects (such as report output in the form of content resources).
For example, the SuperMart demonstration data that ships with JasperReports Server commercial editions makes frequent use of the HTTP interface. This simple API allows users to interact with the SuperMart dashboard, dynamically pass parameters from a report to an analysis view, and display the user’s personal folder based on the login ID.
As shown in the following examples, the major entry points are:
| • | flow.html |
| • | olap/** |
| • | fileview/** |
| | The examples in this section are generalized to describe both the community and commercial editions of JasperReports Server. For simplicity, this section refers to the deployment context generically. For example: With the default deployments, the <context> refers to:
The Spring Web Flow has quite different syntax for flow files as compared to earlier versions, so if a user has a custom flow, it needs to be upgraded. Spring offers a special tool, WebFlowUpgrader, which helps to upgrade the flows. For information about migrating from Spring Web Flow 1.0 to Spring Web Flow 2.0, see the Webflow documentation. |
Executing ReportUnits
The following sections provide examples and details about URLs that execute reports.
Simple Report Execution
The HTTP interface can execute and export reports within the JasperReports Server web application.
The following example calls a report without any parameters and exports to the default format (HTML):
The URL is:
This is the simplest possible report execution URL. The following section explains more advanced options.
Passing ReportUnit Execution Parameters
The following example executes the same report as shown in the previous section, but also passes 4012 as an input control parameter and exports to PDF instead of HTML:
Note the URL parameters:
| • | &customerID=4012 indicates that the value 4012 should be passed to the input control called customerID. The report returns data about customer 4012. |
| • | &output=pdf indicates that the output should be generated in PDF format. |
If the report parameter supports multiple values, you can specify them using the ampersand (&); for example:
This section describes more such parameters.
The report execution parameters can either be reserved parameters that the server uses to determine general attributes of the report execution, or they can be arbitrary parameters that correspond to the report’s input controls/parameters. The parameters are specified as standard HTTP GET parameters (that is, they are in the form name=value and are separated by ampersands (&)).
The following general parameters are recognized by JasperReports Server:
| • | reportUnit specifies the URI of the report unit resource in the repository. |
| • | output (optional) specifies the output format. Values for this parameter are keys for the report exporters configured in the server. By default, the server recognizes the following output types: pdf for PDF, xls for Excel (Paginated), xlsNoPag for Excel, xlsx for XLSX (Paginated), xlsxNoPag for XLSX, rtf for RTF, csv for CSV and swf for the Flash report viewer. When this parameter is not specified, the default format is HTML displayed in the report viewer. |
| • | reportLocale specifies the locale in which the report should be executed. A locale is passed as code consisting of a lower-case two letter ISO-639 language code, followed by optional upper-case two letter ISO-3166 country code and a locale variant, separated by underscore (the format is identical to the standard Java locale programmatic names). |
| • | userlocale also specifies a locale, but in this case, it specifies the locale of the user. It can be added to the startup URI, as in this example: |
http://localhost:8080/jasperserver-pro/login.html?userLocale=en_US
| • | j_username and j_password pass the credentials to authenticate a user with the server. The user name should correspond to a valid user, and password should be the user password (in clear text). |
If you use a commercial edition and host more than one organization, the organization ID or alias must be passed along with the user ID as part of the j_username parameter. The format is j_username=userID|orgID.
If such credential parameters are not present, and no authenticated server session exists, and the server is not configured to use automatic authentication mechanisms (such as single sign-on), the server prompts the user for a user name and a password; after logging in, she is redirected to the report execution page. These authentication parameters let the user skip the login page and directly access the report execution page.
Note that these two parameters are not specific to report execution URLs; they can be used for any URLs that point to a JasperReports Server web page.
| • | pageIndex (optional) specifies the initial page that should be displayed when launching the target report. The page index is 1-based; if a negative page index or a page index greater than the number of pages in the report is used, the report opens at the first page. This parameter is only effective when HTML is used as output. |
| • | anchor (optional) specifies the name of an anchor from the target report at which the report should open. If an anchor with the specified name is not found in the report, the first page of the report is shown. The parameter is only effective when pageIndex is not specified and when HTML is used as output. |
In addition to these standard parameters, report execution URLs can contain parameters that provide values for the report input controls/parameters. The URL parameter names must match the name of the corresponding report input control. The values used for such URL parameters depend on the type of input control:
| • | For simple, single value input controls, the value is a URL parameter value: |
| • | If the type of the input control is text, the URL parameter value is directly used as input control value. |
| • | If the type of the input control is numeric, the URL parameter value is the numerical value formatted according to standard rules, using a period (.) as the decimal separator. |
| • | If the type of the input control is date or date/time, the URL parameter value is the date/time value formatted as described in the jasperserver_config.properties file for the current locale. The following table shows the formats for the default locale: |
| Input Control Type | URL Parameter Format | Example |
| date.format | yyyy-MM-dd | 2013-06-28 |
| datetime.format | yyyy-MM-dd HH:mm:ss | 2013-06-28 13:45:22 |
| time.format | HH:mm:ss | 13:45:22 |
| • | For boolean (check box) input controls, the URL parameter value is either true of false. |
| • | For input controls that refer to static list of values, the URL parameter value is the key/value of the list entry. For example, to select the first value in a list called ListInput, use the parameter &ListInput=1. |
| • | For input controls that rely on a query, the URL parameter value corresponds to the query key/value column. For example, to set a query-based control to the value l_meade, use the parameter &QueryInput=lmeade. |
| • | For multi-value input controls, multiple occurrences of the same URL parameter can be used. For example, parameter=value1¶meter=value2¶meter=value3. |
You can use a special marker URL parameter for multi-value input controls to specify that an empty list should be used as the input control value. In this case, the name of the marker URL parameter is the name of the input control, prefixed by an underscore; it doesn't require any value. This is useful when a multi-value input control has a non-empty list as its default value, and the user wants to override the default value with an empty list.
For example, consider a multi-value input control named MultiInput. By default, this parameter is a list of two values. To override this list of values with another set of two values, you could use the parameter &MultiInput=item1&MultiInput=item2, where item1 and item2 are the overriding list values. To override the default with an empty list, use the parameter &_MultiInput.
If the report parameter values included in a report execution URL are not valid (for example, if a required parameter is missing or a parameter value is not valid), the user is prompted with the input controls so he can correct the values.
Linking to Content
The HTTP interface can return generated content saved to the repository in PDF, HTML, Excel, or RTF format.
The following example links to a PDF file stored in the repository:
Viewing Resources in the Repository
The following example displays all resources saved in the /reports/test folder in the repository:
| | The repository search mechanism was upgraded in 4.0 and the syntax for selecting a folder in the repository was updated in 4.7. HTTP interfaces developed prior to 4.7 should be updated to use the searchFlow&folderUri syntax to access a folder in the upgraded repository. HTTP interfaces developed in versions 4.0 - 4.5.1 may have trouble accessing a folder in the repository. |
The following example displays all resources of type olapview (analysis view) saved in all folders in the repository:
Recommended Comments
There are no comments to display.