Jaspersoft Quick Start Guide

The following workflow introduces you to key features and functionality of Jaspersoft’s flagship Business Intelligence product, JasperReports Server, and lets you explore many of its features during your evaluation process.

Why Jaspersoft?



The Jaspersoft BI Suite provides benefits to both business and IT audiences that enable self-service BI for organizations of all sizes. Key benefits of the BI platform include:

  • Full-featured reporting, dashboards, and analytics that are easy to use
  • Flexible web-based architecture you can embed inside your application
  • Subscription model that enables more users at substantially reduced cost

JasperReports Server is the heart of the Jaspersoft Business Intelligence Software Suite. The integrated end-to-end BI suite provides shared services that include multiple levels of security, a repository for storing and organizing your resources, a semantic layer that greatly simplifies creating reports, a report scheduler, distribution of information, and many more features.


The Jaspersoft BI Suite consists of five components:

Embedding Jaspersoft

For those interested in customizing Jaspersoft or embedding/integrating specific features of the BI server in an application, you can do so in a variety of ways:

Leverage our Javascript API’s to add interactive masterpieces to any web page.
Visualize.js adds value to your apps by making embedding reports & visualizations easy to control, scale, and a joy to use. The only embedded BI tool that works the way developers think.
Web Services
Add reporting functionality to applications using REST or SOAP Web Services:
  • Report execution, report scheduling, repository management, administrative services
  • Available samples: Java, PHP, and C. To install any of these samples refer to the readme files in the samples folder of the JasperReports Server installation directory
  • Review chapter 2 in the Web Services Guide for more about our repository web services
Embed objects from Jaspersoft using iFrames and control parameters via URL
User Interface Themes
Web-standard CSS-based themes that you edit to rebrand and customize the application’s look and feel

Jaspersoft Architecture

Jaspersoft Product Architecture

Install and Configure

Install JasperReports Server

JasperReports Server is the heart of the Jaspersoft BI suite, and Jaspersoft provides several installation options. The easiest is to download and install a bundled installation package. We recommend our bundled installers for first-time evaluations because they are easy to provision and de-provision and do not interact with existing systems or processes.

Want to skip the download and installation?

Installing JasperReports Server is a simple process:

  1. Take a free Online Learning Portal course:

  2. Refer to the minimum system requirements in the JasperReports Server Installation Guide in the section on System Requirements
  3. Download a bundled installer using the 30-Day Download option found on http://www.jaspersoft.com/four-ways-test-drive-jaspersoft-bi-software
  4. Run the installer

For additional information see the JasperReports Server Installation Guide also found in the <JasperReports Server install root>/docs directory of your installation.

Install Jaspersoft Studio Report Designer

Jaspersoft Studio is the primary report developer tool for JasperReports. It simplifies the process of creating the JRXML files that describe the report queries and layout while exposing the most powerful capabilities of JasperReports. Use Jaspersoft Studio to develop and test reports on your local desktop and connect to JasperReports Server to deploy reports or browse and interact with existing reports in the JasperReports Server repository.

You are introduced to Jaspersoft Studio during your evaluation. We recommend that you install Jaspersoft Studio on your local desktop as part of your evaluation. If you installed JasperReports Server locally, you’ll want to install Jaspersoft Studio and experience its flexible and robust report creating capabilities.

  1. Download the Jaspersoft Studio installation package for your operating system using the 30-Day Download option found here:
  2. Run the installer to deploy Jaspersoft Studio to your local machine

Installing on Mobile Devices

iOS Quick Start

  1. Download the TIBCO JasperMobile for iOS app and connect to our demo server
  2. Log in with user id phoneuser and password phoneuser

Getting started with the Mobile SDK for iOS

  1. Go to http://community.jaspersoft.com/project/mobile-sdk-ios
  2. Click the Jaspersoft Mobile SDK for iOS button to download the latest released version

Android Quick Start

  1. Download the TIBCO JasperMobile for Android app and connect to our demo server
  2. Log in with user id phoneuser and password phoneuser

Getting Started with the Mobile SDK for Android

  1. Go to http://community.jaspersoft.com/project/mobile-sdk-android
  2. Click the Download the Mobile SDK for Android button to download the latest version

Configure JasperReports Server

The following are important initial configurations for your evaluation of JasperReports Server.

Configure your JVM

Proper configuration of your JVM ensures high performance and scalability of any JAVA application, including JasperReports Server.

Many JVM settings are set appropriately by the installer, however you should review the settings and adjust the memory allocated to your JVM according to your needs and available resources. Consider the following when setting memory allocation:

  • The number of users, organizations, and reports defined in your implementation/repository
  • The size of the data sets on which you analyze and report
  • The size of the reports that you expect to generate
  • The number of reports you expect to schedule for execution and delivery
  • The number of concurrent users that access your implementation
  • The overall availability of resources on the host server

A minimum heap allocation (-Xms) of 512 MB and a maximum heap allocation (-Xmx) of 1024 MB is recommended for evaluation purposes. Consider a higher allocation for production purposes. In most cases a maximum heap of between 4 and 8 GB is sufficient for larger production implementations, but this seting varies between implementation profiles.

To check your Java JVM settings refer to the JasperReports Server Installation Guide: Setting Java JVM Options for Application Servers.

Configure the Report Scheduler

The JasperReports Server report scheduler leverages the quartz framework to schedule the execution of reports and their delivery via email. The email can include a link to the generated reports—which are stored in the JasperReports Server repository—and/or an attachment of the generated report. Configure the settings to ensure that:

  • JasperReports Server can access your outbound email server
  • Email notifications are sent from a valid email address
  • Repository links correctly reference your server domain or IP address
  • The misfire threshold is set appropriately for your implementation

See the following write-up on configuring the report scheduler for additional information and instructions: Configuring the JasperReports Server Report Scheduler.

Add the JDBC Driver for Your Data Source

JasperReports Server redistributes a Postgres database driver. If you need to connect to another database, acquire the appropriate driver and add it the application server’s classpath.

The Jaspersoft Community wiki page at Connecting JasperReports Server to your Database, particularly the section titled JDBC Database Driver, offers download links to many JDBC connectors provided by database vendors.

You may need to check with your DBA to ensure you are using the correct driver.

Configure the JNDI Connection to Your Data Source

JasperReports Server can use a JDBC or JNDI connector as the connection point to your dataset. In many cases a JDBC connection is acceptable and can be configured without an application restart, however a JNDI connection provides more control over connection pooling and other scalability aspects around database connectivity. Configuring a JNDI connection (for use in defining a JNDI data source within the application) varies depending on your application server.

The Jaspersoft Community wiki page Connecting JasperReports Server to your Database includes a section on JNDI Configuration.

For information on setting up or troubleshooting a JNDI connection for Tomcat, JBoss or WebLogic, scroll down the JasperReports Server Administrator Guide page at: Working with Data Sources. For other application servers, refer to the documentation provided by the application server vendor.

Configure Jaspersoft Studio Report Designer

Configuring and connecting to your data is a critical first step with Jaspersoft Studio. The following helps you with this process.

Connecting to Your Data

Jaspersoft Studio connects to data via a data adapter. A data adapter is an XML file that contains information about where your data is located. It includes information such as a URL, user and password credentials, paths, etc. A data adapter contains no data itself; the data is located in the JRDataSource.

Use data adapters to:

  • Define the data connection type. The connection is a SQL connection rather than a JasperReports or Jaspersoft Studio object
  • Bind information to connect your data to Jaspersoft Studio
  • Create the connection and necessary parameters for the JasperReports library

Review chapter 10 of the Jaspersoft Studio User Guide to see how to implement a variety of data adapters like Hibernate, Hadoop, MongoDB, XML, CSV, and custom data sources.

Configure your Connection to the JasperReports Server Repository

Jaspersoft Studio includes a JasperReports Server plug-in with which you browse the JasperReports Server repository and deploy reports to the server. Configure the plug-in to connect to your JasperReports Server repository. Review chapter 5 in the Jaspersoft Studio User Guide: Connecting Jaspersoft Studio to JasperReports Server for additional information on configuring the plug-in to connect to your JasperReports Server installation.

Starting/Stopping JasperReports Server

Complete start/stop instructions for JasperReports Server are found in the JasperReports Server Installation Guide: Starting and Stopping JasperReports Server.

Accessing JasperReports Server

JasperReports Server ships with several sample user accounts with which you access the application, including a site-wide administrative user (superuser), an organization administrative user (jasperadmin), an end user (joeuser), and a user to demonstrate that a dashboard can serve as someone’s home page (demo). For information on accessing JasperReports Server, see the JasperReports Server Installation Guide: Logging into JasperReports Server.

Working with Data

Overview of Jaspersoft

Before working with your data watch this four-minute product overview to learn the core capabilities of Jaspersoft, including building and interacting with reports, dashboards, and analytic views.

Connecting to and Describing Your Data

Establishing Your Data Source Connection

For evaluation purposes we focus on two primary data source types for connecting to a SQL-based database: A JDBC connection and a JNDI connection.

JNDI Data Source

During the installation and configuration steps, we showed how to set up a JNDI resource within the Tomcat application server. This resource is referenced when configuring a JNDI data source connection. To define a JNDI data source connection within JasperReports Server, refer to the JasperReports Server Administration Guide: JNDI Data Sources.

JDBC Data Source

To create a JDBC data source you must first have deployed the appropriate JDBC driver as outlined above. Defining a JDBC data source is similar to defining a JNDI data source.

Refer to the JasperReports Server Administration Guide: JDBC Data Sources.

Creating Domains that Represent Your Data

A Domain represents your data in a way that matches the business or object model your users understand. Domains create a layer of abstraction between the complexity of the database’s table joins, field labels, etc. and the end user who creates reports. Domains also add row- and column-level security to reports that is based on the user profile.

Learn and see the advantages of Domains in this short tutorial.

Create a Domain with the Domain Designer, an easy-to-use wizard within JasperReports Server. Refer to the JasperReports Server User Guide: Creating Domains for details on creating Domains.

Visualizing and Interacting with Your Data

Creating Ad Hoc Views

JasperReports Server lets you analyze data using chart visualizations or tabular views against predefined Topics, Domains, or OLAP connections. The Ad Hoc report designer is the primary tool in JasperReports Server for analyzing data. To get started, select the Create>Ad Hoc View menu item and follow the workflow. The following tutorial shows an example of creating ad hoc views.


JasperReports Server allows users to quickly create dashboards containing multiple reports from the repository along with external content. With dashboards you create a single comprehensive view of key business metrics for managers and executives. This video shows how to build and interact with a dashboard:

Interactive Reporting for Non-Technical Users

JasperReports Server provides tools for non-technical or BI administrators to build their own reports against a predefined Topic, Domain, or OLAP connection. This tutorial shows how to view, interact with, and define reports using the Ad Hoc report designer.

For more information on ad hoc reporting refer to Section 4 on this page: http://www.jaspersoft.com/olp/using-js-bi.

NOTE: If you're building more-advanced reports that are highly formatted, designed for print layout, or simply require more-advanced report concepts, check out the Creating Your First Report with Jaspersoft Studio section below.

Creating Your First Report with Jaspersoft Studio

Jaspersoft Studio is a flexible and robust tool for creating custom reports leveraging the full power of the JasperReports reporting engine. To create your first report using Jaspersoft Studio review our simple tutorial or read chapter 4 Creating a Simple Report in the Jaspersoft Studio User Guide.

To learn more about Jaspersoft Studio check the tutorial series on our Community site.

NOTE:  We recommend using the JasperReports Server plug-in within Jaspersoft Studio to open and view sample reports found in the JasperReports Server repository. By viewing these reports and possibly copying and modifying them on your own, you will gain a better understanding of the capabilities of Jaspersoft Studio for report development.

Input Controls and Filters

Input controls, or filters, are UI components that let users specify the content they want to see in the report. Input controls are tied to parameters defined within the report and let users modify the report query at run time.

Cascading Input Controls

Cascading input controls dynamically populate based on previous control choices—the value(s) selected in one control determine the values available in the next. For example, a report may be filtered on countries, states/provinces and cities. Using cascading input controls, the country(ies) selected in the first control determines what states/provinces are available in the second control, and the states/provinces selected in the second control determine what cities display in the third control. The user might then select one or more cities and then click the Run button to execute the report and see information concerning the selected cities.

A sample report using cascading input controls and named Cascading multi select example report is found in the Reports/Samples folder of the default organization if you installed the sample data.

Saved Report Options

For convenience users can save input control values.

To save input control values:

  1. Execute the report in JasperReports Server and view the input controls
  2. Select the input control values with which you want to run the report
  3. Click the Save button
  4. A Save Values dialogue box appears. Enter the name you want to assign to these value selections and click Save

After you save a set of input control values, the Input Controls dialogue for the report includes a Use saved values drop-down box. A user can select a menu choice from the drop-down to automatically populate the input control(s) with the value(s) associated with that drop-down menu selection.

A sample report with saved options, named Customers by State Report, is found in the Supermart Demo/Supermart Public folder of the default organization if you installed the JasperReports Server sample data.

Drill-through Reports

In JasperReports Server a report developed using Jaspersoft Studio can leverage hyperlinks to drill from one report to a more-detailed view of data making up a summary value within the report. For example a pie chart shows the percent of total sales by region and each section of the pie chart links to a second report that displays the sales detail for that particular region.

Using Jaspersoft on an Mobile Devices

TIBCO JasperMobile are native applications for your iOS or Android devices that let you browse, view, and interact with reports and dashboards from JasperReports Server. Additionally, JasperMobile comes with an SDK that allows you to build your own mobile apps and leverage mobile analytics.

Watch this video for a demonstration:

Report Distribution

Scheduling your Report Execution and Delivery

JasperReports Server provides report scheduling and distribution. Based on a one-off or recurring schedule you configure, reports are automatically executed and saved to the repository in up to eleven formats. If your SMTP email server is available you can send alert messages to notify individuals of the report’s availability. You can also include links to the reports, include the reports as HTML in the body of the email message, or attach the reports.

To schedule a report for future execution:

  1. Right-click the report's title and select Schedule
  2. Click the Schedule Job button
  3. Enter the job name and optionally a description
  4. Specify when the job should start and the scheduled recurrence of the job
  5. Click Next
  6. If the report has input controls, specify the control values with which you want the report to run. Otherwise skip to step 8
  7. Click Next
  8. Specify the output file name, description, location to which you want the generated reports saved, and format(s)
  9. If you want to send email notifications, enter appropriate information and select if/how you want to include the report with the outgoing email message
  10. Click Submit

Securing Your Data

Implementing Multiple Organizations

JasperReports Server supports multiple organizations or customers in a multi-tenant environment, securing each tenant’s reports and data from users who belong to different organizations. Each organization can configure their own administrators, user accounts, roles, UI themes, data source definitions, and reports. Users access resources only within their organization or published to the Public folders of the repository tree. JasperReports Server’s sample data includes a single organization whose resource ID is organization_1.

Configuring a new organization is a simple process:

  1. Log in to JasperReports Server as the system super user (default credentials: superuser/superuser)
  2. From the main menu select Manage>Organizations
  3. Click New
  4. Enter the name, id, etc. of the organization or company you want to add
  5. Click Save

The new organization is created. The superuser or organization admin user (jasperadmin) selects Manage>Users from the main menu to configure user accounts in the organization. After you define a second organization the JasperReports Server login page displays an additional field with which each user specifies their organization ID. After logging in the organization information is stored in a browser cookie and is not requested again unless the cookie is cleared. Additionally you can provide your users with a URL that specifies the organization so that they are no longer prompted for their organization ID.

For more information see the JasperReports Server Administration Guide section on Managing Organizations.

Establishing User Roles

JasperReports Server leverages user roles to govern access permissions over repository folders and resources. Several roles are included in the JasperReports Server sample data.

The following explains how to define user roles:

  1. Log in as a superuser or organization administrator
  2. From the main menu select Manage>Roles
  3. Select the organization to which you want to add the role. (Roles added at the root level are available to all organizations)
  4. Click Add Role
  5. Enter a role name and click Add Role

One or more roles can be assigned to a user. To assign a role to a user:

  1. Log in as a superuser or organization administrator
  2. From the main menu select Manage>Users
  3. Select the organization to which the user account belongs
  4. Select the user account to which you want to assign the role
  5. Click Edit
  6. At the bottom of the user properties panel highlight the appropriate role(s) in the Roles Available panel
  7. Click the selection arrow to move the role(s) to the right
  8. Click Save

For additional information see the JasperReports Server Administration Guide sections on Managing Users and Managing Roles.

User Permissions

Users and roles can be granted specific permissions to folders and individual resources in the JasperReports Server repository. Access permissions include options such as Execute Only, Read, Write, and more to allow users or groups of users to view reports, execute against specific data sources, and create/deploy reports of their own. To assign permissions right-click on the resource title and select Permissions from the context menu to display the Permissions window. Permissions granted to parent folders are inherited by child folders unless child-folder permissions are explicitly set.

For more information see the JasperReports Server Administration Guide section on Permissions.

Row- and Column-Level Security

Data-level security is a common requirement and restricts content displayed in an Ad Hoc report based on the user’s profile. Data-level security in JasperReports Server is enforced through an XML security file attached to a Domain. The XML security file consists of a specific schema and rules that use Groovy expressions to identify users who can and cannot see certain rows and/or columns in reports built from that Domain.

Here is an example of row-level security mark-up in the file:

<securityDefinition xmlns="http://www.jaspersoft.com/2007/SL/XMLSchema" version="1.0" itemGroupDefaultAccess="granted"> <resourceAccessGrants> <resourceAccessGrantList id="JoinTree_1_resource_access_grant" label="aLabel" resourceId="JoinTree_1"> <resourceAccessGrants> <resourceAccessGrant id="JoinTree_1_ROLE_USER_TENANTID_row_grant"> <principalExpression> authentication.getPrincipal().tenantId != null </principalExpression> <filterExpression> table.tenantcolumn == groovy('authentication.principal.tenantId.toUpperCase()') or ERSI_ESTIMATE.OPERATORCODE == groovy('authentication.principal.tenantId.toUpperCase()') </filterExpression> </resourceAccessGrant> </resourceAccessGrants> </resourceAccessGrantList> </resourceAccessGrants> </securityDefinition>

Let’s examine how security is enforced:

  1. resourceAccessGrants and resourceAccessGrantLists specify what resources are secured
  2. Define the resource you are securing with the id attribute (this must match the ID of the resource item you are securing using row-level security)
  3. Define a principal expression that states for whom (userid or tenantid) you are securing the data (this usually translates to a username or tenantid check)
  4. Finally, define a filter expression where the column name from your data is equal to a groovy expression (that also translates to a username or tenantid)

Column-level security is similar except that itemGroupAccessGrants and itemGroupAccessGrantLists secure the items (columns) that you defined in the Domain. After the security file is configured it is uploaded to the repository and attached to the Domain via the Domain Design wizard in JasperReports Server. Security takes effect when Ad Hoc reports are created from the Domain. Reference the documentation to discover the id’s to use for each access grant.

Integrate and Embed

JasperReports Server provides several interfaces that allow you to integrate or embed Jaspersoft Business Intelligence. You want to integrate two key areas: authentication and the user interface.

Below we introduce you to Single Sign-on capabilities that enable you to integrate JasperReports Server with your authentication mechanism. We then introduce you to some options for integrating your application’s user interface with JasperReports Server.

Single Sign-on

Implementing single sign-on (SSO) results in a user being able to log in to JasperReports Server based on a shared login mechanism and ID. Common external authentication mechanisms include external DB, LDAP, CAS, and Token Based Authentication. The following videos gives an introduction to these authentication methods:

There are also videos available with details on Token-Based Authentication, LDAP Authentication, External Database Authentication

For documentation on Single Sign-on integration refer to the JasperReports Server External Authentication Cookbook.

User Interface Themes/Skins

The JasperReports Server application can be customized to match the appearance of another application and rebrand the user interface. CSS-based themes allow a set of changes to be packaged together in one view. Themes are stored in the repository and are part of the JasperReports Server UI framework that provides separation of structure, presentation, and events.

See the video below for an example of a theme and other examples of UI customization.


Visualize.js is a JavaScript API framework used to embed JasperReport Server reports & visualizations inside web applications.

The following videos show how to get started with visualize.js:

The best way to get started with visualize.js is to learn by example:


Reports and dashboards can be called via HTTP and embedded via iFrames into your applications. Different objectives accomplished using this mechanism are listed below. This is not an exhaustive list but a starting point so you can see what’s possible.

  1. If referencing a report, the type of element to display is included among the parameters
  2. As demonstrated by the following example, authentication—and therefore the login page—can be skipped when you include the login credential parameters j_username and j_password in the URL
  3. If a current version of JasperReports Server is installed locally, the following URL loads a dashboard with no JasperReports Server UI. Notice that the URL contains the login credentials j_username=joeuser and j_password=joeuser:

The video below demonstrates embedding a report into a web page using iFrames.

Web Service API’s

The SOAP and REST Web Service API’s allow components of JasperReports Server to be integrated into other applications via Web Service calls by the hosting application. This includes repository services, scheduling services, Domain services and administrative services. Web Service requests are authenticated using Spring Security and can be configured to use HTTPS.

See the video below for an example of a Java application that utilizes Web Services to provide JasperReports Server functionality in that application.


Advanced Topics

Installing JasperReports Server using the WAR file installation

Leveraging Jaspersoft OLAP for Data Analysis

Migrating, Transforming, and Cleaning Your Data

Many people run their reporting and analytics on a database other than their operational data store, such as a data warehouse or secondary data mart. Jaspersoft ETL is a powerful data integration platform with which data architects and ETL developers extract and transform data from multiple sources and store it in a single database. With hundreds of components and connectors, Jaspersoft ETL pulls data from almost any database, file format, or Big Data source and transforms and loads it into an integrated database for reporting and analysis.

See the video below for an introduction to Jaspersoft ETL.

Additional Resources


After you install JasperReports Server, a full set of standard documentation is found in the <JasperReports Server Install Root Directory>/docs directory. Find nearly all of our documentation free online at our Community Website.


JasperReports Server provides the option to install sample data and reports. Additionally there are several sample reports, web services samples, etc. available in the <jasperreports install server directory>ireport/demo/samples directory and the <jasperreports install root server>/samples directory. Many of these samples are documented online:

Community Forums and Wiki Documentation

With over 400,000 community members, the Jaspersoft community provides a place to interact with other Jaspersoft developers, administrators, and expert users. The Jaspersoft community is an invaluable resource for finding answers to common questions as well as those questions related to your specific use cases. Each core project has its own forums and wiki documentation. To access the Jaspersoft community site, point your browser to http://community.jaspersoft.com/.