geoffrey.hodgins

IntroductionHow 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: RequirementsJasperReports 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. TechniquesHow URLs workhttp://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 ComponentDescriptionhttp://localhost:8080/Host and portjasperserver-pro/Application Pathflow.htmlApplication PageParameter List_flowId=dashboardRuntimeFlowKey-Value pair that defines the action (in this case executing a dashboard)dashboardResource=%2Fpublic%2FEmbedded_Demo%2FSupermart_DashboardKey-Value pair that defines the dashboard resource (pre 6.0 dashboards only)decorate=noAttribute that hides menusviewAsDashboardFrame=trueAttribute 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=jasperadminPassing login information - usernamej_password=jasperadminPassing login information - passwordtheme=themeNamePassing theme to be used Hiding decorations and main browsing menu via URLRemoving 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. 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. Log-in via URLTo 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. Security NotesA 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 passingTo 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). Using a theme to edit the UI of a dashboardHiding buttons unsuitable for embedding in this scenarioThemes 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. Editing Dashboard to remove input controlsDashboard with embedded 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: Dashboard embedded into SuperMart website with externalized 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 EditsHyperlink TargetBy 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 techniquesSmooth iFrame loadingYou 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. ConclusionThis 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 AlsoEmbedding Ad-hoc Using HTTP APIFor embedding dashboards post version 6.0: Embedding Dashboards >6.0 sample_embedded_webpage.zip embeddingwiththehttpapi.zip