Embedding using HTTP API

Introduction

How do I embed JasperReports Server in my existing web application?

JasperReports Server is a stand-alone, web-based Business Intelligence (BI) platform that provides users with Dashboards, Reports, and Analytic-Views. Traditionally, business users log into solutions like this and consume material directly from the web-interface. As BI use cases evolve, embedded Business Intelligence becomes a real need. That means, business users don't care to log into a separate solution. Why not stay within the context of the application they are working on?

There are two ways this can be achieved: 

1. Web services - Use web services to browse the JasperReports Server repository, run reports and get content. The application controls the web service calls.

OR

2. HTTP API - JasperReports Server in your application using an iFrame.

The focus of this technical article is to describe some of the methods available for embedding dashboards into a web-based solution using the HTTP API. The article highlights some tips and tricks that are available to help seamlessly integrate the functionality of JasperReports Server into other web-portals.

We'll go from this:

to this:

Requirements

  • JasperReports Server Pro or Enterprise because a Dashboard is used

  • iReport Designer or Jaspersoft Studio

This guide was written using iReport Designer Pro v5.1 and JasperReports Server Pro v5.1 running on Tomcat7. Later and earlier versions *should* work, but keep in mind changes to the product.

Techniques

How URLs work

http://localhost:8080/jasperserver-pro/flow.html?_flowId=dashboardRuntimeFlow&dashboardResource=%2Fpublic%2FEmbedded_Demo%2FSupermart_Dashboard is the URL to the SuperMart dashboard on my local host. The '?' question mark delimits the Scheme, Host, Path and Page from the parameter list (formally called a "Query"), To pass parameters with this URL, you need to delimit each name/value pair with a "&". For example, "_flowId=dashboardRuntimeFlow", "_flowId" is the variable name and "dashboardRuntimeFlow" is the value. It is delimited from the parameter, dashboardResource by the "&". (for a complete specification of a URL, please see RFC3986, Section 3).

Note that everything passed to JasperReports Server in the URL is case-sensitive, passing with incorrect case will result in it being ignored or undefined behavior.

URL Component Description
http://localhost:8080/ Host and port
jasperserver-pro/ Application Path
flow.html Application Page
Parameter List
_flowId=dashboardRuntimeFlow Key-Value pair that defines the action (in this case executing a dashboard)
dashboardResource=%2Fpublic%2FEmbedded_Demo%2FSupermart_Dashboard Key-Value pair that defines the dashboard resource (pre 6.0 dashboards only)
decorate=no Attribute that hides menus
viewAsDashboardFrame=true Attribute that signifies only the dashboard should be rendered (pre 6.0 dashboards only)
<parameterName>=<parameterValue> Parameter for a report (pre 6.0 dashboards only)
hidden_<parameterName>=<parameterValue> Parameter for a dashboard (pre 6.0 dashboards only)
j_username=jasperadmin Passing login information - username
j_password=jasperadmin Passing login information - password
theme=themeName Passing theme to be used

Supermart Dashboard

Hiding decorations and main browsing menu via URL

Removing the frame around the dashboard is quite simple. The frame includes the menu bar at the top and all that follows it down the side and bottom of the page, but does not remove . As in the example below, you pass "decorate=no" through the URL. The result is shown in the figure below. Roughly speaking, this method sets "display: none;" on the unnecessary decoration around the dashboard.

Effect of "decorate=no" on a dashboard

Removing everything but the actual dashboard involves passing "viewAsDashboardFrame=true". Unlike the above method, unnecessary things are not actually rendered at all in the document. Something to be aware of when using this method is that it blocks themes, so when trying to use an "embedded theme" like used later in this guide, nothing in the dashboard will be affected.

Effect of "viewAsDashboardFrame=true" on a dashboard

Log-in via URL

To provide login information to JasperReports Server for each request, it is possible to pass the username and password parameters through the URL. Adding "j_username=jasperadmin" and "j_password=jasperadmin" to the URL does the job. This is very simple, but very insecure. Read the security notes below for alternative, more secure methods.

Passing login info through the URL

Security Notes

A single sign-on system is the ideal way of authenticating users between applications. CAS, Cosign and JAAS are examples of open source single sign-on systems. There are a variety of commercial single sign-on vendors, like SiteMinder and Tivoli. Another option is to set up anonymous access, so that users do not have to authenticate. This means there is "no security" as you do not have to have a valid login, but this may be acceptable. You can also set anonymous users to ROLE_USER which will allow them to run reports, but not to edit them.

Report parameter passing

To pass a parameter to a dashboard you must add “hidden_” before it and the name of the parameter and input control must be the same. In the example below, parameters are being passed in the URL. The parameters being passed here are "startMonth" and "endMonth" and the number 3 and 10 are their values respectively. The list of items that the input control relates to has each month as its number value (January=1, February=2, ... , December=12).

Passing parameters to dashboard

Using a theme to edit the UI of a dashboard

Hiding buttons unsuitable for embedding in this scenario

Themes consist of a folder of images used in the theme and a "overrides_custom.css" file that overrides CSS styles from the "default" theme in JasperReports Server. First I downloaded the "jasper_dark" theme, which is already modifying the default theme, and then added the following CSS rules to the "overrides_custom.css" file. I then renamed it to "jasper_embedded" and uploaded it onto the server.

/* GETS RID OF SAVE BUTTON ON REPORTS */
#fileOptions.button.capsule.mutton.up.first { display: none;}
/* GETS RID OF THE OPEN NEW TAB BUTTON ON DASHBOARDS */
.button.action.up.open { display: none;}
/* GETS RID OF THE INPUT CONTROL BUTTON ON REPORTS */
#ICDialog.button.capsule.up { display: none;}
/* MAKE BACKGROUND GREYISH COLOUR (#E7E7E7) */
div { background: #E7E7E7;}

Editing Dashboard to remove input controls

Dashboard with embedded input controls:

Internal Input Controls

To delete the input controls of a dashboard, right-click on the respective dashboard in the repository and select "Open in designer...". Then highlight the input controls like below and delete them.

Dashboard after deleting the input controls:

Hidden Input Controls

Dashboard embedded into SuperMart website with externalized input controls:

External Input Controls

Note that, if you use external input controls, you end up rebuilding a lot of what JasperReports Server does for you. In the above example of external input controls on the SuperMart website the inputs must be created, and the updating of the parameters in the dashboard/report must be implemented. Simple HTML form buttons take care of the input part and some Javascript updates the URL of the dashboard to pass the parameters to the report in this case, but not all features will be as easy to replace.

iReport Designer Edits

By default, the reports target is set to "Blank" which opens it in a new tab (or window) when you drill-down to it from a dashboard. Doing this loses all context from the application in which it is embedded. Setting the target to "Parent" will replace the parent node with the new content, in this case the iFrame which the dashboard is shown in will be replaced by the report which has been drilled-down into.

Other techniques

Smooth iFrame loading

You can use some CSS and Javascript to make an element (iFrame in this case) load smoothly or with an effect. Here a simple "Ajax loading gif" is used and then replaced with the iFrame when it has loaded. This is an example of a technique to make seamless embeddings of JasperReports Server in your application.

Conclusion

This guide has shown some concrete examples of the steps needed to smoothly integrate JasperReports Server into an application. Not everything is best-practice, but it is simple and easy to understand. Hopefully the techniques used here are easily adaptable to whatever needs you may have.

See Also

Feedback
randomness