Upgrade Notes


Upgrading from 2.5 to 3.0

Pull Reports™ 3.0 requires servlet API 6.0 and Java 11 runtime.

If the installation WAR does not already support at least API 6.0, upgrade the web-app element of web.xml:

<web-app
    xmlns = "https://jakarta.ee/xml/ns/jakartaee"
    xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation = "https://jakarta.ee/xml/ns/jakartaee
      https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
    version = "6.0">

Sitemesh 3 support

For installations which use Sitemesh for page decoration, servlet API 6.0 now requires Sitemesh 3. See Export Decoration for more information.

SLF4J 2

Pull Reports™ 3.0 requires a SLF4J 2 compatible provider. See this SLF4J FAQ for more information.

Upgrading from 2.4 to 2.5

New pullreports-catalog-1.7.0.xsd

Release 2.5 contains a new pullreports-catalog-1.7.0.xsd schema file. Change the xmlns attribute in each Pull Reports™ XML Catalog file to the new value.

<catalog xmlns="http://www.pullreports.com/catalog-1.7.0"...>

Upgrading from 2.3 to 2.4

Pull Reports™ 2.4 requires servlet API 4.0. If the installation WAR does not already support at least API 4.0, upgrade the web-app element of web.xml:

<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
    http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
    version="4.0">

Upgrading from 2.2 to 2.3

Pull Reports™ 2.3 replaces Groovy templating with Freemarker templating within the <placemark_name_template>, <url_template>, <subquery> elements and filters within <canned_queries>. This is a security improvement since Groovy templating provides unconstrained access to static method calls. Please migrate templates to Freemarker compatible syntax.

Additionally, some template syntax and capabilities have changed.

<placemark_name_template>

Column id references must begin with @ and may no longer include the base table path. For example, change a template reference such as ${/base@column} to ${@column}.

<subquery> and <canned_queries> filters

Use methods provided by RequestMethodModels to contextualize urls to the HttpServletRequest instead of the request template variable. For example, ${request.getAttribute('foo')} becomes ${getRequestAttribute('foo')}

<url_template>s

How to reference columns.  Column id references must begin with @ for base table columns and @@ for parent table columns. Prefixing column ids with the table path within a template is no longer supported. For example, change a template reference such as ${/base@column} to ${@column}.

Accessing the HttpServletRequest.  Use methods provided by RequestMethodModels to contextualize urls to the HttpServletRequest instead of the request template variable. For example, ${request.getAttribute('foo')} becomes ${getRequestAttribute('foo')}

No support for static method calls.  Calling Java static methods is no longer supported. Use Freemarker directives instead.

Requiring columns to be non-null.  Use Freemarker if, then, else and the ?? operator to require a column to be non-null instead of !. For example, /example?id=${@!id}, becomes, <#if @id??>/example?id=${@id}</#if>

Upgrading from 2.1 to 2.2

User queries

The installation guide now contains instructions on how to activate user queries.

REST API change

In release 2.2, the cannedQueries parameter of the GET Report Information and GET Catalog Information APIs is now namedQueries.

Upgrading from 2.0 to 2.1

REST API change

Release 2.1 includes a small upgrade to the Pull Reports REST API, sort parameter. If the exported <report>'s defaultSort attribute is specified, a sort parameter with an empty value (e.g. sort=) negates the defaultSort and returns the results unsorted.

This upgrade fixes defect in the Ad Hoc Report Creator in which removing the final sorted column of a <report> with a defaultSort could still return the results sorted by the default value.

Map format dependency upgrades

Release 2.1 upgrades the following Export Report REST API map format JavaScript dependencies.

  • Leaflet upgraded to 1.7

  • Leaflet Markercluster to 1.5

  • JQuery to 3.6

If your configuration decorates the map format result and depends on these dependencies, please verify your decoration is compatible with the upgrade.

Creator dependency upgrades

Release 2.1 upgrades the following Report Creator JavaScript dependencies.

  • angular-translate upgraded to 2.19

Upgrading from 1.7 to 2.0

Maven repository now available over anonymous HTTP

The Pull Reports™ Maven repository is now available at https://repo2.pullreports.com and no longer requires authentication to download the Pull Reports™ JAR.

For example, a 1.7 Gradle repository configuration like this:

repositories {
     ...
     maven {
         url "s3://repo.pullreports.com/maven2"
         credentials(AwsCredentials) {
             accessKey 'YourAccessKey'
             secretKey 'YourSecretKey'
         }
     }
 }

Should be changed to this in 2.0:

repositories {
     ...
     maven {
         url "https://repo2.pullreports.com/maven2"
     }
 }

Upgrading from 1.6 to 1.7

Major breaking changes

GeoJSON, Map, and KML export formats now require primaryKeyColumns

The geojson, map, and kml export formats now require the report's base table to specify the primaryKeyColumns attribute. Each format now returns distinct results based on the primary key columns.

When upgrading from 1.6 to 1.7, it is necessary to specify the primaryKeyColumns attribute on the base table of each report with <geojson> or <kml> configuration or the corresponding export formats will not activate.

GeoJSON, Map, and KML export formats automatically filter non-null geometries

The geojson, map, and kml export formats now return features only if the feature geometry is non-null. This effects the export results when the limit and offset parameters are specified.

For example, in Pull Reports™ 1.6, specifying offset=0 and limit=10 for a REST API request in which the first 10 rows of data contained 8 records with geometry and 2 with null geometry would return a result set of 8 features because the two records with null geometry would be within the limit. In Pull Reports™ 1.7, the same request will contain the first 10 records with non-null features exactly as if the request explicitly filtered to non-null geometries.

Catalog Configuration Java API breaking changes

Table 1. Class deprecations to be removed in the next release
1.61.7
com.pullreports.model.config.ColumnConfiguration.ColumnConfigurationBuildercom.pullreports.model.config.ColumnConfiguration.Builder
com.pullreports.model.config.TableConfiguration.TableConfigurationBuildercom.pullreports.model.config.TableConfiguration.Builder
com.pullreports.model.config.ReportConfiguration.ReportConfigurationBuildercom.pullreports.model.config.ReportConfiguration.Builder
com.pullreports.model.config.ExportConfiguration.ExportConfigurationBuildercom.pullreports.model.config.ExportConfiguration.Builder
com.pullreports.model.config.CannedQueryConfiguration.CannedQueryConfigurationBuildercom.pullreports.model.config.CannedQueryConfiguration.Builder
com.pullreports.model.config.JoinColumnsRelationshipConfiguration.JoinColumnsRelationshipConfigurationBuildercom.pullreports.model.config.JoinColumnsRelationshipConfiguration.Builder
com.pullreports.model.config.JoinTableRelationshipConfiguration.JoinTableRelationshipConfigurationBuildercom.pullreports.model.config.JoinTableRelationshipConfiguration.Builder

Table 2. Class packaging and name changes
1.61.7
com.pullreports.export.request.ColumnsTermcom.pullreports.model.config.ColumnsTerm
com.pullreports.export.request.SortTermcom.pullreports.export.request.Sort
com.pullreports.export.request.SortTermTemplatecom.pullreports.model.config.SortTerm

Table 3. Method name changes
1.61.7
com.pullreports.model.config.CannedQueryConfiguration.CannedQueryConfigurationBuilder#setSortTermTemplatescom.pullreports.model.config.CannedQueryConfiguration.Builder#setSortTerms
com.pullreports.model.CannedQuery#getSortTermscom.pullreports.model.CannedQuery#getSorts

Table 4. Method signature changes
1.61.7
com.pullreports.model.config.PreFilter(ColumnId,Operator,List<Object>)com.pullreports.model.config.PreFilter(ColumnId,Operator,List<FilterValue>)

Table 5. Capability migrations: parsing a sort parameter
1.61.7
com.pullreports.export.request.SortTerm#fromString(String)com.pullreports.export.request.parsers.SortParameterPreParser#parseSingle(String)

Table 6. Capability migrations: parsing a columns parameter
1.61.7
com.pullreports.export.request.ColumnsTerm#fromString(String)com.pullreports.export.request.parsers.ColumnsParameterPreParser#parse(String)

REST API changes

  • The meta.sort and meta.subqueries properties of the REST API json format are now the empty Array instead of undefined if they have no value.

REST-API dependency upgrades

The following Java dependencies are upgraded.

  • org.codehaus.groovy:groovy-all to 2.5.14

Upgrading from 1.5 to 1.6

Optional upgrade steps

Activating tree exports

Activate the new jsontree and htmltree export formats by specifying the new primaryKeyColumns attribute for all report tables which have at least one relationship descendant of cardinality many.

Tree formats are disabled until activated.

creator.url configuration property

Activate the new "Creator" navigation link from HTML export formats back to the Report Creator by specifying the creator.url configuration property.

Major breaking changes

New pullreports-catalog-1.6.1.xsd

Release 1.6 contains a new pullreports-catalog-1.6.1.xsd schema file. Change the xmlns attribute in each Pull Reports™ XML Catalog file to the new value.

<catalog xmlns="http://www.pullreports.com/catalog-1.6.1"...>

Column and relationship ids must be unique

In release 1.6, <column> and <relationship> id values within the same <table> or <table_ref> must now be unique.

This rule is required by the new jsontree export format which returns column and relationship ids as properties of the JSON Object representation of the table.

REST-API dependency upgrades

The following Java dependencies are upgraded.

  • org.codehaus.groovy:groovy-all to 2.4.19

Upgrading from 1.4 to 1.5

Version 1.5 has no breaking changes nor dependencies upgrades.

Upgrading from 1.3 to 1.4

Major breaking changes

New pullreports-catalog-1.6.0.xsd

Release 1.4 contains a new pullreports-catalog-1.6.0.xsd schema file. Change the xmlns attribute in each Pull Reports™ XML Catalog file to the new value.

<catalog xmlns="http://www.pullreports.com/catalog-1.6.0"...>

Report Creator initialization change

Release 1.4 simplifies and improves the JavaScript initialization of the Report Creator. However, these improvements mean that Pull Reports™ 1.3 JavaScript initialization code will not work in 1.4. See the Report Creator Installation for instructions on how to correctly initialize the Pull Reports™ 1.4 creator.

Removal of catalogId and reportId initialization properties

Release 1.4 removes the catalogId and reportId Report Creator initialization properties. In order to open the creator to a specific <report>, see the section called “Linking to a Component” or use the new adHocCreatorParams initialization property.

creator dependency upgrades

Release 1.4 upgrades the following Report Creator JavaScript dependencies.

  • JQuery upgraded to 3.3

REST-API dependency upgrades

The following Java dependencies are upgraded.

  • org.codehaus.groovy:groovy-all to 2.4.16

Upgrading from 1.2 to 1.3

Major breaking changes

New pullreports-catalog-1.5.0.xsd

Release 1.3 contains a new pullreports-catalog-1.5.0.xsd schema file. Change the xmlns attribute in each Pull Reports™ XML Catalog file to the new value.

<catalog xmlns="http://www.pullreports.com/catalog-1.5.0"...>

Removed GET Global Label Value List REST API endpoint

Release 1.3 removes the GET Global Label Value List REST API endpoint because it was redundant with the GET Label Value List endpoint. This removal is unlikely to effect REST API users since the common use of the GET Global Label Value List REST API endpoint was within the Pull Reports™ Report Creator.

<subquery> provider attribute

The <subquery> factory attribute is renamed to provider. Additionally, the referenced class must implement SubqueryProvider.

Minor breaking changes

<export_config> defaultSort does not permit table path

The <export_config> element's defaultSort attribute no longer permits the base table path within the sort term list. Only @ prefixed column ids are valid.

Replace a defaultSort value defined like this:

<export_config defaultSort="/tablePath@columnId"/>

With the @ prefixed column id:

<export_config defaultSort="@columnId"/>

New <label_value_query_default> element

The <label_value_query> element now requires a SQL query within the element body. Use the new <label_value_query_default> element to configure a <column>'s label value list to contain the distinct set of values within the column.

Replace a <label_value_query> defined like this:

<column id="foo" name="bar" displayName="fooBar">
    <label_value_list>
        <label_value_query/>
    </label_value_list>
</column>

With a <label_value_query_default> like this:

<column id="foo" name="bar" displayName="fooBar">
    <label_value_list>
        <label_value_query_default/>
    </label_value_list>
</column>

GET Report Information API labelValueList property change

The GET Report Information API's column.labelValueList property is now a boolean instead of a string or a boolean.

This change relates to the removal of the GET Global Label Value List REST API endpoint and is unlikely to effect users.

Non-breaking changes

<relationship> cardinality default value

The <relationship> element's cardinality attribute now has a default value of many.

<relationship>s configured like this:

<relationship cardinality="many">...</relationship>

may now be configured like this:

<relationship>...</relationship>

REST-API dependency upgrades

The following Java dependencies are upgraded.

  • org.codehaus.groovy:groovy-all to 2.4.15