Chapter 3. Installation

After obtaining the Pull Reports™ software and license and reading the license agreement, follow these steps to install Pull Reports™.

3.1. Server Requirements

Java Virtual Machine

A Java 8 JVM.

Servlet Container

A Servlet Container which implements Servlet Specification 3.0 or higher (e.g. Tomcat 7).

Relational Database

A relational database which supports 2008 ANSI SQL.

Certified databases:

  • H2 1.4

  • MySQL 5.7

  • Oracle 12.1

  • PostgreSQL 9.4, 9.6

  • SQLServer 2016, 2017

Database compatibility

The most common database variability effecting Pull Reports™ is the implementation of limit and offset within SQL written by the Export Report REST API. By default, Pull Reports™ uses the ANSI standard offset [offset] rows fetch first [limit] rows only syntax but also implements pluggable SQL dialects for databases which do not support this syntax.

3.2. Software and Dependencies

The Pull Reports™ software is available for download after purchase. The downloaded file is named pullreports-dist-x.y.z.zip where x, y, and z correspond to the product major, minor, and patch version numbers respectively. Unzip the file to access the following files and directories:

Table 3.1. pullreports-x.y.z.zip contents
File / DirectoryDescription
PullReportsEULA.pdfThe Pull Reports end user license agreement. Please read carefully.
dist/pullreports-x.y.z.jarThe Pull Reports software. See following table for a component description.
dist/pullreports-catalog-1.4.0.xsdThe XML schema definition for Pull Reports™ XML Catalog files. Use to validate Pull ReportsXML Catalog files.
dist/pom.xmlThe Maven POM file of required Pull Reports™ runtime dependencies. These dependencies are also found in the lib directory.
libThe transitive, runtime dependency JARs for Pull Reports™. These same dependencies are listed within dist/pom.xml and are included in the distribution as a convenience.

Table 3.2. pullreports-x.y.z.jar components
ComponentDescription
com.pullreports.web.PullReportsContextListenerServletContextListener which reads Pull Reportsproperties and parses XML Catalog files.
com.pullreports.web.PullReportsServletHttpServlet which serves all Pull Reports™ resources. Mapped to URL pattern /pullreports/*.
  • pullreports.min.js

  • pullreports.js

  • pullreports.min.css

  • pullreports.css

CSS and JavaScript assets to support the Pull Reports™ Ad Hoc Report Creator. Available at the following URL pattern relative to the context path of the WAR:

/[context]/assets/[filename]

For instance:

/[context]/assets/pullreports.min.js


3.2.1. Dependency Management

Pull Reports™ recommends using dependency management software when installing Pull Reports™ into an existing JEE web application. Dependency management software such as Gradle, IVY, or Maven ensures that JARs and their transitive dependencies are automatically resolved, downloaded, and installed.

When using dependency management software with Pull Reports™, there are three general techniques for hosting JAR files: an enterprise repository, a local repository, and project-local JARs. The following examples use Gradle when discussing these three techniques in the context of Pull Reports™ installation. See the respective documentation for achieving similar results with Maven and IVY.

3.2.1.1. Enterprise repository

An enterprise repository is a common file or network location into which common code artifacts are installed. Nexus and Artifactory are popular open source repository management software, but a common network drive available to multiple team members may also suffice.

When publishing the Pull Reports™ JAR to an enterprise repository, include the Pull Reports™ POM descriptor in the publication so that dependency management software will resolve Pull Reports™ transitive, runtime dependencies. Most tools will automatically detect the POM file within the JAR's META-INF directory, but the POM is also available in the dist directory of the Pull Reports™ media. Nexus and Artifactory provide web interfaces and services for publishing artifacts; the Maven install:install-file plugin assists publication to a file based repository.

Once the Pull Reports™ JAR is published to an enterprise repository, include the Pull Reports™ JAR as a runtime dependency so as to download and install Pull Reports™ and all of its transitive, runtime dependencies. The following build.gradle example includes a URL based maven repository configuration and the Pull Reports™ dependency declaration.

repositories {
    maven {
        url "https://repo.myorganization.org/artifactory"
    }
}
dependencies {
    runtime 'com.pullreports:pullreports:1.2.1'
}

See the Gradle dependency management documentation for more repository configuration options.

3.2.1.2. Local repository

A local file repository is identical to an enterprise file repository except that it is scoped to one computer - usually within a user's home directory, (~). A local file repository can support local development but is not easily shared with other team members.

To manually publish the Pull Reports™ JAR to a local repository, place the pullreports-x.y.z.jar and pom.xml files from the Pull Reports™ media within ~/.m2/repository/com/pullreports/x.y.z/ where x.y.z is the version of the Pull Reports™ software. When copying pom.xml, rename it to pullreports-x.y.z.pom to comply with Maven repository guidelines.

For example, if publishing Pull Reports™ version 1.2.1, the local repository should be:

$ ls -1 ~/.m2/repository/com/pullreports/pullreports/1.2.1
pullreports-1.2.1.jar
pullreports-1.2.1.pom

Once the Pull Reports™ JAR is published to a local repository, include the Pull Reports™ JAR as a runtime dependency so as to download and install Pull Reports™ and all of its transitive, runtime dependencies. The following build.gradle demonstrates an example local repository configuration and the Pull Reports™ dependency declaration.

repositories {
    mavenLocal()
}
dependencies {
    runtime 'com.pullreports:pullreports:1.2.1'
}

3.2.1.3. Project-local JARs

When an enterprise or local repository is not available, the Pull Reports™ JAR and all of its transitive, runtime dependencies may be installed within an application's project directly. When using project-local dependency management, know that the project must manage JAR version conflicts (e.g. two versions of the same JAR) and transitive, runtime dependencies itself. Additionally, since transitive, runtime JAR dependencies may change between Pull Reports™ versions, review each JAR within the Pull Reports™ media's lib directory with each Pull Reports™ upgrade.

To establish project-local dependency management, copy the Pull Reports™ JAR and all transitive, runtime dependency JARs into a project directory such as lib. The application build must then include these JARs within the application's classpath. The following build.gradle demonstrates a project-local Pull Reports™ dependency assuming the Pull Reports™ JAR and all transitive, runtime dependency JARs are within the project's lib directory.

dependencies {
    runtime fileTree(dir: 'lib', include: '*.jar')
}

3.3. Basic WAR Installation

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.

In order to run the example, contact the Pull Reports™ sales team to receive the Pull Reports™ software and an evaluation license.

3.3.1. License

Place the 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.

See the administration chapter for more information.

3.3.2. 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 dependency management for recommendations on managing Pull Reports™ JARs within an application build. If manually creating a WAR, place the Pull Reports™ JAR and all transitive, runtime dependency JARs within the WAR's WEB-INF/lib directory.

Note

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™.

3.3.3. pullreports.properties

Create a text file called pullreports.properties 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 will be specified during the XML Catalog files step below, and the later must be the default JNDI location of a javax.sql.DataSource used for report export.

Note

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.

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

3.3.4. 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 logging documentation for more information on SLF4J logging.

3.3.4.1. 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.

WEB-INF/lib/slf4j-log4j12-1.7.22.jar
WEB-INF/lib/log4j-1.2.17.jar

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

WEB-INF/classes/log4j.properties
Example 3.1. log4j.properties file

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

log4j.com.pullreports=error, pullreports

log4j.appender.pullreports=org.apache.log4j.RollingFileAppender
log4j.appender.pullreports.File=${catalina.home}/logs/pullreports.log
log4j.appender.pullreports.MaxFileSize=100KB
log4j.appender.pullreports.MaxBackupIndex=1
log4j.appender.pullreports.layout=org.apache.log4j.PatternLayout
log4j.appender.pullreports.layout.ConversionPattern=%p %t %c - %m%n

# Configure a separate log file for logging SQL queries
log4j.com.pullreports.SQL=debug, pullreports-sql
log4j.appender.pullreports-sql=org.apache.log4j.RollingFileAppender
log4j.appender.pullreports-sql.File=${catalina.home}/logs/pullreports-query.log
log4j.appender.pullreports-sql.MaxFileSize=100KB
log4j.appender.pullreports-sql.MaxBackupIndex=1
log4j.appender.pullreports-sql.layout=org.apache.log4j.PatternLayout
log4j.appender.pullreports-sql.layout.ConversionPattern=%p %t %c - %m%n

3.3.5. XML Catalog files

Note

See the XML Catalog Files chapter for instructions on how to create Pull Reports™ XML Catalog files.

Place the Pull Reports™ XML Catalog files within the WAR's classes directory and reference them via the pullreports.properties catalogs property.

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

WEB-INF/classes/financial-report-catalog.xml
WEB-INF/classes/client-report-catalog.xml

The catalogs property value should be:

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

Note

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

3.3.6. Configure Security (Optional)

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

3.3.7. Run the application

Install the WAR file containing the Pull Reports™ JARs, license file, properties file, and Pull Reports™ XML Catalog files 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]

3.3.8. Verify Pull Reports™ REST API

The PullReportsServlet exposes a REST API to catalog and report resources within the installed Pull Reports™ XML Catalog files. Use the the API to verify correct installation.

3.3.8.1. List catalogs

http://localhost:8080/[context]/pullreports/catalog.json

Returns a simple JSON representation of all <catalog>s and their child <report>s. The Pull Reports™ Ad Hoc Report Creator uses this URL to display the Switch report drop down menu. Request it directly within a browser to verify the Pull Reports™ installation.

Learn more about the catalog REST API.

3.3.8.2. Export report

http://localhost:8080/[context]/pullreports/catalog/[catalog_id]/report/[report_id]/export?limit=1

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 Pull Reports™ XML Catalog files contain 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 export.report.maxResults. 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.

3.3.9. Embed the Pull Reports™ Ad Hoc Report Creator

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

To install the Ad Hoc 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.

Note

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

3.4. Spring Boot Installation

Follow these instructions to install Pull Reports™ within an existing Spring Boot application. These instructions assume the reader is familiar with Spring Boot and has already created a Spring Boot application. Spring Boot has an excellent quick start tutorial to help those unfamiliar with Spring Boot.

Spring Boot 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 spring-boot sub-project for information specific to Spring Boot Pull Reports™ installation.

In order to run the example, contact the Pull Reports™ sales team to receive the Pull Reports™ software and an evaluation license.

The following instructions were created with Spring Boot 1.5.

3.4.1. License

After creating the Spring Boot application, place the pullreports.license file within the src/main/resources directory. This file is read from the root of the JVM classpath at WAR initialization and validates the license term and number of allowable <report>s.

See the administration chapter for more information.

3.4.2. Library dependencies

Spring Boot uses either Gradle or Maven dependency management to resolve application JAR dependencies. See dependency management for recommendations on managing Pull Reports™ JARs within a Spring Boot project.

Note

See an example of how to use Gradle dependency management in the Pull Reports quick start repository's build.gradle

3.4.3. Register Web Components

Add the @ServletComponentScan(basePackages="com.pullreports") annotation to the Spring Boot application class in order to automatically register the com.pullreports.web.PullReportsContextListener and com.pullreports.web.PullReportsServlet on application start up.

Note

See an example in the Pull Reports quick start repository's Application.java

3.4.4. Register JNDI DataSource

Pull Reports™ retrieves javax.sql.DataSources from JNDI. In a production deployment environment, the Servlet Container will typically provide the JNDI DataSource to a running Spring Boot application. When running Spring Boot with an embedded Servlet Container in development or in production via a runnable JAR, create the JNDI DataSource by overriding the EmbeddedServletContainerFactory bean and providing the necessary JNDI configuration.

The Pull Reports™ quick start repository has an example JndiTomcatEmbeddedServletContainerFactory which establishes a JNDI javax.sql.DataSource backed by an H2 database connection.

Note that creating a JNDI javax.sql.DataSource requires registering the database JDBC driver as a compile time dependency. For instance, if using Gradle and H2, add the H2 JDBC driver as a dependency within build.gradle:

dependencies{
    compile 'com.h2database:h2:1.4.195'
}

3.4.5. Logging

Pull Reports™ uses the SLF4J logging framework. Since the Spring Boot spring-boot-starter-web plugin transitively includes SLF4J, see the Spring Boot logging documentation to configure Pull Reports™ loggers in a Spring Boot application.

For example, add the following property to application.properties to log all Pull Reports™ SQL statements:

// Example: setting the Pull Reports SQL logger to DEBUG
logging.level.com.pullreports.SQL=DEBUG

See the logging documentation for more information on SLF4J logging.

3.4.6. Hot Reloading in Development

Because Pull Reports™ caches the XML Catalog file configuration in the JVM memory, changes to XML Catalog files are not hot deployed to the running Spring Boot application during development. To enable hot reloading, explicitly add the Pull Reports JAR to the spring-boot-devtools restart classloader via the following spring-devtools.properties property:

restart.include.pullreports=/pullreports-[\\w\.]+\.jar

Note

See an example in the Pull Reports quick start repository's spring-devtools.properties

3.4.7. XML Catalog files

Note

See the XML Catalog Files chapter for instructions on how to create Pull Reports™ XML Catalog files.

Place Pull Reports™ XML Catalog files within the src/main/resources directory and reference them in the next step via the pullreports.properties catalogs property.

For example, for Pull Reports™ XML Catalog files installed here:

src/main/resources/financial-report-catalog.xml
src/main/resources/client-report-catalog.xml

The catalogs property value should be:

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

Note

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

3.4.8. pullreports.properties

Create a text file called pullreports.properties within the src/main/resources directory. This file contains required configuration information related to database connectivity and report definition.

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 pullreports.properties file would be:

catalogs=classpath:financial-report-catalog.xml classpath:client-report-catalog.xml
jndiDataSource=java:comp/env/jdbc/example-datasource

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

Note

See an example in the Pull Reports quick start repository's pullreports.properties

3.4.9. Run the application

Execute gradle bootRun to run the application.

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

3.4.10. Verify Pull Reports™ REST API

The PullReportsServlet exposes a REST API to catalog and report resources within the installed Pull Reports™ XML Catalog files. Use the the API to verify correct installation.

3.4.10.1. List catalogs

http://localhost:8080/[context]/pullreports/catalog.json

Returns a simple JSON representation of all <catalog>s and their child <report>s. The Pull Reports™ Ad Hoc Report Creator uses this URL to display the Switch report drop down menu. Request it directly within a browser to verify the Pull Reports™ installation.

Learn more about the catalog REST API.

3.4.10.2. Export report

http://localhost:8080/[context]/pullreports/catalog/[catalog_id]/report/[report_id]/export?limit=1

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 Pull Reports™ XML Catalog files contain 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 export.report.maxResults. 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.

3.4.11. Embed the Pull Reports™ Ad Hoc Report Creator

Follow these directions to install the Ad Hoc Report Creator into the Spring Boot application. Note that these directions assume the use of Freemarker templating via the spring-boot-starter-freemarker plugin:

  1. Create a Freemarker template within the src/main/resources/templates directory (e.g. ad-hoc-creator.ftl)

  2. Add a Spring controller mapping for the template:

    @GetMapping("/adHocCreator")
    public String adHocCreator() {
        return "ad-hoc-creator";
    }
  3. Follow the Ad Hoc Report Creator installation instructions to install the basic HTML template into ad-hoc-creator.ftl.

  4. After installation, the Ad Hoc Report Creator will be available at http://localhost:8080/[context]/adHocCreator.

Note

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

3.5. Grails 3 Installation

Follow these instructions to install Pull Reports™ within a new or existing Grails 3 application. These instructions were created with Grails 3.3.

Grails 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 grails sub-project for information specific to Grails Pull Reports™ installation.

In order to run the example, contact the Pull Reports™ sales team to receive the Pull Reports™ software and an evaluation license.

3.5.1. License

After creating the Grails application, place the pullreports.license file within the src/main/resources directory. This file is read at WAR initialization and validates the license term and number of allowable <report>s.

See the administration chapter for more information.

3.5.2. Library dependencies

Grails 3 uses Gradle to resolve JAR dependencies. See dependency management for recommendations on managing Pull Reports™ JARs within a Grails project.

Read about additional dependency management resolution strategies within the Gradle user guide.

Note

See an example of how to use Gradle dependency management in the Pull Reports quick start repository's build-ext.gradle

3.5.3. Register JEE Beans

Register the PullReportsContextListener and PullReportsServlet as Spring beans within the grails-app/conf/spring/resources.groovy file.

Example 3.2. JEE listener and servlet components within resources.groovy
import org.springframework.boot.web.servlet.ServletRegistrationBean
import org.springframework.boot.web.servlet.ServletListenerRegistrationBean
import com.pullreports.web.PullReportsServlet
import com.pullreports.web.PullReportsContextListener

beans = {

    pullreportsListener(ServletListenerRegistrationBean) { bean ->
         listener = new PullReportsContextListener()
    }

    pullreportsServlet(ServletRegistrationBean) { bean ->
         servlet = new PullReportsServlet()
         urlMappings = ['/pullreports/*']
    }
}

Note

See an example in the Pull Reports quick start repository's resources.groovy

3.5.4. Register JNDI DataSource

Pull Reports™ retrieves javax.sql.DataSources from JNDI. In a production deployment environment, the Servlet Container will typically provide the JNDI DataSource. In Grails development, the application runs within an embedded Tomcat container, so the JNDI javax.sql.DataSource must be created by extending TomcatEmbeddedServletContainerFactory and adding the DataSource factory to the Catalina context.

The Pull Reports™ quick start repository has an example JndiTomcatEmbeddedServletContainerFactory bean which establishes a JNDI javax.sql.DataSource backed by an H2 database connection.

The JndiTomcatEmbeddedServletContainerFactory must be registered as the authoritative ContainerFactory tomcatEmbeddedServletContainerFactory bean within resources.groovy. In the example resources.groovy file from the quick start repository, the JndiTomcatEmbeddedServletContainerFactory implementation is only used during development. When the application is deployed in a non-development environment, the Servlet Container must provide the JNDI javax.sql.DataSource.

Note that creating a JNDI javax.sql.DataSource requires registering the database JDBC driver as a compile time dependency. For instance, if using H2, add the H2 JDBC driver as a dependency within build.gradle:

compile 'com.h2database:h2:1.4.195'

3.5.5. Logging

Pull Reports™ uses the SLF4J logging framework. Since Grails 3 natively supports SLF4J logging, activate Pull Reports™ logging by adding appropriate loggers to grails-app/conf/logback.groovy.

// Example: setting all Pull Report loggers to log at the ERROR level.
logger("com.pullreports", ERROR)
// Example: setting the Pull Reports SQL logger to DEBUG
logger("com.pullreports.SQL", DEBUG)

See the logging documentation for more information on SLF4J logging.

3.5.6. Hot Reloading in Development

Grails uses spring-loaded to hot deploy changes to class files during development when run via the run-app command. Because Pull Reports™ deployed within a Servlet Container caches Pull Reports™ XML Catalog file configuration in the JVM memory, changes to Pull Reports™ XML Catalog files are not refreshed by spring-loaded.

In order to hot reload changes to Pull Reports™ XML Catalog files during Grails development, switch Grails to use spring-boot-devtools for hot reloading and include the pullreports-x.y.z.jar in the refresh classloader.

To do this, first declare a dependency on spring-boot-devtools within build.gradle:

dependencies {
    ...
    runtime 'org.springframework.boot:spring-boot-devtools'
    ...
}

Second, turn off spring-loaded in grails-app/conf/application-development.yml

grails:
    agent:
        enabled: false

Finally, include the pullreports JAR within the restart classloader via the following configuration in src/main/resources/META-INF/spring-devtools.properties:

restart.include.pullreports=/pullreports-[\\w\.]+\.jar

3.5.7. XML Catalog files

Note

See the XML Catalog Files chapter for instructions on how to create Pull Reports™ XML Catalog files.

Place Pull Reports™ XML Catalog files within the src/main/resources directory. Reference them in the next step via the pullreports.properties catalogs property.

For example, for Pull Reports™ XML Catalog files installed here:

src/main/resources/financial-report-catalog.xml
src/main/resources/client-report-catalog.xml

The catalogs property value should be:

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

Note

See an example in the Pull Reports quick start repository's petstore.xml and pullreports.properties

3.5.8. pullreports.properties

Create a text file called pullreports.properties within the src/main/resources directory. This file contains required configuration information related to database connectivity and report definition.

Requirement:  Grails 3 installations must set the static.resource.prefix property value to /static.

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 pullreports.properties file would be:

catalogs=classpath:financial-report-catalog.xml classpath:client-report-catalog.xml
jndiDataSource=java:comp/env/jdbc/example-datasource
static.resource.prefix=/static

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

Note

See an example in the Pull Reports quick start repository's pullreports.properties

3.5.9. Run the application

Execute grails run-app to run the application.

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

3.5.10. Verify Pull Reports™ REST API

The PullReportsServlet exposes a REST API to catalog and report resources within the installed Pull Reports™ XML Catalog files. Use the the API to verify correct installation.

3.5.10.1. List catalogs

http://localhost:8080/[context]/pullreports/catalog.json

Returns a simple JSON representation of all <catalog>s and their child <report>s. The Pull Reports™ Ad Hoc Report Creator uses this URL to display the Switch report drop down menu. Request it directly within a browser to verify the Pull Reports™ installation.

Learn more about the catalog REST API.

3.5.10.2. Export report

http://localhost:8080/[context]/pullreports/catalog/[catalog_id]/report/[report_id]/export?limit=1

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 Pull Reports™ XML Catalog files contain 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 export.report.maxResults. 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.

3.5.11. Embed the Pull Reports™ Ad Hoc Report Creator

To install the Ad Hoc Report Creator into the Grails application, follow these steps:

  1. Create a GSP page within the grails-app/views directory (e.g. ./grails-app/views/ad-hoc-creator.gsp)

  2. Add a mapping for the new view to UrlMappings

    "/ad-hoc-creator"(view:"/ad-hoc-creator")

  3. Follow the Ad Hoc Report Creator installation instructions to install the basic HTML template into ad-hoc-creator.gsp.

    Important note for Grails 3

    Grails 3 prefixes all static content from JAR META-INF/resources directories with the /static URL path. For this reason, prefix all paths to Pull Reports.css and .js files with /static.

  4. After installation, the Ad Hoc Report Creator will be available at http://localhost:8080/[context]/ad-hoc-creator.

Note

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