Basic WAR Installation


Learn how to install Pull Reports™ Ad Hoc reporting and data service software into a JEE web application.

Follow these instructions to install Pull Reports™ within a new or existing Java Web Application Archive (WAR) file. These instructions describe installation into a "classic" JEE directory structure without the use of additional web or build frameworks.

JEE Quick Start Example

Pull Reports™ has a quick start example repository publicly available on GitHub to aid understanding of the various installation components. See the jee sub-project for information specific to JEE Pull Reports™ installation.

Install License file for Standard Edition

Place the purchased pullreports.license at the root of the WAR's classpath such as within the WEB-INF/classes directory. This file is read at WAR initialization and validates the license term and number of allowable <report>s.

Community Edition deployments do not require a license file. See the Administrative Guide, About the License documentation for more information.

Install Library Dependencies

The pullreports-x.y.z.jar plus all transitive, runtime dependency JARs from the Pull Reports™ media must be available on the WAR's classpath. See the dependency management documentation for recommendations on managing Pull Reports™ JARs within an application build.


The WAR's web.xml must not be attributed with:

<web-app metadata-complete="true">

This will disable scanning for classes annotated with Servlet Specification 3.0 web component annotations such as @WebServlet and thus disable Pull Reports™.

Configure Logging

Pull Reports™ uses the SLF4J logging framework. Since Pull Reports™ does not come with an implementation of the SLF4J API, provide a SLF4J implementation in order to activate logging.

See the Administrative Guide logging documentation for more information on SLF4J logging.

SLF4J-Log4j example

Log4j is a popular implementation of SLF4J. In order to use a Log4j as the SLF4J implementation, put the slf4j-log4j12 binding and log4j implementation Jars into the WAR's WEB-INF/lib directory.


Then put a text file named file in WEB-INF/classes

Example 1. file

This example assumes the WAR s deployed within the Tomcat Servlet Container with the catalina.home java.lang.System property set., pullreports

log4j.appender.pullreports.layout.ConversionPattern=%p %t %c - %m%n

# Configure a separate log file for logging SQL queries, pullreports-sql
log4j.appender.pullreports-sql.layout.ConversionPattern=%p %t %c - %m%n

Catalog Configuration


See the Catalog Configuration Introduction documentation for information on how to create Pull Reports™ XML Catalog files or usage of the Catalog Configuration Java API.

When using Pull Reports™ XML Catalog files for catalog configuration, place the XML Catalog files within the WAR's classes directory and reference them via the catalogs property.

For example, for XML Catalog files installed within this WAR path:


The catalogs property value should be:

catalogs=classpath:financial-report-catalog.xml \


See an example Pull Reports™ XML Catalog file setup in the Pull Reports quick start repository's petstore.xml and


Create a text file named at the root of the WAR's classpath such as within the WEB-INF/classes directory. This properties file must contain at least two required properties, catalogs and jndiDataSource. The former lists the catalog configuration values specified during the Catalog Configuration step below. The latter provides the default JNDI location of a javax.sql.DataSource used for report export.

Taking the XML Catalog file location from the previous step and a default JNDI javax.sql.DataSource location of java:comp/env/jdbc/example-datasource, the file would be:

catalogs=classpath:financial-report-catalog.xml classpath:client-report-catalog.xml

See the reference documentation for a description of all required and available properties.


Creating a JNDI javax.sql.DataSource is the responsibility of the Servlet Container into which the Pull Reports™ WAR is deployed. See the documentation for your Servlet Container for help configuring JNDI. For example, if using Tomcat, see the JNDI DataSource How-To documentation.

Furthermore, the Pull Reports quick start repository's build.gradle and context.xml demonstrate JNDI DataSource configuration within a Gretty managed Tomcat.

Configure Security (Optional)

See the Security documentation chapter for instructions on how to configure security for all or individual Pull Reports™.

Run the Application

Install the WAR file containing the Pull Reports™ JARs, license file, properties file, and catalog configuration into the Servlet Container of choice. Exact installation instructions vary between Servlet Container implementations. Please consult the documentation of the chosen container for more information.

The following instructions assume the WAR is available at the URL http://localhost:8080/[context]


The PullReportsServlet exposes a REST API to catalog and report resources within the installed catalog configuration. Use the API to verify correct installation.

Verify: List catalogs

Open a browser and paste the following URL into the location bar:


This URL returns a simple JSON representation of all <catalog>s and their child <report>s. The Pull Reports™ Report Creator uses this endpoint to display report metadata within the Report Repository. Request it directly within a browser to verify the Pull Reports™ installation.

Learn more about the catalog REST API.

Verify: Export report

Open a browser and paste the following URL into the location bar:


This URL invokes the Export Report REST API for the report identified by [catalog_id] and [report_id]. Requesting this URL within a web browser is an easy way to verify that the configured DataSource works and that the catalog configuration contains valid database table and column names.

What does limit=1do?

The limit=1 parameter restricts the returned results to just 1 row. Without it, the default behavior of the export API is to return every row of the report's base table up to the configured By default, the Export Report REST API returns JSON output. Change this by appending another format type (e.g. &format=html) to the query string.

Embed the Report Creator

See the Report Creator chapter for instructions on how to install the creator into a website.

To install the Report Creator into a HTML page within the WAR into which you installed the Pull Reports™ JAR, create an HTML page within the WAR (e.g. ./creator.html) and follow the installation instructions.


See an example creator installation in the Pull Reports quick start repository's ad-hoc-creator.jsp