You are on page 1of 44

Jaspersoft Embedding Guide

Copyright 2013 Jaspersoft Corporation. All rights reserved. Printed in the U.S.A. Jaspersoft, the Jaspersoft logo, Jaspersoft
iReport Designer, JasperReports Library, JasperReports Server, Jaspersoft OLAP, and Jaspersoft ETL are trademarks and/or
registered trademarks of Jaspersoft Corporation in the United States and in jurisdictions throughout the world. All other
company and product names are or may be trade names or trademarks of their respective owners.
This is version 0513-JSP51-01 of the Jaspersoft Embedding Guide.

TABLE OF CONTENTS
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1

Overview of Embedded BI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.2

The Five Levels of Embedded BI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6


1.2.1

1.3

1.4

Level 1: Static Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.2.2

Level 2: Managed Interactive Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.2.3

Level 3: Highly Interactive Reports and Dashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.2.4

Level 4: Self-Service Reporting and Analysis for Operational Applications . . . . . . . . . . . . . 7

1.2.5

Level 5: Advanced Analytics for Deeper Insight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Embedded BI Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3.1

JasperReports Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.3.2

Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.3.3

iframes and Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.3.4

Other Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Choosing a Level of Embedding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8


1.4.1

Matrix of Levels and Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.4.2

Roadmap for Your Embedded BI Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.4.3

Transitioning from Web Services to iframes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.5

The Embedded BI Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.6

Additional Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.6.1

User Personas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.6.2

Report Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.6.3

Administrator Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.6.4

Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.6.5

Mobile Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 2 Level 1: Using the JasperReports Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13


2.1

Business Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.2

Solution Using JasperReports Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.3

Implementing Level 1 Embedding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.4

Alternative Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Jaspersoft Embedding Guide


2.4.1

Using JasperReports Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.4.2

Using Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.4.3

Limitations to iframes for Level 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 3 Level 2: Embedding Through Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17


3.1

Business Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.2

Solution Using Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3.3

3.4

Implementing Level 2 Embedding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19


3.3.1

Installing and Configuring JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.3.2

Creating Users, Roles, and Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.3.3

Loading Reports Into the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Alternative Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3.4.1

Using Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3.4.2

Using JasperReports API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

3.4.3

Using iframes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 4 Level 3: Report and Dashboard Viewers in iframes . . . . . . . . . . . . . . . . . . . . . . . . . . 25


4.1

Business Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

4.2

Solution Using iframes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4.3

4.4

Implementing Level 3 Embedding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28


4.3.1

Creating a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

4.3.2

Customizing the User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

4.3.3

Logging Into JasperReports Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

4.3.4

Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Alternative Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.4.1

JasperReports API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

4.4.2

Hybrid Solutions with Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

4.4.3

iframe Variants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Chapter 5 Level 4: Ad Hoc Reporting in iframes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35


5.1

Business Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

5.2

Solution Using iframes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

5.3

Implementing Level 4 Embedding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

5.4

5.3.1

Creating a Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

5.3.2

Training Users on the Ad Hoc Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Alternative Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 6 Level 5: Advanced Analysis in iframes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

6.1

Business Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

6.2

Solution Using iframes, OLAP, and ETL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

6.3

Implementing Level 5 Embedding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

6.4

Alternative Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Introduction

CHAPTER 1

INTRODUCTION

JasperReports Server builds on the JasperReports Library as a comprehensive family of Business Intelligence (BI) products,
providing robust static and interactive reporting, report server, and data analysis capabilities. These capabilities are available
as either individual products, or as part of an integrated end-to-end BI suite utilizing common metadata and providing shared
services, such as security, a repository, and scheduling. The BI suite can be deployed in a stand-alone server where users log in
to view their data, or the server functionality can be embedded so that users have secure and reliable access to their data within
another application.
This guide covers the multiple ways in which reporting features can be embedded to provide BI capabilities in your
applications. The server exposes functionality through several interfaces, and the choice of features you want to embed
determines which interface you use. For example, web service APIs give access to core server functionality such as the
repository, report viewer, and scheduler. A more advanced integration with HTML iframes gives access to Ad Hoc reporting.
As a result, Jaspersoft BI provides seamless integration with a range of applications and the capability to easily add custom
functionality.
This guide is intended for solution architects who want to understand embedded BI and design an application using Jaspersoft
BI products. It is also intended for programmers who must plan and implement the code that effectively embeds the BI
features.

Architects Product managers who want to enhance their products and applications with embedded BI, and who often
create a roadmap for adding further embedded BI features.
Programmers The engineers who write the application with embedded BI features. They write the code for the user
interface (UI) as well as for the back end that responds to UI actions by invoking the BI features.
The procedures in this document assume you are familiar with JasperReports Server installation, deployment, and
administration. You must have system administrator privileges within JasperReports Server and its application server,
as well as read and write access to their files on the host.
This document also assumes you are familiar with the various programming languages and file formats that it uses,
including Java, JavaScript, XML, and HTML.

This chapter contains the following sections:

Overview of Embedded BI
The Five Levels of Embedded BI
Embedded BI Technologies
Choosing a Level of Embedding
The Embedded BI Example
Additional Considerations

Jaspersoft Embedding Guide

1.1

Overview of Embedded BI

Embedding BI is the process of adding rich data visualization and manipulation to an application by leveraging Jaspersofts BI
suite in the design and coding of an application. All of the following can be achieved by embedding Jaspersoft BI:

Reports that run on demand with output in your application or delivered in a file.
A repository of reports with secure role-based access, scheduling, and email delivery.
Interactive reports and dashboards displayed in your application.
Self-service ad hoc reporting and advanced analytics integrated into your application.

Throughout this document, the application and your application refer to the end-user application which has a need for
displaying data and in which Jaspersoft BI is embedded to fulfill that need. Your needs may be larger than a single application,
but whatever the size of your solution, the application is the interface where users access their data, and they are transparently
connected to the embedded features of Jaspersoft BI.

Figure 1-1

Overview of an Embedded JasperReports Server

For simplicity, this document assumes your application has a typical client-server architecture that users interact with through
a user interface. Even if your application is more complex and has more input and output channels, the basic architecture
remains similar.
Based on typical user scenarios and experience with numerous real-world implementations, Jaspersoft has identified five
levels of embedded BI functionality:

Level 1: Static Reporting


Level 2: Managed Interactive Reports
Level 3: Highly Interactive Reports and Dashboards
Level 4: Self-Service Reporting and Analysis for Operational Applications
Level 5: Advanced Analytics for Deeper Insight

1.2

The Five Levels of Embedded BI

A level of embedded BI is the extent to which you implement and expose Jaspersoft BI features in your application. The
different levels correspond to different user requirements, different roadmaps for your application, and also determine the
implementation architecture.
Each level is distinct based on how the personas identified above interact with the application and embedded BI features:

How users access their data.


How data analysts create reports to expose the data.
How programmers implement the UI and connect it to the embedded BI features.

Introduction

1.2.1

Level 1: Static Reporting

The most basic embedded BI is for users to select a report from a list and have it display in their interface. It is appropriate for
a small number of reports and presenting data that doesnt have underlying complexity. This level is static in two ways:

The choice of reports is static, usually implemented as buttons or menus in the UI.
The report itself is static, predetermined by the report designer. However, newer features of the JasperReports Library
allow interactive reports where tables can be sorted or filtered by the user.

Of course, whenever a report is run, it accesses its data source and presents the latest data. It is the choice of reports and layout
of the reports that are static to the user.
Jaspersofts embedded solution for level 1 is to develop your application with the JasperReports Library and create reports in a
designer such as iReport or Jaspersoft Studio. This solution is covered in Chapter 2, Level 1: Using the JasperReports
Library, on page 13.

1.2.2

Level 2: Managed Interactive Reports

In a way, level 1 is the trivial case. Your application can include any level of report management, for example role-based
access or scheduling, but you must program it yourself. However, Jaspersoft already provides a proven and secure report
server for storing, protecting, scheduling, and distributing reports.
In level 2, you embed JasperReports Server to manage your reports and provide all this functionality. In this case, embedding
means you host the server internally, and your application uses web service calls to expose its contents. Users see dynamic
lists of reports, based on the roles of their logged in identities. Users can view and export reports in any number of format. And
finally, users can schedule reports and have the output emailed as necessary. However, reports are still displayed in your own
application, as provided by the web services interface.
This solution is covered in Chapter 3, Level 2: Embedding Through Web Services, on page 17.

1.2.3

Level 3: Highly Interactive Reports and Dashboards

Level 3 embeds the more powerful report and dashboard viewers available in commercial editions of JasperReports Server:

The report viewer provide interactivity with reports, such as sorting columns and filtering rows.
The dashboard viewer provides data-rich visualizations and input controls for viewing different parameters.

Level 3 is distinct because the interactive report and dashboard viewers in JasperReports Server require the use of iframes to
display within your application. This switch in the embedding architecture certainly affects the UI and source code of your
application. In addition, level 3 and above require JasperReports Server features that are only available with a commercial
license, whereas levels 1 and 2 are implemented with either community editions or commercial editions.
This solution is covered in Chapter 4, Level 3: Report and Dashboard Viewers in iframes, on page 25.

1.2.4

Level 4: Self-Service Reporting and Analysis for Operational Applications

The next level of embedded BI is to give business users the power to explore their data and create their own reports. Level 4
exposes the Ad Hoc Editor so that users can manipulate their data interactively. End users of your application are no longer
consumers of prepared reports and dashboards, they become report creators and data explorers.
In order to expose the Ad Hoc Designer, level 4 also relies on iframes. Because all of the higher level rely on iframes,
switching to an architecture that supports them gives you the ability to expand your embedded BI offering, and thus increase
the power of your application.
Level 4 is distinct because in order to give end users access to the data, you need a metadata layer to hide the complexity of
database and protect your database. Thus, data analysts create Domains in JasperReports Server and take advantage of their
ability to select, filter, optimize, and secure data as opposed to direct database access.
This solution is covered in Chapter 5, Level 4: Ad Hoc Reporting in iframes, on page 35.

Jaspersoft Embedding Guide

1.2.5

Level 5: Advanced Analytics for Deeper Insight

Level 5 provides the same Ad Hoc interface as level 4, but it adds more capabilities to the back end to provide more powerful
analysis tools. For example, if your reporting database is growing in size and your report times are increasing, you can use
Jaspersoft ETL and take advantage of the performance benefits of OLAP analysis.
Jaspersoft ETL has rules for transforming and pre-loading your data, and thus creates an optimized data mart. However, only
data analysts and administrators access Jaspersoft ETL, therefore its user interface is not embedded in your application. Data
analysts do create OLAP cubes in the embedded instance of JasperReports Server, and users can access this analysis view
through the Ad Hoc editor. This gives your business users another powerful analysis tool for exploring their data interactively.
This solution is covered in Chapter 6, Level 5: Advanced Analysis in iframes, on page 41.

1.3

Embedded BI Technologies

This section provides an overview of the three main technologies that are used to embed Jaspersoft BI in your application.
Different levels of embedding rely on different technologies, though they can sometimes be mixed at the same level. The
implementation of the example in each level gives more details about each architecture.

1.3.1

JasperReports Library

When embedding the JasperReports Library alone, your application uses the library to fill and render reports. However, your
application must manage all interaction of the user with the reports, from storing the report files, offering choices to the user
through the user interface, and displaying the report.
JasperReports is a set of Java classes that can be bundled with a Java application. Reports are defined as XML files that can be
written by hand or designed in an editor such as Jaspersoft Studio.

1.3.2

Web Services

Web services provide a way for your application to interact with a running instance of JasperReports Server and take
advantage of its features. The web service APIs give access to the servers repository, reports, export formats, and scheduler,
all the while enforcing user and data security. You application must still provide the user interface, but it will integrate tightly
with the web services to display information from the embedded server.

1.3.3

iframes and Themes

An iframe in a browser loads and displays any URL, therefore your application displays part of the JasperReports Server user
interface directly. In order to blend the JasperReports Server user interface into that of your own application, there are
parameters you specify to remove the various menus. Furthermore, you can customize the appearance of JasperReports Server
using themes to match the fonts, sizing, and colors of your application.

1.3.4

Other Technologies

Jaspersoft and the Jaspersoft community is continuously developing new ways to embed the JasperReports Server
functionality. In particular, there are working examples using PHP web applications that can be used in non-Java
environments. For more information, see Chapter 7, Other Technologies, on page 47.

1.4

Choosing a Level of Embedding

Unlike other solutions, Jaspersoft BI provides all five levels of BI embedding, giving you flexibility and room for expansion as
you provide a rich data experience for the users of your application. You want to choose the level that provides the
functionality you wish to expose in your application and allows for expansion. In this way, the 5 levels provide a roadmap for
the embedded BI in your application.

Introduction

1.4.1

Matrix of Levels and Technologies

The following table shows which technologies are recommended for each level of embedding. Choose the technology that is
recommended for the embedded solution you want to implement. The table uses the following symbols and gives a brief
explanation for each choice:
Recommended technology at that level.
Usable technology under certain conditions.
Not recommended because difficult or impossible to implement.
At some levels, several architecture options are possible. For example, you can embed the JasperReports Server repository as
both an iframe and using web services. Choose the one that best fits the architecture and goals of your application. However, if
you plan to later include features at a higher level of embedding, you should consider iframes from the start. The difficulty of
switching from web services to iframes is shown by a double-line separating these two columns.

Table 1-1
Level
1 - Static
reports

2 - Managed
reports

3 - Interactive
reports and
dashboards
4 - Self-service
reporting and
analysis
5 - Advanced
analytics

1.4.2

Recommended Technologies for Each Level of Embedding


JasperReports API

Web Services

iframes & Themes

Flexible solution for quickly


adding reporting to Java
applications.

Requires a server instance,


but can be used in non-Java
environments.

Requires a server instance,


but can be used in web
applications.

Difficult to re-implement
report options, report scheduler,
and repository functionality

Best solution, very flexible;


works on any platform including
mobile SDKs

Solution is possible, but UI


must be customized to limit
navigation

Very difficult to re-implement


interactive reports and
dashboards.

Not possible; use


JasperReports API or iframes.

Best solution; use themes to


control appearance

Extremely difficult to reimplement report creator and inmemory data processing.

Not possible; use iframes.

Best solution; use themes to


control appearance.

Requires third party


components.

Not possible; use iframes.

Best solution; use themes to


control appearance.

Roadmap for Your Embedded BI Application

If your application is evolving, or your BI needs are changing, you should plan a path through this matrix. To avoid costly
changes of technology and re-implementation, make sure your path stays within a given technology column. You need to
predict the highest level of embedded BI that you are likely to implement in the near or far future.
Consider the following scenarios:

You need a small number of custom reports, and implementing them quickly with a minimal server footprint is essential.
You may later need more reports, or the ability to schedule a report, but that is unlikely or not a high priority.
Jaspersoft recommends embedding the JasperReports API (first column) to run reports within your application without
the need for a reporting server. If you need scheduling later, moving down the first column to level 2, it will be harder to
implement but it will be possible.

You have lots of reports with varying levels of access based on user permissions, but you dont need scheduling right
away.
Jaspersoft recommends you use web services to access an instance of the JasperReports Server. The server stores all your
reports and enforces permissions on access. Even if you do not implement scheduling right away, it is very easy to add
later.
9

Jaspersoft Embedding Guide

Even though you only have a few reports to start with, you are certain you want to embed interactive reports, dashboards,
and eventually self-service reporting.
In this case, Jaspersoft recommends implementing a solution with embedded iframes. Even if you only need simple
reporting to begin with, iframes provide a simple transition to dashboards and self-service reporting. The initial
development may be more complex, but it is the only solution that scales easily to levels 3 and 4.

The following section goes into more detail about the implementation differences between web services and iframes, and how
to handle them.

1.4.3

Transitioning from Web Services to iframes

There are significant differences between solutions using web services and those using iframes. They both rely on an instance
of JasperReports Server, but they require different modifications to the host application:

With web services, the server handles the logic of storing and running reports, and the client application handles the
display of information. The client must process the servers response, for example a list of reports, and display them to the
user in such a way to make them clickable. This is a typical client-server interaction.
With iframes, the server handles both the logic and the display, with the client only providing a window to display the
servers contents. When the user interacts with the contents of the iframe, it is the JasperReports Server that is responding
to clicks and generating the user interface. In order to select features exposed by the server and control their appearance in
the iframe, this solution often requires customization of the server interface and its themes (colors, fonts, and sizes).

Because of these differences, the transition from level 2 using strictly web services to level 3 using strictly iframes should be
carefully considered and perhaps avoided. Because the technologies are so different, such a transition would involve
discarding the level 2 solution and implementing the level 3 solution entirely, including the level 2 functionality.
If you must switch, consider a hybrid solution that includes your previous web services for some functionality and iframes for
other functionality. The same instance of JasperReports Server can respond to both kinds of clients at the same time. This
allows you to reuse your web services implementation, and it provides continuity for users. However, a hybrid solution has
some limitations of its own, such as needing to hide functionality in iframes that you already provide through web services.
For example, if your web services provide a listing of reports that does not allow users to schedule a report, you must hide the
repository functionality in the iframe because it allows users to schedule reports.
The following section introduces the embedded BI example used throughout this book. The example focuses on a the details of
a complete solution at each level, while presenting a realistic progression from each level. For example, the narrative from
level 2 to level 3 presents the hybrid solution, although it focuses on iframes technology.

1.5

The Embedded BI Example

This guide presents a scenario with a realistic business case for each of the 5 levels embedded BI functionality. For the
scenario at each level, the guide gives an overview of how the embedded BI can be implemented in a sample application.
However, this guide is not meant to be a programming guide that explains how to implement each solution.
The example is based on a fictional company named Bucks Electronics that has a chain of retail stores in several geographic
areas. Bucks Electronics develops and maintains its own inventory management system software, called IMS2. The IMS2
application is greatly enhanced by embedding Jaspersoft BI at each of the levels:
1.

At the first level, IMS2 provides a button for reporting on distributor supply levels. Inventory clerks can thus access the
system and receive a PDF of the report.

2.

At the second level, the IMS2 application provides scheduled reports on a regular basis, customized and delivered to
different store managers.

3.

At the third level, IMS2 is growing into a company-wide business intelligence solution. Employees are relying on it daily
to provide data-dense dashboards.

4.

At the fourth level, IMS2 users are requesting many custom reports, too many for a single administrator to handle. Using
data exploration in the Ad Hoc editor, they can now create, save, and run their own reports.

5.

At the fifth level, business analysts have the tools to explore their data in powerful OLAP cubes. At the same time, that
data is being collected automatically from multiple sources by ETL.

10

Introduction
While the same example company is used to present a realistic scenario at each level, the sum of all scenarios is not realistic. It
is unlikely that a company would implement every solution in sequence because of the costly transition between each level. In
particular, switching technologies from the JasperReports API to web services and web services to iframes involves a
significant re-implementation of the embedding application.
As an architect and planner, your goal is to select the level that is most likely going to be your ultimate goal, and then
implement the recommended solution once. If you anticipate changes to your requirements, factor those changes into your
initial decisions. It is often more feasible to make a given technology span several levels, rather than switch technologies every
time your requirements expand to a new level. For more information, see section 1.4.2, Roadmap for Your Embedded BI
Application, on page 9.

1.6

Additional Considerations

As you explore the possibilities of embedded BI and consider which level and which technology fits your needs, you should
keep in mind several considerations that affect your design and deployment:

User Personas Who uses your application and how they interact with the embedded BI.
Report Designer The tool and process for creating and managing reports in your solution
Administrator Functions Identifying the necessary administrative procedures and documenting them.
Performance As with any deployment, you must provides sufficient CPU and memory on the client and the server for
your anticipated user load.
Mobile Deployment Whether your application supports mobile devices or will in the future, and how JasperReports
Server can be accessed via mobile.

These topics are introduced in the following sections, but their detailed analysis is beyond the scope of this document.

1.6.1

User Personas

Architects and programmers who design and implement an embedded BI solution must consider the following user personas:

Business users End users who access your application and invoke features that rely on embedded BI.
Administrators IT users who deploy and maintain your application. They must also deploy and maintain the BI features,
usually an instance of JasperReports Server.
Data Analysts Database experts who know how your data is stored and who use Jaspersoft tools to create reports and
metadata that are exposed through the embedded features. Data analysts often require administrative access to deploy the
reports they create, and often one person fills both roles.

Depending on the size and structure of your organization, the same person may take on two or three of these personas. Yet,
your solution must still distinguish between them in order to meet the requirements for each persona.

1.6.2

Report Designer

At every level, an unspoken part of the solution is the report designer tool such as iReport or Jaspersoft Studio. The data
analyst must prepare reports and upload them to the right place (and with the proper permissions) so that they are available
through the embedded features. In certain cases, the data analyst can use the interactive Ad Hoc editor in JasperReports Server
to design the reports, but this is not always possible for complex reports.
Your solution should identify the tools and processes by which you can create folders, reports, Topics, and Ad Hoc views, and
how to set permissions to make them available to end users.

1.6.3

Administrator Functions

In addition to creating and uploading reports, the following data analyst and administrator functionality must be considered as
part of any solution:

Creating data sources and Domains.


Managing the folders and permissions in the repository.
Managing users, roles, and organizations.
11

Jaspersoft Embedding Guide


For web services and iframes solutions, you have the option of embedding the administrator functions into your application.
With web services, this requires extra effort and increases the scope of your application, so in most cases, it is avoided.
Instead, administrators can perform these actions through the JasperReport Servers own interface. With iframes, it requires
extra effort to suppress the administrator functionality, and as long as each user has a separate account, the administrator
menus are displayed only to administrator users.

1.6.4

Performance

At all levels except level 1, your application gains all the performance advantages of the dedicated reporting server. The
reports being run and scheduled are independent of any load on your own application, and you can size the JasperReports
server instance with the CPU and memory you need for your expected reporting load. In addition, the server has optimizations
and caching that you can configure for optimal performance.
When you embed the BI functionality, make sure your application is using the server efficiently to pass on that performance to
the user. For example, you should use the latest web service APIs (currently REST version 2), or in the case of iframes, make
sure your users have adequate bandwidth to the server itself.

1.6.5

Mobile Deployment

All three embedding technologies are compatible with some form of mobile deployment:

JasperReports Library is compatible with the Android API.


The Jaspersoft Mobile SDKs for iOS and Android use web services.
An iframe can run in any mobile browser that supports most web standards.

Typically, you will want to develop a mobile version of your own application, in which case you should rely on the Jaspersoft
Mobile SDKs for iOS and Android. Because these SDKs rely on web services, mobile applications that use them are
essentially using level 2 of embedded BI. However, if you have a web-based client application, most modern mobile browsers
can render iframes correctly and thus support higher levels of embedded BI. In both cases, you only need one JasperReports
Server to respond to all your clients, whether standard clients or mobile, web services or iframes.

12

Level 1: Using the JasperReports Library

CHAPTER 2

LEVEL 1: USING THE JASPERREPORTS LIBRARY

The first level of embedding is called static reporting, so-called because the choice of reports in the application is static. At this
level, your application provides reports directly to the users of your application. For example, users click a button or select a
menu to run the corresponding report. The report is run with the latest data and displayed to the user. Also, from the developer
and administrator point-of-view, modifying or adding reports involves reprogramming the application and redeploying it.
The Jaspersoft embedded BI solution for level 1 is implemented straightforwardly with the APIs of the JasperReports Library.
Using this library, applications can programmatically define a data source, use it to fill and display a report, and then export
the report in any number of formats. Reports are designed separately using the iReport or Jaspersoft Studio tools, then
exported in JRXML to be bundled with the application.
This chapter contains the following sections:

Business Example
Solution Using JasperReports Library
Implementing Level 1 Embedding
Alternative Solutions

2.1

Business Example

Bucks Electronics has implemented an Inventory Management System, named IMS2. This application written in Java runs as
a web application from a server at the companys headquarters, so that employees at each store have access to IMS2 through
their web browser. Kelly is the application administrator, responsible for maintaining and expanding the applications
capabilities.
Joel is an inventory clerk at Bucks Electronics retail store in Phoenix. Using the built-in functionality of IMS2, Joel can
obtain an inventory list for each of the products in his department. Joel has noticed patterns in the sales of batteries, and wants
to optimize his supply for the coming months. Joel wants to know how many batteries his distributors provided last month and
how many are planned for the rest of the year, presented in a table and bar chart. He wants to run the report against the latest,
most up-to-the-minute data.

2.2

Solution Using JasperReports Library

To meet this need, Kelly plans to embed JasperReports Library in the IMS2 application and implement the report as a menu
option. The new report should be displayed in a pop-up window, which also has a button to download the same report in PDF
format. The following figure shows the design mock-up that Kelly made for Joels request.

13

Jaspersoft Embedding Guide

Figure 2-1

Custom Report Window Added to the IMS2 Application in Level 1 Example

The following scenario shows how Joel interacts with the updated IMS2 application:
1.

Log in as usual.

2.

Select new menu option. The report with table and bar charts displays in a pop-up window.

3.

Click Export PDF to download and print it from the PDF viewer if needed.

This solution puts the custom reports right inside the IMS2 application where users can access them easily. This is the goal of
embedding Jaspersoft BI.

14

Level 1: Using the JasperReports Library

2.3

Implementing Level 1 Embedding

Here is the general procedure that Kelly follows to implement level 1 reporting in IMS2:
Step

Action

Description

1.

Create the report in iReport (NetBeans) or


Jaspersoft Studio (Eclipse).

Using iReport or the Jaspersoft Studio, Kelly creates the


report layout and specifies the data source, query, and fields
needed. When the report is complete, she saves the JRXML
file that defines the report.

2.

Add user interface components:

The code for the user interface is different for every


application. However, it is often straightforward to find menu
definitions and add new sub-menus and menu items to
invoke the window with the new report.

New menu option


Pop-up window for the new report
Button listeners for export operations

3.

Add code to run the report and display the


output.

For examples of code using JasperReports Library, see the


code samples in the software and on the community
website: http://community.jaspersoft.com/wiki/jasperreportslibrary-samples

4.

Add code to export the PDF and deliver it


through the application.

5.

Bundle JasperReports Library and the


JRXML file for the report in the IMS2
deployment.

Update the product build to include the JasperReports JARs


and the JRXML file. Alternatively, the report file could be
located in a local folder, and only the file location is compiled
into the code.

6.

Build and redeploy the IMS2 application.

When users access the application, they see the new menu
and are able to run and print the report.

Some design considerations:

Kelly anticipates that other employees will need custom reports, so she makes her code modular.
In the future, she can add reports simply by updating the IMS2 menus and re-using the same functions to run the report
and export other formats.
However, adding reports does require the IMS2 application to be restarted, which needs to be done off-hours to avoid
disrupting users.

2.4

Alternative Solutions

The following row from Table 1-1 on page 9 shows the different technologies that can implement a level 1 solution:
Level
1 - Static
reports

JasperReports API

Web Services

iframes & Themes

Flexible solution for quickly


adding reporting to Java
applications.

Requires a server instance,


but can be used in non-Java
environments.

Requires a server instance,


but can be used in web
applications.

Even though this chapter features one solution using the JasperReports API, there are many possible solutions, with both the
JasperReports API and web services technologies.

2.4.1

Using JasperReports Libraries

Given that JasperReports Library can be bundled with any Java application, the possible usage scenarios are endless. In the
IMS2 solution, the library adds reporting capabilities to an already deployed web application. However, there are many other
typical use cases:

Stand-alone Java application with a user interface to display reports.

15

Jaspersoft Embedding Guide

Headless or command-line report generator that can be used in batch files or scripts.
Production reporting where the application generates hundreds or thousands of reports and distributes them by email or by
printing them.
Elaborate reports, sub-reports, and dashboard-like reports.
Control of the report output to implement interactive reports.
Export to other formats and incorporate that in your workflow. For example, offer an option to open the report in Excel.

2.4.2

Using Web Services

Web services are the technology used to offer the higher functionality of Level 2 embedding, but web services can also be used
to implement simpler Level 1 functionality.
If your application is not written in Java, you cannot use the JasperReports Library directly. To access reports, you would need
to deploy a JasperReports Server and interact with it programmatically by calling the web services API from your application.
Web service APIs are HTTP-based and can be implemented in any language, and many languages have built-in or add-on
support for the REST and SOAP web services.
In this case, the implementation workflow is somewhat more complicated. You must install a JasperReports Server in a Javabased application server such as Apache Tomcat and configure it with your reports. Then your application can request a report
in any format using the web services. The web services expose many features of the server, but you only need to implement
the ones that you want to appear in your application.
In addition to creating the JRXML of the report, you must upload it to the server. Then your code will run the report by
sending a web services request to the server and receiving the HTML or PDF output. However the user workflow is
unchanged. Joel will still use the new menu option to display his report.
Another reason you might implement a simple reporting solution using web services is to plan for the expansion of your BI
needs. As described in Chapter 3, Level 2: Embedding Through Web Services, on page 17, the JasperReports server that
you deploy provides a lot of functionality that, when youre ready to you can later access through the Web Services.

2.4.3

Limitations to iframes for Level 1

The iframes technology rely on displaying content that is actually running on the JasperReports Server. Because the server is a
full-featured product, it provides more functionality than that required by level 1 embedding. Indeed, the server exposes many
features such as a report repository, user permissions, and scheduling that you may not want to expose in your host application.
It is possible to customize the features and how they are displayed by iframes, but this is complex and error-prone.
If you do not need to embed the advanced features, Jaspersoft recommends using only the JasperReports API or web services
to implement level 1. If you plan on embedding advanced features in the future, you may want to implement a level-2 or level3 solution from the start. It will take slightly longer to implement than a JasperReport API solution, but it scales better and
saves you the time needed to change technologies later.

16

Level 2: Embedding Through Web Services

CHAPTER 3

LEVEL 2: EMBEDDING THROUGH WEB SERVICES

The second level of embedding is called managed interactive reports. In this use, interactive refers to how users can select
reports from a dynamic list, as opposed to the static choices in level 1. Level 2 introduces the use of JasperReports Server to
manage and run reports. In fact, all higher levels of embedding rely on the server, but the choice of technologies and features
differ between the levels.
JasperReports Server provides a complete set of features to manage reports, so you dont have to implement them yourself. It
has a repository to store and organize reports, and it implements security through authentication, permissions, and role-based
access. It also provides structures to define input controls and a scheduler to run and email reports at set times. And it uses the
JasperReports Library internally to run reports and export them to different formats.
The Jaspersoft embedded BI solution for level 2 relies on web service APIs to access reports on the server. The end-user
application has its own user interface, but when it wants to list or run a report, it makes calls to the server.
Web services are a set of APIs that allow the calling application to make requests for information that is processed or stored on
the server. Web services use the HTTP protocol to exchange XML and JSON objects over the internet. For example, the
calling application can request a URL that represents a search of the repository, and the server responds with XML objects for
each report that matched the search. JasperReports Server implements both REST and SOAP web services, but this document
focuses only on the more modern REST services.
This chapter contains the following sections:

Business Example
Solution Using Web Services
Implementing Level 2 Embedding
Alternative Solutions

3.1

Business Example

As Bucks Electronics expands into new regions, there are more and more store managers and employees requesting more and
more reports. Kelly is still responsible for maintaining and extending the IMS2 inventory management system, and up until
now, she has been adding reports to the custom menu shown in Figure 2-1 on page 14. But Kelly receives requests for more
advanced functionality:

Paul, the manager of the Santa Fe store, has requested an inventory aging field for his stores reports. However, inventory
clerks dont need this information and prefer the original report without the extra field.
Janet is a manager for the western regional stores for Bucks Electronics. She wants to know how many total shipments
were delivered last month per distributor, how many items are in stock, and how many will be shipped next month for
each store. She then wants each report to run on a nightly basis and be sent via email to each store manager.

17

Jaspersoft Embedding Guide

3.2

Solution Using Web Services

Kelly realizes it is time for a major update to the IMS2 application. Implementing all the required features using the
JasperReports Library is possible, but as a one-person team, she doesnt have the time to do it by herself. Instead, she plans to
install an instance of JasperReports Server on her network and rely on it to provide the features she needs.
To interact with the server, Kelly modifies the IMS2 application to make web service calls to the server and display the results
in the IMS2 application. For example, when Paul logs into IMS2, the web service call also logs him into JasperReports Server,
where he is assigned the ROLE_STOREMANAGER. Then, when another web service call obtains the list of reports, this role
grants him access to the reports that include the inventory aging field. IMS2 now uses web service calls to run the report and
also offer PDF export options. As an end-user, Paul never sees the JasperReports Server interface, only the information
returned from the web service calls in the IMS2 user interface.

Figure 3-1

Dynamic Report List Added to the IMS2 Application in Level 2 Example

A major advantage of this architecture for Kelly is that JasperReports Server provides a full-featured user interface for the
administrator. Now, she can manage the reports independently of the running IMS2 application, and she can set all the roles,
permissions, and schedules she needs in real-time through the servers UI. To satisfy Janets request, Kelly creates and uploads
the report to JasperReports Server, then sets the schedule as requested. The following figure shows how Kelly would set the
email output of the report in the JasperReports Server scheduler interface.

18

Level 2: Embedding Through Web Services

Figure 3-2

Scheduling Feature in JasperReports Server in Level 2 Example

This architecture with IMS2 accessing the server through web services is very flexible. Kelly can continue to add folders,
reports, permissions, and schedules to the server while the IMS2 application is in production and accessing the server.

3.3

Implementing Level 2 Embedding

Here is the general procedure that Kelly follows to implement and deploy level 2 managed reports in IMS2:
Step

Action

Description

1.

Install and configure a stand-alone


instance of JasperReports Server.

See section 3.3.1, Installing and Configuring


JasperReports Server, on page 20.

2.

On the server, create users and roles,


then create folders and permissions in the
repository with role-based permissions.

See section 3.3.2, Creating Users, Roles, and Folders,


on page 21

19

Jaspersoft Embedding Guide


Step

Action

Description

3.

Create reports in iReport (NetBeans) or


Jaspersoft Studio (Eclipse) and upload
them to the server.

The report designers let you upload files directly to the


server, where they are available immediately. For details,
see section 3.3.3, Loading Reports Into the Server, on
page 22.

4.

Schedule the reports as requested by


users.

To complete the server setup, Kelly schedules the user


reports by setting the recurrence and email output through
administrator pages on the server. See Figure 3-2 on
page 19.

5.

Add user interface components to the


IMS2 application:

The code for the user interface is different for every


application. When using web services for embedding, the
code for the user interface is often making the web service
calls directly, overlapping with the next step.

New menu option


New custom report listing page
Pop-up window
Button listeners

6.

Add code to make web services call to the


server and process the response:

For documentation, see the JasperReports Server Web


Services Guide.

List reports based on role permissions


Run a chosen report
Export PDF from a chosen report

7.

If you use any web service toolkits, such


as Apache Axis, bundle them with in your
build process.

Update the product build to include the necessary JARs.


Alternatively, the report file could be located in a local folder,
and only the file location is compiled into the code.

8.

Build and redeploy the IMS2 application.

When users access the application, they interact with the


JasperReports Server transparently through the IMS2
application.

There are 2 distinct phases to this project:

Steps 1-4: Configuring and managing reports on JasperReports Server.


Steps 5-8: Implementing web service calls in the IMS2 application.

In an actual deployment, the 2 phases often progress in parallel. You must set up the server first to test your web services calls,
but you can iterate with test reports and finalize the user reports after the code is working. One of the strengths of level 2
embedding with web services is that the application is very independent of the running server.

3.3.1

Installing and Configuring JasperReports Server

At the heart of level 2 and all higher levels is an instance of JasperReports Server hosting the reports, providing security, and
responding to web service requests. There are two fundamental ways to install the server:

In the traditional stand-alone installation, you provision a computer through your IT department and run the installer to
deploy the server.
New cloud-based virtual servers are available through Amazon Web Services (AWS), and you can choose a machine
image that deploys the latest JasperReports Server release.

There are also other solutions such as installing the server on a virtual machine hosted by your IT services, or even
downloading the source code, customizing, and building the server binaries yourself. When deciding how and where to deploy
JasperReports Server, keep in mind the following constraints:

20

Where you store your data and how you secure it If your data is already in the cloud, it makes sense to deploy the server
in the cloud as well. If your data is sensitive and should never leave your corporate firewall, you need a dedicated local
computers on which to deploy the server.

Level 2: Embedding Through Web Services

Other technologies you can leverage, such as application servers and portals If your IT department already maintains an
app server for internal tools, you may be required to use it for all internal software. This can also simplify access to your
data, if the existing app server already makes the data sources available.
How many resources you have to deploy and maintain physical or virtual servers in your own IT department Hosting
your own server instance has many advantages, but it also has maintenance costs for both hardware and software. The
Amazon Machine Images (AMI) are designed for immediate deployment and ease of upgrade.
Whether your company is already using or migrating to Amazon Web Services It is possible to create secure private
networks within AWS, and your IT department might already be using Amazon servers. If your data is already located in
one of Amazons storage services, Jaspersoft recommends deploying JasperReports Server through AWS as well.

Another aspect of the deployment is to estimate your user load and dimension your server installation accordingly. You also
want to keep in mind future expansion and make sure the size and performance of your server can meet expected growth in
numbers of users or amounts of data.
Finally, Jaspersoft releases several different editions of JasperReports Server, from a free and open source Community Edition
with limited features to Professional and Enterprise Editions with advanced features. The level 2 example presented in this
chapter can be deployed on the Community Edition, but the upgrades in levels 3, 4, and 5 require the Professional and
Enterprise editions. Jaspersoft releases evaluation versions of the commercial editions, so you can download and test the
advanced features for a limited time. Future licenses may also be based on usage limits such as number of users and number of
reports, so contact a Jaspersoft representative when planning your deployment.
Anticipating the future needs of Bucks Electronics, Kelly purchases the license for the Enterprise edition. Working with her
IT department, she obtains a computer in the server room near the IMS2 host and connects it to the internal network. She
already has the evaluation server running on her laptop that she will use as a test platform. Kelly installs the production
instance of JasperReports Server on the dedicated computer by following the instructions in the JasperReports Server
Installation Guide.
Once the server is running, she sets herself as the administrative user and configures the server for her particular environment
and intended load using the information in the JasperReports Server Administrator Guide.

3.3.2

Creating Users, Roles, and Folders

In order for the IMS2 application to interact with the JasperReports Server, the administrator must create the following items
on the server:

Repository folder hierarchy A structure for organizing and maintaining all reports, helper files, and associated resources.
User accounts Unique usernames and encrypted passwords for secure access.
Roles Groups of users that can be assigned permissions.
Permissions Determine which users and roles can view or modify a report or resource in the repository.

The repository is the internal storage for reports and resources in JasperReports Server. It is designed like a file system with
folders that may contain reports, resources, and other folders. Common resources such as a data source or an image can be
placed in common folders and then referenced by reports in other folders. As the administrator, Kelly creates the folder
structure to organize the reports that she has created for her users.
The need for user accounts, roles, and permissions in JasperReports Server depends on the data policy you want to enforce on
the reports stored on the server. The data policy determines which of your native application users are allowed access to the
various reports through web services. In the simplest case, all users have equal access to all reports. This is simple because it
requires a single user account on the JasperReports Server, and all web service calls can use this account. Also, because all
web services requests are from the same user, no roles are necessary. Every user of your application can access every report on
JasperReports Server.
In the case of IMS2, the data policy dictates that different users have access to different reports, and some user should not have
access to certain reports. To implement this policy, the IMS2 application must have user accounts and pass those credentials to
JasperReports Server where the same user accounts are configured. As part of the preparation of the server, Kelly must create
user accounts for her users, so that each web service call can be sent on behalf of the IMS2 user that requested it. Creating
users can be performed manually on JasperReports Server, or the server can be configured to support single sign-on through
external authentication such as an LDAP directory. For more information see the JasperReports Sever Authentication
Cookbook.

21

Jaspersoft Embedding Guide


Depending on the number of users and complexity of your data policy, roles can be defined on JasperReports server to assign
users to common groups. In our example, Paul is a store manager, and each store manager should have access to a set of
reports that other store employees cant see. Similarly, Janet the regional manager has access to reports that others dont. Kelly
creates a role for all store managers and another role for regional managers.
In order to restrict access to reports, Kelly defines permissions on certain folders using these new roles. JasperReports Server
supports a full range of permissions from execute only to read/write/delete. Permissions can be used in different ways to
support different kinds of deployments. In the case of an embedded solution using web services, the logic of the embedding
application also restricts the users access to reports. In Kellys implementation for level 2, she uses web service calls to search
for reports that a user can access, and then run those reports. In both cases, users should have read-only permission for the
reports they see and run, and no access permission for those they dont. Therefore, Kelly grants read-only access to the
manager roles on the folders that contain their respective reports.

3.3.3

Loading Reports Into the Server

Using iReport or the Jaspersoft Studio, Kelly creates the new reports needed by Paul and Janet. In order to run these reports in
JasperReports Server, she needs to do the following:

Define data sources on the server.


Upload reports to their designated folder on the server.
Upload any helper files such as images or input controls.

The most important part of setting up the server environment is to create data sources on the server for data that IMS2 reports
must access. A data source is a resource in JasperReports Server that identifies a database and the parameters to access its data.
You can have multiple data sources, for example to connect to test databases and production databases, or to have reports
based on different sources of information. Data sources should be stored in a folder that only has administrator permissions.
Once the data sources are created on the server, Kelly can use iReport to upload reports and test them on the server. The
JasperReports Server plug-in to iReport creates the report and associates it with its data source. The plug-in also helps her to
upload any images or input controls to the server, either as components of the report or as independent reusable resources.
Using the JasperReports Server plug-in, Kelly can develop, test, and upload report directly from iReport. But she can also log
into the server as administrator and use the report wizard to upload the JRXML and other report components manually.
When the reports and their components are uploaded into the folders in the servers repository, they inherit the permissions on
those folders. Kelly could also assign permissions on each report, but it is easier to rely on the folder permissions and have
them applied uniformly to all reports in a given folder.
Finally, once the reports are uploaded and tested, Kelly can start to define the schedules to run the reports and send them by
email. Because the scheduling is configured and carried out entirely on JasperReports Server, reports can be scheduled and
emailed as soon as they are uploaded, regardless of whether the IMS2 application has been updated to use web services yet.

3.4

Alternative Solutions

The following row from Table 1-1 on page 9 shows the different technologies that can implement a level 2 solution, and the
subsequent sections describe the trade-offs in using other technologies:
Level
2 - Managed
reports

3.4.1

JasperReports API

Web Services

iframes & Themes

Difficult to re-implement
report options, report scheduler,
and repository functionality

Best solution, very flexible;


works on any platform including
mobile SDKs

Solution is possible, but UI


must be customized to limit
navigation

Using Web Services

The example in this chapter is just one solution that uses web services to embed BI functionality into IMS2. Web services
provide many different ways of interacting with the server, and thus many extensions of the given solution are possible:

22

Level 2: Embedding Through Web Services

Keyword search through web services would allow users to find specific reports being stored on the server, instead of
scrolling through a long list.
The IMS2 application could implement a mechanism of favorite reports for each user, which it then resolves through
web services.
Scheduling could be performed through web services, thus allowing users to schedule reports themselves.
Other administrative functions such as uploading reports could be implemented through web services from the IMS2
application.
Web services are also available through Jaspersofts Android and iOS SDKs, meaning that you can develop mobile
versions of your application with the same features.

3.4.2

Using JasperReports API

JasperReports Server is itself a web application based on the JasperReports library. It implements all of the features of level 2,
and many more. This proves it is possible to implement these features natively in IMS2, but this overlooks the complexity of
doing so. To implement level 2 in IMS2 without relying on a server, Kelly would need to program or integrate the following
components:

The repository: a storage for reports and a mechanism to upload reports.


Permissions: a way to restrict access to reports based on the user and his roles.
A scheduler: a mechanism to run reports with recurrence and calendar schedules, including sending the output by email.

While there can be certain advantages to implementing one or more of these features natively in IMS2, there are also
disadvantages such as performance, scalability, security, and maintenance. The main drawback to implementing features
directly in IMS2 is that further upgrades and advanced features require further customizations and maintenance. By opting for
the JasperReports Server instead, you gain all the features and future improvements of the server.

3.4.3

Using iframes

If you eventually want to implement levels 3,4, or 5 that require the use of iframes, you can start by implementing level 2 using
iframes as well. Unlike web services, a solution using iframes has very little modification on the client, only a page to display
the iframe and the interface to access it. The difficulty of using iframes in level 2 is that the server exposes a lot of
functionality, more than just the managed reports of this level. There are two options to deal with the extra functionality:

Use themes and customizations of the user interface to restrict what users can access through the iframe. This technique is
further described in Level 3: Report and Dashboard Viewers in iframes on page 25.
Skip to level 3 functionality. Instead of spending effort to restrict access to functionality, leverage the functionality to
implement a level 3 solution.

For more information about planning deployments and choosing between web services and iframes, see section 1.4.3,
Transitioning from Web Services to iframes, on page 10.

23

Jaspersoft Embedding Guide

24

Level 3: Report and Dashboard Viewers in iframes

CHAPTER 4

LEVEL 3: REPORT AND DASHBOARD VIEWERS IN IFRAMES

The third level of embedding is characterized by highly interactive reports and dashboards. At this level, the embedding
application displays truly interactive reports where users can sort and filter data, change input controls, and even click on
values to drill-down. Dashboards display multiple reports linked together by common input controls, and are equally
interactive. Implementing these complex features natively in any application would be difficult, so this level again leverages
the functionality of JasperReports Server.
The Jaspersoft embedded BI solution for level 3 is to use iframes to display reports and dashboards that are being served
directly from JasperReports Server. JasperReports Server has a web interface that creates interactive reports and dashboards in
web pages in the users browser. In level 3, the host application uses iframes to display the servers pages inside of its own
user interface. The embedding application only provides the placeholder for the iframe, and then users interact directly with
JasperReports Server within that iframe.
An iframe is an HTML element that creates an inline frame for external content. Therefore, this solution applies to a wide
range of applications that are themselves web applications accessed through a browser or to applications that can display
HTML in their user interface. In either case, JasperReports Server provides mechanism to customize the look and feel of its
content so that the contents of the iframe blend seamlessly with the appearance of the host application.
This chapter contains the following sections:

Business Example
Solution Using iframes
Implementing Level 3 Embedding
Alternative Solutions

4.1

Business Example

Thanks to embedded BI, more and more employees of Bucks Electronics have access to useful data within the IMS2
application. Steve is the head of inventory operations for all of the chains electronic retail stores, and he wants to leverage this
data for his needs. He would like to see up-to-the minute metrics for key inventory and point of sale performance indicators.
Instead of looking at dozens of individual reports, he wants the summary data presented in a single easy-to-read dashboard.
In addition, Steve wants his reports to be interactive and provide drill down to detailed data, filters, and easy to see flags
associated with metric outliers. These metrics are combined from the IMS2 inventory system and another Point of Sale
application to provide a central business performance dashboard.

25

Jaspersoft Embedding Guide

4.2

Solution Using iframes

Kelly realizes once again that the current solution isnt going to be adequate for this new level of engagement. Solutions using
web services are very powerful and very flexible, but they do not yet support the interactive features of the server, such as
dashboards and Ad Hoc reports.
Kelly could create her own dashboard functionality and use web service calls to fill it, but the Professional Edition of
JasperReports Server that she installed for level 2 has dashboards built in. Even if she didnt already have a server, installing
and configuring the server is much simpler than re-implementing dashboards using web service calls.
To display the dashboards that appear on the server, Kelly modifies the IMS2 application to use iframes. An iframe displays
content from another URL and allows the user to interact with the content as if it were part of the original page. An application
starting at level 3 could use an iframe to show the servers repository page, search results, or the user-specific library page. The
user would then launch reports and dashboards in the same iframe.
In the case of IMS2, Kelly has already implemented the report listing using web services (see section 3.2, Solution Using
Web Services, on page 18), so she plans a hybrid solution that uses iframes for dashboards. First, she duplicates the web
services code to create a page that lists dashboards. But instead of running a report through web services, this page opens a
new window containing the iframe with the dashboard.

Figure 4-1

Dashboard Embedded into the IMS2 Application in Level 3 Example

The dashboard is rendered by JasperReports Server in the iframe. Dashboards contain multiple reports, each of which can have
data from a different source. The user can interact with the dashboard in several ways:

26

The dashboard can have input controls such as the start month and end month in the figure above. These controls can
provide input to multiple reports, all of which are refreshed when clicking the Submit button.

Level 3: Report and Dashboard Viewers in iframes

Charts may have interactive features such as mouse-over information, dynamic ranges, or selectable chart type.
As shown in the figure above, Kelly has also designed the reports in the dashboard to implement the drill-down feature
that Steve requested. The following figure shows how the iframe has refreshed with a detailed report after clicking the
name of a month (May) in the dashboard.

Figure 4-2

Drill-down Report from a Dashboard Embedded in the IMS2 Application

Because iframes display the user interface (UI) directly from the server, Kelly must also customize the appearance of the
server UI to match the IMS2 application. JasperReports Server provides two different approaches to customizing the UI:

In Kellys chosen solution, she only needs the content of the dashboard so she appends viewAsDashboardFrame=true to
the URL of the dashboard within the server. Also, the URL that she configures for the drill-down report use the same
parameter. As shown in the figures above, the dashboard and report display without any menus or server navigation links.
Users can interact with the dashboard, but cannot access the rest of the server.
In pure iframe solutions, you may want to expose the servers repository, search, and library pages, including any menus
or navigation links. In this case, you would use UI customizations and themes to limit what appears to users.
Customizations determine what menus appear for the given roles of a user, and themes determine whether logo, frames,
and various panels appear. Themes also control the colors, fonts, and sizes of UI features, allowing you to make the server
contents in the iframe blend seamlessly with the UI of your application.

27

Jaspersoft Embedding Guide

4.3

Implementing Level 3 Embedding

Here is the general procedure that Kelly follows to implement and deploy level 3 interactive dashboards in IMS2. The first two
steps are identical in levels 2, 4, and 5. These two steps are common to all levels that rely on a JasperReports Server instance.
Step

Action

Description

1.

Install and configure a stand-alone


instance of JasperReports Server.

Same as described in Level 2, section 3.3.1, Installing and


Configuring JasperReports Server, on page 20.

2.

On the server, create users and roles,


then create folders and permissions in the
repository with role-based permissions.

Same as described in Level 2, section 3.3.2, Creating


Users, Roles, and Folders, on page 21

3.

Create reports in iReport (NetBeans) or


Jaspersoft Studio (Eclipse). Alternatively,
create Ad Hoc reports based on Topics or
Domains in the server.

Dashboards are composed of individual reports that are


already stored on the server. Kelly creates the dashboard
elements in a report designer and uploads them to the
server as described in section 3.3.3, Loading Reports Into
the Server, on page 22.

4.

Create the dashboard on the server using


any number of reports. These reports can
each have a different data source.

As a sever administrator, Kelly uses the Dashboard


Designer to arrange reports and link them together with input
control. For more information, see section 4.3.1, Creating
a Dashboard, on page 28.

5.

Create a UI theme on the server to hide


buttons and make the dashboard match
your applications user interface.

Kelly designs her reports and dashboard lists so that all


URLs use the parameter to suppress navigation. If she
needed the server navigation in the iframe, she could
customize it with themes. For details, see section 4.3.2,
Customizing the User Interface, on page 29.

6.

Add user interface components to the


IMS2 application:

The code for the user interface is different for every


application. One advantage of using iframes is that they are
very simple to implement because they consist of a single
HTML element (the iframe) and the URL to the server.

New menu option


New window with iframe to display the

dashboard
7.

Build and redeploy the IMS2 application.


JasperReports Server does not need to be
redeployed unless the UI configuration
files have been modified.

When users access the application, they interact with


dashboards seamlessly in an iframe.

The following sections describe the steps that are specific to level 3 embedding.

4.3.1

Creating a Dashboard

JasperReports Server provides the dashboard designer to lay out and control several reports on a single page. Each report runs
independently, so each can have its own data source. Each report can also have input controls, but if they accept the same
parameter, a single input can be used for all reports. The result is a dashboard that combines data from several sources in a
data-rich display.
You can add any report to a dashboard, but usually, you want to design reports that fit neatly on the page along with other
tables and charts you want to display. In Kellys use of embedded dashboards, she also designs the reports so that the drilldown links available in each report work within the iframe.
The reports for the dashboard are uploaded to the server in the same way as all other reports, either from iReport or Jaspersoft
Studio, or through the servers report wizard. A good practice is to make separate folders in the repository for each
dashboards reports and any common elements.

28

Level 3: Report and Dashboard Viewers in iframes


As an administrator on JasperReports Server, Kelly opens the dashboard designer and uses drag-and-drop to place reports on
the canvas, resize them, and align them:

Figure 4-3

Dashboard Designer in JasperReports Server

The left-hand column of the dashboard designer lists the reports and input controls that are available to create the dashboard.
The input controls create dropdowns for the user to enter values. Other content can also be added to dashboards:

Buttons for submitting input controls, resetting their values, or printing.


Labels and text.
Web content from a given URL.

Once the dashboard is created, it is saved in the repository and available to be displayed through an iframe.

4.3.2

Customizing the User Interface

By default, the iframe displays the full JasperReports Server user interface, but this is usually not desirable because it includes
menus, features, and actions that your application users should not see or have access to. The server provides three ways to
control the appearance of the UI:

Frame Options Whether or not to display the navigation frame around the dashboard content.
Themes The font, color, and size of UI elements controlled through cascading style sheets (CSS).
UI Customizations Role-based access to menus and context-menu items.

4.3.2.1

Frame Options

The simplest way to display dashboards and drill-down reports in an iframe is to link directly to the URL of the dashboard or
report and include one of the following two parameters at the end of the URL:

viewAsDashboardFrame=true For dashboards and reports, this parameter removes all server navigation and frames

around the content. This is best for dashboards and reports without input controls, as shown in Figure 4-1 on page 26 and
Figure 4-2 on page 27, respectively.
decorate=no For reports with input controls and repository pages, including search and library pages, this parameter
removes the server navigation around the content. This allows users to interact with the report or the page, but not have
access to other pages or features of the server.

29

Jaspersoft Embedding Guide


For example, the URL for the dashboard in Figure 4-1 on page 26 would be:
http://localhost:8080/jasperserver-pro/flow.html?_flowId=dashboardRuntimeFlow&
dashboardResource=%2FDashboards%2FStorePerfDash&viewAsDashboardFrame=true

If you expose the repository, search, or library pages, you may still need UI customizations to restrict access to context-menu
actions such as scheduling a report.
4.3.2.2

Themes

A theme is a set of cascading style sheet (CSS) files and images that JasperReports Server uses to render the user interface.
Together, these files define colors, sizes and spacing, fonts, and many other aspects of the UI. Themes are stored in the
repository, and administrators can create new themes and activate them to change the UI. One advantage to themes is that they
can be modified anytime and take effect immediately without restarting the server.
The following figure shows the CSS files of the default theme and the appearance of the sample jasper_dark theme.

Figure 4-4

Themes in JasperReports Server

Using themes, you can modify the contents of the iframe so that it matches the color and style of the embedding application.
You can easily change or remove the Jaspersoft logo and hide unnecessary navigation such as the logout link.
For example, the following code example is the beginning of the overrides_custom.css file that defines the jasper_dark theme.
This theme mostly changes the color of user interface, so it is a good one to copy if that is your goal.
/* BUTTONS */
#globalSearch .button.search {
border-left: 2px solid #000b2c;
}
.action.jumbo.up.pressed {
background: none repeat scroll 0 0 #FFFFFF;
border: 1px solid #bf5b08;
}

30

Level 3: Report and Dashboard Viewers in iframes


/* CONTAINERS */
.banner {
border-top:1px solid #000b2c;
border-bottom: 1px solid #000b2c;
}
column.decorated {
border:1px solid #000b2c;
}
#frameFooter {
background: url("images/footer_bkgd.png") repeat-x scroll 0 0 #024666;
border-top: 1px solid #000b2c
}
body {
background: none repeat scroll 0 0 #035b85;
}
.panel.tooltip .message.label {
color: #035B85;
margin-bottom: 0;
}
...

For documentation about managing themes in the repository, see the JasperReports Server Administrator Guide. For more
examples of writing and modifying themes, see the JasperReports Server Ultimate Guide.
4.3.2.3

UI Customizations

In some embedding scenarios, you may want to allow users some navigation in the repository pages, for example to use
folders to store many reports or to allow searching. To display the menus and search field for this, you cannot use frame
controls. But you must also restrict access to other features, such as creating an Ad Hoc report, and themes are not sufficient to
do this. In order to display the menus but restrict access to certain features, you must customize the user interface.
Customization involves modifying the following types of files that define the user interface:

Java Server Pages (JSP)


JavaScript files
XML configuration files

For example, these files have role-based mechanisms to determine which users can see the various menus and context-menus.
By changing these roles, you can remove the corresponding menu items for non-administrator users.
The downside to such deep customization of the UI is that any changes require you to restart JasperReports Server in order to
take effect.
For more information, see the chapter on UI customization in the JasperReports Server Ultimate Guide.

4.3.3

Logging Into JasperReports Server

Before displaying any page, JasperReports Server requires its users to log on with a username and password. There are several
ways to enter the password before displaying a dashboard:

In Kellys solution, the hybrid architecture using web services can be used to log in before displaying the dashboard.
Because she is using web services to display lists of dashboards, she must send the user name and password as one of the

31

Jaspersoft Embedding Guide


first web service calls. Even in a solution that does not otherwise use web services, the API for logging in is simple and
one of the most secure ways to authenticate users.
The username and password can be included in the URL that is set for the iframe. This is the most transparent to users
because they do not need to enter them. This disadvantage of this method is that it makes the credentials visible on the
network. It is possible to encrypt the password, but even that does not provide complete security. As a result, this method
should be used only for low security applications behind a firewall.
The most secure method is to allow users to log in themselves. If your application does not use web services or the URL
to send the username and password, the server displays a login screen in the iframe. After the user enters the correct
credentials, the iframe redirects automatically to the requested dashboard.
Another way to authenticate users is to have an external authentication mechanism such as LDAP to verify the password.
JasperReports Server supports several options for external authentication, including the ability to configure single sign-on
(SSO). For more information, see the JasperReports Server Authentication Cookbook.

4.3.4

Security

With iframes, the full user interface of JasperReports Server is being displayed in your application, the same as if your users
logged into the server, except for the elements of the UI that you remove with frame controls, themes, and customizations. The
fact that users have access to the server means that you should take the time to configure the security mechanisms to keep your
data secure:

Do not use a single username, especially not an administrator username, for all your users. Configure the user accounts on
JasperReports Server and use them when accessing the server from your application.
If you have lots of users and they have different levels of access to data, define roles to represent the various groups that
have equal access.
Define sensible permissions for users and roles on your reports and dashboards in the repository. Make most of your
reports read-only so they are not accidentally deleted. Make sure that data sources and Domains have execute-only
permissions so that only administrators have access to them.
Do not use display:none in the CSS files of a theme to hide buttons or functionality. Any browser with the proper tools
can bypass the CSS and access the functionality. Instead, customize the UI and change the roles for role-based menus.

4.4

Alternative Solutions

The following row from Table 1-1 on page 9 shows the different technologies that can implement a level 3 solution:
Level
3 - Interactive
reports and
dashboards

4.4.1

JasperReports API

Web Services

iframes & Themes

Very difficult to re-implement


interactive reports and
dashboards.

Not possible, use JR API or


iframes.

Best solution; use themes to


control appearance

JasperReports API

A dashboard can be seen as a composite report, consisting of any number of subreports in a full-page layout. You can
implement complex reports with subreports, or design an interface that displays multiple reports for the user. However,
handling all the components of the reports and the multiple data sources is complex, which is why Jaspersoft recommends
using iframes to access JasperReports Server at this level.

4.4.2

Hybrid Solutions with Web Services

Web Services cannot access or display dashboards required at this level of embedding. However, as with the example
presented in this chapter, hybrid solutions are very common. They use the web services from level 2 to access level-2 features,
and uses iframes for the level-3 interactivity. This is one example of how applications can transition smoothly between levels,
once the work of installing the JasperReports Server instance is done

32

Level 3: Report and Dashboard Viewers in iframes


For applications that are designed around level-3 embedding to begin with, iframes can be used to implement the entire
solution. For example, the list of reports that are still displayed by web services in this example could be displayed by the
library page of JasperReports Server in an iframe.

4.4.3

iframe Variants

As explained in this chapter, there are several ways to embed iframes. The main choice is between the stripped-down
dashboard or report and the rich interface provided by the repository. By giving users access to the repository, they can access
features such as scheduling if you allow them. However, you must remember to hide or remove the UI that gives access to
features that users should not access.

33

Jaspersoft Embedding Guide

34

Level 4: Ad Hoc Reporting in iframes

CHAPTER 5

LEVEL 4: AD HOC REPORTING IN IFRAMES

The fourth level of embedding includes self-service reporting and analysis for operational applications. This level provides
the user with data exploration through interactive report design and creation tools. These allow the user to analyze data,
possibly from real-time sources, by slicing, dicing, and looking for outliers. Then, the user can create a report around the
findings and save it or distribute it.
The Jaspersoft embedded BI solution for level 4 is to use iframes again and provide access to the Ad Hoc editor where users
can access data presented through a Domain. The powerful in-memory engine of the Ad Hoc editor allows users to explore
their data dynamically, by dragging and dropping columns and rows, changing summary functions, pivoting, and drilling
down to detailed tables. As in level 3, the host application uses iframes to display the servers pages inside of its own user
interface, and then users interact directly with JasperReports Server within that iframe.
This chapter contains the following sections:

Business Example
Solution Using iframes
Implementing Level 4 Embedding
Alternative Solutions

5.1

Business Example

The IMS2 application with embedded Jaspersoft BI is driving data-based decisions for more and more employees at Bucks
Electronics. As more and more employees use the tools, they are innovating and requesting the next generation of capabilities.
Paul is an inventory planner for Bucks Electronics corporate office and now has reports for each of his wholesale distributors.
Some reports are driven by product line, while others are based on specific store metrics. Unfortunately, the distributors
change every few months, and so he frequently requests new reports from Kelly. Other managers and planners have also been
requesting new reports regularly and this takes time away from Kellys other responsibilities.

5.2

Solution Using iframes

Fortunately, Paul understands the data he needs and how to work with it. He and the other managers could create their own
reports if they had access to the right tools. Kelly realizes that JasperReports Server provides a data exploration and report
creation tool: the Ad Hoc editor lets users create reports interactively by dragging an dropping rows and columns in a table,
chart, or crosstab.

35

Jaspersoft Embedding Guide


Kelly creates a menu item and new page in IMS2 to embed another iframe. The URL of the iframe opens the Ad Hoc editor on
Jasper Reports Server. Inside the editor, users can drag and drop fields into tables, charts, and crosstabs. As shown in the
following figure, Kelly uses a theme to set the colors so they match the user interface of IMS2.

Figure 5-1

Ad Hoc Editor Embedded into the IMS2 Application in Level 4 Example

To give users to access to data securely, Kelly configures Domains that can access multiple data sources and join the data into
a single table. The Domain has a presentation layer that Kelly uses to expose data base fields as dimensions or measures with
meaningful labels and default formatting. The Domain provides security and ease of use for users like Paul who understand the
data but might not be familiar with the database schemas and table names. The Domain exposes the data with business labels
that Paul is familiar with.

5.3

Implementing Level 4 Embedding

In the sample scenario, Kelly is upgrading from level 3 to level 4 embedding, both of which rely on iframes and a stand-alone
instance of JasperReports Server. Here is the general procedure for embedded solutions using iframes:

36

Step

Action

Description

1.

Install and configure a stand-alone


instance of JasperReports Server.

Same as described in Level 2, section 3.3.1, Installing and


Configuring JasperReports Server, on page 20.

2.

On the server, create users and roles,


then create folders and permissions in the
repository with role-based permissions.

Same as described in Level 2, section 3.3.2, Creating


Users, Roles, and Folders, on page 21

Level 4: Ad Hoc Reporting in iframes


Step

Action

Description

3.

Create data sources and Domains on the


server that users need to access data.

Kelly uses the virtual data source to join different databases,


and then creates a Domain, as described in section 5.3.1,
Creating a Domain, on page 37.

4.

Create a UI theme on the server to make


the Ad Hoc editor match the IMS2 user
interface.

In order to expose the Ad Hoc editor and the necessary


Domains, Kelly needs to modify permissions and themes on
the server so that they appear in the iframe. For more
information, see section 4.3.2, Customizing the User
Interface, on page 29.

5.

Add user interface components to the


IMS2 application:

The code for the user interface is different for every


application. In this example, the iframe element is embedded
in a simple page that has a title and logo.

New menu option


New page with iframe to display the Ad

Hoc editor
6.

Build and redeploy the IMS2 application.


JasperReports Server does not need to be
redeployed unless the UI configuration
files have been modified.

When users access the application, they interact with the Ad


Hoc editor seamlessly in an iframe.

7.

Offer user training to get the most out of


Ad Hoc views and reports, and to avoid
common pitfalls.

For details, see section 5.3.2, Training Users on the Ad


Hoc Editor, on page 38.

The following sections describe the steps that are specific to level 4 embedding.

5.3.1

Creating a Domain

A Domain is a metadata layer, similar to a database view, that hides the complexity of the database and restricts access to data
so that users see only the data they need, in the format they need it. Ad Hoc reports can be based on Topics, Domains, or
OLAP connections. Topics do not offer the same level of control as a Domain, and OLAP connections require a more complex
OLAP schema. By choosing Domains, Kelly can create and modify the metadata layer in the Domain designer tool within
JasperReports Server.
Creating a Domain with the Domain designer involves defining the following components:

Data Source Domains rely on SQL and can thus be based on any JDBC data source. The first step in defining a Domain
is to select the data source that users will access through the Domain. To create a Domain that accesses data from several
sources, JasperReports Server supports virtual data sources. First create a virtual data source that references two or more
JDBC data source, then select it as the data source for the Domain. However, in order for a report to receive data from
both sources, the tables from each source must have a common key so that they can be joined in the Domain.
Schema In data source that support schemas, such as Oracle and Postgresql, you must select a single schema to appear in
the Domain.
Tables Select all the tables that contain fields (columns) that you want to expose in the Domain.
Derived Tables (optional) A derived table is defined by a query and may contain filters to limit the amount of data
returned. It is a custom table, defined by the Domain creator.
Joins Join statements connect tables together on keys, which are columns that are equivalent in two or more tables. Each
table should be joined to the others so that its fields can be compared to others. Join patterns are often complex, depending
on the number and nature of the database tables. The joins can create patterns such as star or snowflake, as an analogy to a
central fact table linked to multiple dimension tables. Usually, all tables are joined together because unjoined tables,
called data islands, cannot appear in the same report.
Calculated Fields (optional) If you want to compute new values based on arithmetic operations on existing columns, you
can define calculated fields to do this. A calculated field is equivalent to a custom field
Pre-filters (optional) By filtering your dataset based on field values, you can select the ranges and conditions for your
data. Pre-filters operate on the data before it is processed in the Ad Hoc editor, so they speed up the report by reducing the
size of the dataset being returned from the data base and needing to be processed in memory.

37

Jaspersoft Embedding Guide

Display The display of a Domain is the final step where you select the final fields that are exposed to users. These are
the fields that users can use in reports they create in the Ad Hoc editor. You can also set the name of each field, its default
aggregating function, and any translations. The Domain designer lets you group fields into sets, which make it easy for
users to find them in the Ad Hoc editor. The following image shows sets their fields being selected in the Domain
designer.

Figure 5-2

Domain Designer in JasperReports Server

Domains are very flexible and can be used for both simple and complex datasets. The Domain reflects this complexity in the
designer, but exposes a much simpler set of fields for the user to interact with in the Ad Hoc themselves can be simple or
complex, and the following

Data islands Data islands are unjoined sets of fields in the same Domain, and only one data island at a time can appear in
the Ad Hoc editor.
Security file The security file restricts access to both rows and columns based on the logged-in user ID or role. Use a
security file to ensure that only unauthorized users have access to any sensitive data.
Locale bundles Used to translate the name or description of a field in the Ad Hoc editor and the reports it generates.
Domain Topics When basing an Ad Hoc view on a Domain, the user still has the option to filter, select, and rename
fields. Domain Topics are like report-based Topic because they pre-select these options and can be opened directly in the
Ad Hoc editor. Create Domain Topics for your users if they dont need to select fields from the Domain.

For more information about creating Domains and advanced Domain features, see the JasperReports Server User Guide.

5.3.2

Training Users on the Ad Hoc Editor

In previous levels, users of the IMS2 application have been strict consumers of embedded reports and dashboards. In this level,
users create reports and have access to the underlying data. As with Paul in the example, advanced users understand the data
but may not be familiar with interface. The Ad Hoc editor is a complex and powerful tool, and Jaspersoft suggests helping new
users to learn its functionality through simple training sessions and documentation.
Depending on the needs of your users, here are some of the topics they can benefit from:

38

Level 4: Ad Hoc Reporting in iframes

Choosing data from the Domain, such as data islands and pre-filters.
Interacting with Ad Hoc views and saving views as reports.
Choosing tables, charts, or crosstabs to represent data.
Working with sample data and full data sets.
Hiding and revealing panels as needed to maximize the area for data.
Using fields, dimensions, facts, and measures.
Grouping on rows and columns, and pivoting between rows and columns.
Summary functions for groups.
Slicing, dicing, and using filters to reduce the data and find patterns.

5.4

Alternative Solutions

The following row from Table 1-1 on page 9 shows that iframes are the only technology that can easily implement a level 4
solution:
Level
4 - Self-service
reporting and
analysis

JasperReports API
Extremely difficult to reimplement report creator and inmemory data processing.

Web Services
Not possible; use iframes.

iframes & Themes


Best solution; use themes to
control appearance.

An interactive data explorer and report creator is a complex feature that is difficult to implement from the JasperReports API
alone. At the core of the Ad Hoc editor is an in-memory columnar data store and processor that allows near-instantaneous
response and that scales to large datasets. This feature in the JasperReports Server represents years of development and
performance improvements that you can best leverage through an iframe.
There is no API to access Ad Hoc functionality through web services because they are not suited to the stateful interactivity
between the user and the data. However, web services can still be used in hybrid solutions. For example, the reports created
through the Ad Hoc editor could be listed and viewed in the same manner as presented in Chapter 3, Level 2: Embedding
Through Web Services, on page 17.

39

Jaspersoft Embedding Guide

40

Level 5: Advanced Analysis in iframes

CHAPTER 6

LEVEL 5: ADVANCED ANALYSIS IN IFRAMES

The fifth level of embedding is called advanced analytics for deeper insight. This level implements data analysis through online analytical processing (OLAP), and alternative way to store and retrieve data as multidimensional views called cubes.
OLAP cubes are different from standard relational databases and have their own query language called Multidimensional
Expressions (MDX). However, relational OLAP (ROLAP) allows you to store your data in relational databases that are
cheaper or free (MySQL), and access them as if they were cubes.
The Jaspersoft embedded BI solution for level 5 provides several tools for working with OLAP cubes:

Jaspersoft ETL (Extract, Transform, and Load) allows you to prepare and import large volumes of data automatically
from any number of sources into any number of data structures, including optimized relational databases used to define
OLAP cubes.
The schema workbench lets you define an OLAP schema for data in a ROLAP cube.
OLAP views combine a connection to the ROLAP cube with an MDX query to give access to the multidimensional data.
This data analysis tool lets users slice, dice, and drill down through the cubes. Advanced users can edit the MDX query to
modify their view of the cube.

This chapter contains the following sections:

Business Example
Solution Using iframes, OLAP, and ETL
Implementing Level 5 Embedding
Alternative Solutions

6.1

Business Example

As Bucks Electronics stores expand geographically, the data-driven practices of their embedded BI helps employees optimize
their inventory and take decisions that maximize their profits. Each store collects data about deliveries, sales, stock, and many
other dimensions. This data helps store managers and regional office supervisors to plan their orders and time their
promotions. Susan is a product line manager for Bucks Electronics store headquarters, and as a data analyst, she hopes to use
the corporate-wide data to solve some inefficiencies.
From her existing dashboards and Ad Hoc data exploration, she noticed that margin costs are dropping for keyboards and
monitors at the northwest stores compared to those in the southwest. To understand why this is happening, she would like to
explore a variety of data and dimensions including wholesale unit costs, retail price, inventory aging, shipping costs, and
product promotion data. She plans to compare products by store and date (month and year) dimensions, including pulling in
data from their product promotions system. Shell be looking for trends over time, possibly caused by seasonal store patterns
and additional expenses on the supply side.

41

Jaspersoft Embedding Guide

6.2

Solution Using iframes, OLAP, and ETL

Kelly could create more Domains to address these needs, but Susan is familiar with OLAP, and it can provide more powerful
multidimensional analysis. Jaspersoft provides a full range of analysis tools for OLAP, including a viewer that can appear in
an iframe. To implement the embedded solution, Kelly uses Jaspersoft ETL, the schema workbench and OLAP views.
Jaspersoft ETL is necessary in this solution because Susan wants to access data from a wide range of sources across the
company. Performance would be slow if her OLAP view needed to access so many different sources, especially during the day
when they are receiving many transactions. In some cases, the formats or structure of the data might not be compatible
between sources. Jaspersoft ETL lets Kelly automate the collection of the data and do it at off peak hours. If necessary, she can
have it convert data between formats. The result is a new relational database that holds a copy of the historical data that Susan
needs and which is updated nightly with current information from across the company.
To access the data, Kelly uses the schema workbench to create an OLAP schema based on the data in the relational database
(ROLAP). This OLAP schema defines all the various dimensions and fact tables among the information collected by the ETL
process. Along with the schema, Kelly writes an MDX query to create an OLAP view that Susan can use to begin exploring
her data. Susan can always modify the MDX query and save new OLAP views when she finds interesting results.
Jaspersoft OLAP is a viewer that lets users interact with an OLAP view to expand dimension, slice, dice, and drill down to the
data that creates the aggregate values. It displays in the JasperReports Server, therefore Kelly can embed it in an iframe, much
like dashboards and the Ad Hoc editor in previous levels.

6.3

Implementing Level 5 Embedding

In the sample scenario, Kelly is upgrading from level 4 to level 5 embedding, both of which rely on iframes and a stand-alone
instance of JasperReports Server. Here is the general procedure for embedded solutions using iframes:
Step

Action

Description

1.

Install and configure a stand-alone


instance of JasperReports Server.

Same as described in Level 2, section 3.3.1, Installing and


Configuring JasperReports Server, on page 20.

2.

On the server, create users and roles,


then create folders and permissions in the
repository with role-based permissions.

Same as described in Level 2, section 3.3.2, Creating


Users, Roles, and Folders, on page 21

3.

Install Jaspersoft ETL and configure a job


to gather data and make any necessary
transformations. Provision a database to
store the ROLAP tables and fields.

For more information, see the documentation in Jaspersoft


ETL installation.

4.

Run the Jaspersoft workbench tool and


create an OLAP schema for the ROLAP
tables.

For more information, see the documentation for the


Jaspersoft workbench.

5.

Create an OLAP view with an MDX query


to access the ROLAP tables through the
schema.

For more information, see the Jaspersoft OLAP User Guide.

6.

Add user interface components to the


IMS2 application:

The code for the user interface is different for every


application. Kelly again creates a hybrid solution and uses
web services to list OLAP views, then an iframe to display
the chosen view. For more information, see section 4.3.2,
Customizing the User Interface, on page 29.

New menu option


New page with iframe to display the

OLAP view

42

Level 5: Advanced Analysis in iframes


Step

Action

Description

7.

Build and redeploy the IMS2 application.


JasperReports Server does not need to be
redeployed unless the UI configuration
files have been modified.

When users access the application, they interact with OLAP


views seamlessly in an iframe.

8.

Offer user training to get the most out of


OLAP views and to avoid common pitfalls.

Susan has worked with OLAP before, but with a little


training, others can take advantage of this powerful new tool
that is embedded in IMS2.

6.4

Alternative Solutions

The following row from Table 1-1 on page 9 shows that iframes are the only technology that can easily implement a level 5
solution:
Level
5 - Advanced
analytics

JasperReports API
Requires third party
components.

Web Services
Not possible; use iframes.

iframes & Themes


Best solution; use themes to
control appearance.

As with the Ad Hoc editor, the advanced functionality of the OLAP viewer is very difficult and time consuming to implement
without an instance of the server. Jaspersoft ETL is a standalone tool that could be used with any solution, or in hybrid
solutions.

43

Jaspersoft Embedding Guide

44