Grails 5 Installation

After creating the Grails application, place the purchased 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.

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

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

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

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

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/*']
    }
}

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 TomcatServletWebServerFactory and adding the DataSource factory to the Catalina context.

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

The JndiTomcatServletWebServerFactory must be registered as the authoritative ContainerFactory tomcatServletWebServerFactory bean within resources.groovy. In the example resources.groovy file from the quick start repository, the JndiTomcatServletWebServerFactory 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:

implementation 'com.h2database:h2:2.1.214'

Pull Reports™ uses the SLF4J logging framework. Since Grails 5 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 Administrative Guide, logging documentation for more information on SLF4J logging.

When using Pull Reports™ XML Catalog files for catalog configuration, place 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

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

grails:
    agent:
        enabled: false

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

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 5 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 pullreports.properties reference documentation for a description of all required and available properties.

Execute grails run-app to run the application.

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.

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

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

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