Jaspersoft Quick Start Guide

The following workflow will introduce you to the key features and functionality of Jaspersoft’s flagship product, JasperReports Server, and allow you to see and interact with many of the features as part of your evaluation process.

Guided, training-based evaluation assistance

Register Now

Why Jaspersoft



The Jaspersoft BI Suite provides benefits to both business and IT audiences which enables self service BI for organizations of all sizes. The key benefits of the BI platform are:

  • Full featured reporting, dashboards, and analytics that are easy to use
  • Flexible web-based architecture that is easy to embed inside another application
  • Affordable license model to reach more users for less cost

The integrated end-to-end BI suite provides shared services, such as security, a repository, metadata, scheduling, and distribution of information. The heart of the Jaspersoft BI Suite is JasperReports Server.


The Jaspersoft BI Suite consists of five different components, which are listed below:

Embedding Jaspersoft

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

Web Services
Add reporting functionality to applications using REST and SOAP Web Services:
  • Report execution, report scheduling, repository management, administrative services
  • Available samples: Java, PHP, C. To install any of these samples please refer to the readme files in the samples folder of the JasperReports Server install directory.
  • More about our repository web service
Java API
Add your own actions and pages to JRS leveraging our Java API(s):
  • Repository, Report Data Service, Report Scheduling, Users and Roles, Object Permissions, OLAP Connections
Execute reports using HTTP and HTTPS
User Interface Themes
Web standard CSS based themes that can be edited to rebrand and customize the look and feel of the application

Jaspersoft Architecture

Jaspersoft Product Architecture

Install and Configure

Install JasperReports Server

Jaspersoft offers several installation options. The easiest path is to download and install a bundled installation package. Our bundled installers are strongly encouraged for first-time evaluations, as they are easy to provision and de-provision and do not interfere 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, Section 1.5: System Requirements.
  3. Download a bundled installer using the 30 Day Download option found on http://www.jaspersoft.com/jaspersoft-business-intelligence-software-trial.
  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 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. Jaspersoft Studio can be used to develop and test reports on your local desktop as well as connect to JasperReports Server to deploy reports or to browse and interact with existing reports within the JasperReports Server repository.

As part of your evaluation, we will introduce you to Jaspersoft Studio. We recommend that you install Jaspersoft Studio on your local desktop as part of your evaluation. If you installed JasperReports Server locally you must also chose to download and install Jaspersoft Studio as well.

  1. Download the Jaspersoft Studio installation package for the operating system you plan to install using the 30-Day Download option found at the following location:
  2. Run the installer. The installer will deploy Jaspersoft Studio based on the Eclipse framework to your local machine.

Installing on Mobile Devices

iPad Quick Start

  1. Use our demo server to quickly view and interact with sample data by opening Safari on your iPad and going to http://mobiledemo.jaspersoft.com/jasperserver-pro/
  2. Login as user id: joeuser, password: joeuser

iPad with your own Jaspersoft installation

  1. Install Jaspersoft on your local machine (see section 1, above), or sign up for a free 7-day live trial
  2. With Jaspersoft installed and running, open Safari on your iPad and type the URL of your Jaspersoft login page
  3. To learn how to interact with your data, see the video below:

iPhone Quick Start

  1. Download the sample iPhone app and connect to our demo server.
  2. Login as user id: phoneuser, password: phoneuser

Getting started with the Mobile SDK for iOS

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

Android Quick Start

  1. Download the JasperMobile for Android app and connect to our demo server.
  2. Login as user id: phoneuser, password: phoneuser

Getting Started with the Mobile SDK for Android

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

Configure JasperReports Server

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

Configure your JVM

Proper configuration of your JVM is an important step to ensure performance and scalability of any JAVA application, including JasperReports Server.

Many of the JVM settings will be set appropriately by the installer, however it is recommended that you review the settings and adjust the memory allocation to your JVM according to your own needs and available resources. When choosing your memory allocation settings, you should consider the following:

  • The number of users, organizations, and reports you will have defined within your implementation/repository
  • The size of the datasets that you will be analyzing and reporting upon
  • The size of the reports that you expect to generate
  • The number of reports you expect to schedule for execution and delivery at any given time.
  • The number of concurrent users that will be accessing 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. For production purposes, it is recommended that you consider a higher allocation. In most cases, a maximum heap allocation between 4 GB and 8 GB has been sufficient for larger production implementations, but this can vary between implementation profiles.

To check your Java JVM settings refer to Section 6.2 of the JasperReports Server Installation Guide, "Setting Java JVM Options for Application Servers."

Configure the Report Scheduler

The scheduling functionality of JasperReports Server leverages the quartz framework to schedule the execution and delivery of reports via email. The email can include either a link to the report output within the JasperReports Server repository and/or an attachment of the actual report output. You will need to ensure that the appropriate configuration settings are set to ensure that:

  • JasperReports Server is configured with the necessary access to your outbound email server
  • The email notifications are sent from a valid email address
  • Any repository links correctly reference back to 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, you will need to acquire the appropriate driver and add it the application server's classpath.

The Jaspersoft Community Wiki page,  Connecting JasperReports Server to your Database, particularly the section: JDBC Database Drivers, has download links to many of the various 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. Setting up a JNDI connection (for use in defining a JNDI data source within the application) will vary depending on your chosen application server.

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

For additional information on setting up and troubleshooting a JNDI connection in Apache Tomcat, refer to the JasperReports Server Administrator Guide,  JNDI Issues on Apache Tomcat.  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 steps will help you with this process.

Connecting to Your Data

Jaspersoft Studio connects to data through 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, password, paths, etc. A data adapter does not contain any data itself, the data is located in the JRDataSource.

Data adapters are used 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 JasperReports library

See how to connect Jaspersoft Studio using the JDBC data adapter as well as other connection types such as 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 that provides the capability to browse the JasperReports Server repository and deploy reports to the server. You will need to configure the plug-in to connect to your JasperReports Server repository. See the Jaspersoft Studio User Guide and the “Connecting Jaspersoft Studio to JasperReports Server,” for additional information on configuring the plug-in to connect to your installation of JasperReports Server.

Starting/Stopping JasperReports Server

Complete start/stop instructions for JasperReports Server can be found in the JasperReports Server Installation Guide, “Starting and Stopping JasperReports Server.”

Accessing JasperReports Server

JasperReports Server has several default users that can be used to access the application, including a site-wide administrative user (superuser), an organization administrative user (jasperadmin), a sample end user (joeuser), and a user to demonstrate the ability to set a dashboard as the default landing 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 own data, watch this 4-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

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

JNDI Data Source

During the install and configuration steps, we showed how to set up a JNDI resource within the Tomcat application server. This resource will be referenced when setting up 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 have deployed the appropriate JDBC driver as outlined previously. Defining a JDBC Data Source is similar to how we defined the JNDI Data Source, refer to the JasperReports Server Administration Guide, “JDBC Data Sources.”

Creating Domains that Represent Your Data

Domains are used to create representations of your data to match the business or object model your end users understand. They create a layer of abstraction between the user creating reports and the database with predefined joins, labels, etc. to make it easier for users to understand and create reports. Domains also add an additional layer of security to the data, creating the ability to create row and column-level security based on the user profile.

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

You can create a domain using the domain designer within the JasperReports Server interface. Refer to the JasperReports Server User Guide, “Creating Domains,” for details on domains and how to create your first domain.

Creating Topics that Represent Your Data

Topics represent predefined queries and filters associated with a data source from which ad hoc reports can be created. They are typically created through Jaspersoft Studio by an administrator and deployed to the server for end-user convenience. Topics can also be saved from a Domain within the server as an intermediate step during the ad hoc report creation process.

Creating a topic in Jaspersoft Studio is similar to creating a report. Simply create a report with a query and filters, deploy it to the server in a Topics folder and associate it with a data source. Your users will be able to leverage this predefined set of data to create their next ad hoc report.

For additional information, see:

Visualizing and Interacting with Your Data

Analyzing your Data

JasperReports Server gives end users the ability to analyze data using chart visualizations or tabular views against predefined topics, domains, or OLAP connections. The primary tool used to analyze data is the Ad Hoc designer. To get started, click on the Create>Ad Hoc View menu item and follow the workflow. The following tutorial shows an example of connecting to and analyzing data using JasperReports Server.

Ad Hoc Reporting for Non-Technical Users

JasperReports Server offers tools for non-technical or BI administrators to build their own reports against a predefined topic, domain, or OLAP connection. This tutorial will show how to view, interact with, and define reports using the Ad Hoc Designer.

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

NOTE: If you're trying to build more advanced reports that are highly formatted, designed for print layout, or simply require more advanced report concepts, check out the "Creating a Report with Jaspersoft Studio" section below.


JasperReports Server allows end users to quickly create dashboards containing multiple reports from the repository along with external content. With dashboards, they will be able to create a single, comprehensive view of key business metrics for managers and executives. The tutorial below shows an end user building and interacting with a dashboard.

For more information on dashboards refer to Section 2 on the following page: http://www.jaspersoft.com/olp/using-js-bi.

Creating Your First Report with Jaspersoft Studio

Jaspersoft Studio is a powerful tool for creating custom reports leveraging the full power of the JasperReports reporting engine. To create your first report using Jaspersoft Studio check out our simple tutorial or read the chapter, "Creating a New Report" in the Jaspersoft Studio User Guide.

To learn more about Jaspersoft Studio, check out 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 within JasperReports Server. By viewing these reports, and possibly copying and modifying them on your own, you will have a better understanding of the capabilities of Jaspersoft Studio for report development.

Input Controls/Filters

Input Controls, or filters, are user interface components that provide end users with the ability to limit or select specific data to report on and analyze. By tying input controls to parameters defined within the report, JasperReports Server provides end users with the ability to modify the report query at run time.

Cascading Input Controls

Cascading Input Controls provide the ability for end users to select related report filtering options by limiting the available options within input controls based on the value(s) selected in a preceding input control. For example, a report may be filterable based on global regions, countries, states/provinces and cities. With cascading input controls, the available countries can be limited by the global region selected, the states/provinces can be limited by the countries selected, and so on.

A sample report using cascading input controls, named “Cascading multi select example report”, can be found within the Reports/Samples folder of the default organization if you installed the sample data within your implementation.

Saved Report Options

For convenience, end users can label and save a set of report options or input control selections that are commonly used for a report. By doing so, this saved option set can be used later to run the report based on a predefined set of filter options.

To save a set of report options:

  1. Select a report from the repository or search the browser within JasperReports Server.
  2. Select the filter values you wish to run the report with.
  3. Click “Save”.
  4. A Save Values dialogue box will appear. Enter the name you would like to save the value selections as and Click “Save”.

Once you have saved a set of report options, the Input Controls dialogue for the report will include a “Use saved values” dropdown at the top that can be used to re-select these options for future report executions. In addition, within the repository viewer, the report will have an expandable list of saved options listed so that the saved options can be selected directly from the repository browser.

A sample report with saved options, named “Customers by State Report”, can be found in the Supermart Demo/Supermart Public folder of the default organization if you installed the sample data within your implementation.

Drill-through Reports

Within JasperReports Server, a report developed using Jaspersoft Studio can leverage hyperlinks to enable the ability to drill from one report to a more detailed view of data making up a summary value within the report. For example, you may have a pie chart that shows the percent of total sales by region and each section of the pie chart could link to a second report showing the sales detail for that particular region.

Using Jaspersoft on an iPad

  1. Open Safari on your iPad and connect to our demo server or configure with your own environment.
  2. Watch the video on how to interact with the sample data:

Report Distribution

Scheduling your Report Execution and Delivery

JasperReports Server provides a scheduling and distribution capability. Based on a set frequency or date, reports can be automatically executed and saved into the repository for future viewing. Email notifications can also be defined with the report schedule to notify individuals of the report’s availability either with a link back to the repository location or with the physical attachment of the report output to the email.

To schedule a report for future execution:

  1. Right click on the report in the repository browser and select “Schedule…”
  2. Click “Schedule Job”
  3. Enter the Job Name/Description
  4. Select when the job should start and the scheduled recurrence of the job
  5. Click “Next”
  6. If the report has filter options, select the filter values that you want the report to run with, otherwise skip to step 8
  7. Click “Next”
  8. Enter the output file name, location, description, and format
  9. If you would like email notifications to be sent, enter the email addresses, subject and message to be sent and select if you would like to have the report attached to the email
  10. Click “Submit”

Securing Your Data

Implementing Multiple Organizations

JasperReports Server supports use across multiple organizations or customers in a multi-tenant environment, maintaining security of reports and data between users from different organizations or customers. Each organization can have their own administrators, user roles, UI themes, data source definitions, and reports. Users will only have access to resources defined within their organization or published in the Public portion of the repository tree. JasperReports Server has a single standard organization by default called “organization_1”.

Setting up a new organization is a simple process:

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

The new organization now exists within your implementation. The superuser or the organization admin user(jasperadmin) can use the Manage>Users menu to set up users within the organization. Once you have defined a second organization within your implementation, the login screen for JasperReports Server will e xpose an additional organization field to specify the organization alias or organization id associated with the user that is logging into the system. Once a user has successfully logged in, the organization information will be stored in a browser cookie and will not be requested again unless the cookie is cleared or the user login is unsuccessful. Additionally, you can provide your users with a URL that specifies the organization so that they will not be asked for their organization id.

For more information,  see the  JasperReports Server Administration Guide sections on Managing Organizations

Establishing User Roles

JasperReports Server leverages user roles to establish permissions over repository objects and folders. There are several roles defined already within the standard installation of JasperReports Server.

The following outlines how you can define your own user roles:

  1. Login as a superuser or organization administrator
  2. Go to Manage>Roles
  3. Select the organization you would like to add the role to. (Roles added at the root level will be available to all organizations)
  4. Click “Add Role…”
  5. Enter a role name and click “Add Role

A user can have multiple user roles. The following are the steps to add a role to a user:

  1. Login as a superuser or organization administrator.
  2. Go to Manage>Users.
  3. Select the organization to which the user you want to add a role to belongs.
  4. Select the user to which you would like to add the role.
  5. Click “Edit”.
  6. On the bottom of the user properties panel, select a the role you would like to add from the Roles Available.
  7. Click the right arrow to move the role to roles assigned.
  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 resources within the JasperReports Server repository. Access rights include options such as execute only, read, write, etc. to allow users or groups of users to view reports, execute against specific datasources, and create/deploy reports of their own. In order to set permissions, simply right click on the resource and select the permissions option. Permissions granted to parent folders are inherited by child folders unless set explicitly otherwise.

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

Row and Column Level Security

Data level security is a pretty common requirement in order to be able to present the appropriate slice of data to a particular user based on their profile. This is possible within JasperReports Server using domains. After an initial domain has been built to describe your data, an xml file with a certain schema can be designed where Groovy expressions can be used to secure both rows and columns in your data and domain.

Let’s look at an example of row level security :

<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 breakdown the steps to achieving this:

  1. resourceAccessGrants and resourceAccessGrantLists specify what resources are being secured.
  2. Define the resource you are securing by the id attribute (this must match the id of the resource item you are securing using row level security).
  3. Define a principal expression which basically states who (userid or tenantid) you are securing the data by (this usually translates to a username or tenantid check).
  4. Finally you will define a filter expression of the form shown above where the column name from your data is equal to a groovy expression (that also will translate to a username or tenantid).

Column level security is similar except for the fact that itemGroupAccessGrants and itemGroupAccessGrantLists are used to secure the "items" (columns) that you have defined in the domain. Once the security file has been defined it is uploaded and attached to the domain and will take effect when the data and domain are accessed through JasperReports Server. It is highly recommended that the documentation be referenced in order to understand what id’s to use for each access grant.

Integrate and Embed

If you are developing a product or managing an environment in which you want to integrate or embed BI, JasperReports Server provides several interfaces to allow you to do so quickly and easily. When integrating JasperReports Server into your environment or application, you will want to integrate two key areas: authentication and user interface.

We will introduce you to the Single Sign-On capabilities of JasperReports Server that will enable you to integrate with your chosen authentication mechanism. We will then introduce you to a few options for developing the integration between the user interface of your application and JasperReports Server

Single Sign-on

Implementing this mechanism results in a user being able to log into JasperReports Server based on a shared login mechanism and Id. Common external authentication mechanisms include LDAP, CAS, or SiteMinder. As an example, we will discuss integrating JasperReports Server with LDAP.

Configuring LDAP for JasperReports Server requires knowledge of your LDAP structure and system administration access to the server on which JasperReports Server is installed. Listed below are the high level steps involving modifications to the applicationContext-security.xml file within your JasperReports Server implementation:

  1. Uncomment and configure the ldapContextSource bean. This bean will be configured with the connection string to your ldap server as well as admin account credentials.
  2. Uncomment and configure the ldapAuthenticatonProvider bean. This bean will handle finding, binding, and authenticating the user you are attempting to login with as well as assigning the defined user roles for that particular user if roles are defined and assigned in the LDAP system.

There are 2 constructor arguments for this bean that must be configured; the first is the BindAuthenticator which handles binding and authenticating with ldap and the second is the ldapAuthoritiesPopulator which handles searching for a user roles and assigning them to the user for use within JasperReports Server.

The following video describes the integration between an Open LDAP server and JasperReports Server.

Integrating with other mechanisms such as Active Directory would involve a similar process.

For more information on Single Sign-On integration please refer to the JasperReports Server External Authentication Cookbook.

User Interface Themes/Skins

The JasperReports Server application can be customized to match the look and feel of another application and allow for rebranding of user interface. This is accomplished through the use of CSS based themes, which allow for a set of changes to be packaged together in one view. Themes are stored in the repository and are part of the user interface framework within JasperReports Server that provides for separation of structure, presentation, and events.

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


Reports and dashboards can be called via HTTP and embedded into other application using iFrames. There are a few different objectives that can be accomplished using this mechanism which are listed below. This is not an exhaustive list but a starting point for you to get an idea of what’s possible.

  1. Using URL parameters( j_username, j_password) authentication can be skipped allowing for the login screen to be skipped
  2. If referencing a report the type of element to display is included.
  3. The below URL loads up a dashboard with no JasperReports Server UI

The video below covers an example of embedding a report into a web page using iFrames.

Web Services APIs

The SOAP & REST Web Services APIs allows for different components of the JasperReports Server application to be integrated into other applications via Web Service calls by the hosting application. This includes the repository services, scheduling services, domain services and administrative services. Web Services 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 from the WAR file installation

Leveraging Jaspersoft OLAP for Data Analysis

Migrating, Transforming, and Cleaning Your Data

Many people choose to run their reporting and analytics on a database other than their operational data store, such as a data warehouse or secondary data mart. This is why we offer Jaspersoft ETL, a powerful data integration platform for data architects and ETL developers. It provides the ability to extract and transform data from multiple sources and store it into a single database. With hundreds of components and connectors, Jaspersoft ETL provides the ability to pull data from almost any database, file format, or Big Data source and transform and load it into an integrated database for reporting and analytical purposes.

See the video below for an introduction to Jaspersoft ETL.

Additional Resources


Once you have installed JasperReports Server, a full set of standard documentation can be found in the <JasperReports Server Install Root>/docs directory.  You can also find all of our Documentation on-line at our Community Website.


JasperReports Server includes the option to install Sample Data and Reports. In addition, there are several sample reports, web services samples, etc. available in the <jasperreports install server>ireport/demo/samples as well as the <jasperreports install root server>/samples directory. Many of these samples are documented online:

Community Forums and Wiki Documentation

With over 230,000 community members, the Jaspersoft community provides a place to interact with other Jaspersoft developers, administrators, and users. The Jaspersoft community is an invaluable resource for finding answers to common questions as well as those questions related to specific use cases you may be trying to address. Each core project has its own set of forums and wiki documentation. To access the Jaspersoft community site, go to http://community.jaspersoft.com/ .