Learn the catalog configuration elements for Pull Reports™ ad hoc report and data service configuration.
This guide contains detailed information about Pull Reports™ catalog configuration elements.
To browse the guide, read this introduction and then start with the <catalog> root element. Other key elements
include:
To follow a step-by-step catalog configuration tutorial, see Tutorial 1: Creating an Ad Hoc Report on one Database Table. To download a working Pull Reports™ application, see the quick start example GitHub project.
Every Pull Report configuration is contained within one catalog configuration. A catalog groups one to many reports into a common resource path within the Pull Reports REST API and allows multiple reports to share common security, JDBC DataSource, or logging configuration.
A catalog may be defined as a Pull Reports™ XML Catalog file or as a Java class implementing the
CatalogConfigurationFactory Catalog Configuration API interface.
For simple Pull Reports™ installations, configuration via XML is typically sufficient.
However, if you need to dynamically create configuration from an external source
such as a database, would like to reuse configuration between Pull Reports™ installations,
or you prefer programmatic, Java configuration over declarative, XML configuration,
use the Java API.
This guide defines both the correct usage of the Pull Reports™ XML Catalog file elements and contains links to the Catalog Configuration Java API Javadoc for those elements with Java analogs.
Specify the location of all XML Catalog files or CatalogConfigurationFactory's
via the catalogs initialization property. Pull Reports™ reads this
property on application start up and creates report configuration up to the
license limit.
An XML Catalog file defines one <catalog> and
one to many <report>s within that catalog. Each report must have exactly one, base <table>,
and the base <table> must have at least one <column>. <relationship> elements
may be added to the base <table> to join additional <table>s to the report's join tree.
Here is the most minimal XML Catalog file possible. It defines one catalog, report, table, and column
element.
This catalog configuration permits the export of the one database column, schema_name.table_name.column_name,
from the Export Report REST API.
<?xml version="1.0" encoding="UTF-8"?> <catalog xmlns="http://www.pullreports.com/catalog-1.7.0" id="my-catalog" name="My Catalog" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.pullreports.com/catalog-1.7.0 https://www.pullreports.com/docs/xsd/pullreports-catalog-1.7.0.xsd"> <report id="my-report" name="My Report"> <table id="my-table" displayName="My Table" name="schema_name.table_name"> <column id="my-column" name="column_name" displayName="My Column"/> </table> </report> </catalog>
To use the Catalog Configuration Java API, create a Java class which implements the
CatalogConfigurationFactory
interface and returns a
CatalogConfiguration
with at least one
ReportConfiguration.
Java classes within the Catalog Configuration Java API are directly analogous to similarly named elements within the
XML catalog configuration schema. To aid in understanding the relationship between the two configuration technologies,
the API Javadocs and this XML schema documentation contain hyperlinks between analogous Java classes and XML elements.
Here is a CatalogConfigurationFactory which returns the same minimal catalog configuration
as the XML Catalog file from the previous section.
package com.pullreports.examples.schema;
import com.pullreports.model.CatalogId;
import com.pullreports.model.ColumnId;
import com.pullreports.model.ReportId;
import com.pullreports.model.TableId;
import com.pullreports.model.config.CatalogConfiguration;
import com.pullreports.model.config.CatalogConfigurationFactory;
import com.pullreports.model.config.ColumnConfiguration;
import com.pullreports.model.config.ReportConfiguration;
import com.pullreports.model.config.TableConfiguration;
import jakarta.servlet.ServletContext;
import java.util.Collections;
import java.util.List;
public class MinimalCatalogConfigurationFactory implements CatalogConfigurationFactory {
@Override
public CatalogConfiguration makeCatalog(ServletContext servletContext) {
ColumnConfiguration myColumnConfiguration = new ColumnConfiguration.Builder(
new ColumnId("my-column"),"column_name").setDisplayName("Column Name").build();
List<ColumnConfiguration> columnConfigurations = Collections.singletonList(myColumnConfiguration);
TableConfiguration myTableConfiguration = new TableConfiguration.Builder(
new TableId("my-table"),"My Table",columnConfigurations)
.setName("schema_name.table_name").build();
ReportConfiguration myReportConfiguration = new ReportConfiguration.Builder(
new ReportId("my-report"),"My Report",myTableConfiguration).build();
List<ReportConfiguration> reportConfigurations = Collections.singletonList(myReportConfiguration);
return new CatalogConfiguration(new CatalogId("my-catalog"),"My Catalog",reportConfigurations);
}
}
A table resource path is a reference to a specific <table> or <table_ref>
within a report's join tree. Table resource paths are forward
slash (/) separated lists of <table> or <table_ref> ids
starting from the base table of the <report>. For instance, the path:
/student/parent/employer
refers to the employer table joined as a child <relationship> to the
parent table joined as a child <relationship> to the base student table.
Table resource paths are used within the Export Report REST API
columns parameter and <join_column> referencedTablePath
attribute and form a component of column resource paths.
Since the base table id is always the
first path element of a table resource path, it may be omitted from the path for brevity. For instance,
the previous path example may also be written as:
/parent/employer
since the /student base table path is assumed.
<join_column> referencedTablePath attributeThe only exception to the optional inclusion of the base table path is the
referencedTablePath of <join_column>. This attribute value does
not support the omission of the base table path
The following Pull Reports™ XML Catalog file lists each table resource path within an XML comment above the table definition.
<?xml version="1.0" encoding="UTF-8"?> <catalog xmlns="http://www.pullreports.com/catalog-1.7.0" id="class" name="Class Reports" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.pullreports.com/catalog-1.7.0 https://www.pullreports.com/docs/xsd/pullreports-catalog-1.7.0.xsd"> <report id="student-information" name="Student Information"> <export_config defaultColumns='id,name'/> <!-- Path: /student --> <table id="student" displayName="Student Details" name="student_details"> <column id="id" name="id" displayName="Student ID" paramType="java.lang.Integer"/> <column id="name" name="student_name" displayName="Student Name"/> <column id="bdate" name="birth_date" displayName="Birth Date" paramType="java.sql.Date"/> <column id="active" name="is_active" displayName="Is Active?" paramType="java.lang.Boolean"/> <relationship> <join_table name="student_parent"> <join_columns> <join_column columnName="student_id" referencedColumnName="id" /> </join_columns> <inverse_join_columns> <join_column columnName="parent_id" referencedColumnName="id" /> </inverse_join_columns> </join_table> <!-- Path: /student/parent --> <table id="parent" displayName="Parent Details" name="parent"> <column id="id" name="id" displayName="Parent ID" paramType="java.lang.Integer"/> <column id="name" name="parent_name" displayName="Parent Name"/> <relationship> <join_table name="parent_employer"> <join_columns> <join_column columnName="parent_id" referencedColumnName="id" /> </join_columns> <inverse_join_columns> <join_column columnName="employer_id" referencedColumnName="id" /> </inverse_join_columns> </join_table> <!-- Path: /student/parent/employer --> <table_ref id="employer" ref="employer_global"/> </relationship> </table> </relationship> <relationship> <join_table name="student_employer"> <join_columns> <join_column columnName="student_id" referencedColumnName="id" /> </join_columns> <inverse_join_columns> <join_column columnName="employer_id" referencedColumnName="id" /> </inverse_join_columns> </join_table> <!-- Path: /student/employer --> <table_ref id="employer" ref="employer_global"/> </relationship> </table> </report> <!-- Path: Not Applicable. Global <table>s do not have a Path --> <table id="employer_global" displayName="Employer" name="employer_details"> <column id="id" name="id" displayName="Employer ID" paramType="java.lang.Integer"/> <column id="name" name="name" displayName="Employer Name"/> <relationship join="inner" cardinality="one"> <join_column columnName="state_abbreviation" referencedColumnName="abbreviation" /> <!-- Valid paths: Path 1: /student/employer/state (when joined from /student/employer) Path 2: /student/parent/employer/state (when joined from /student/parent) --> <table_ref id="state" ref="state_global"/> </relationship> </table> <!-- Path: Not Applicable. Global <table>s do not have a Path --> <table id="state_global" displayName="State" name="state"> <column id="abbr" name="abbreviation" displayName="State Abbreviation"/> <column id="name" name="name" displayName="State"/> </table> </catalog>
When creating paths with <table_ref>s,
use the id of the <table_ref> instead of the id
of the referenced Global <table>. This keeps the path
to each table reference unique.
A column resource path is a reference to a specific <column>. Create column resource paths
by appending the at-sign (@) plus the column's id to the
column's parent table resource path.
For example, the path:
/student/parent/employer@name
refers to the column with id name of the
employer table joined as a child <relationship> to the
parent table joined as a child <relationship> to the
base student table.
Column resource paths are commonly used within the Export Report REST API
filter, columns, and
sort parameters and several other catalog configuration
elements such as <export_config>, <url_template>, and <placemark_name_template>.
Similar to table resource paths, column resource paths may exclude the base table path. For instance, the previous example may also be written as:
/parent/employer@name
because the /student base table path may be omitted. Furthermore, when referring to columns
on the base table, the table path may be omitted all together. For example, the following column resources paths
are equivalent paths to the name column of the student base table.
@name
/student@name
columns ParameterWhen used within the columns
Export Report REST API parameter, a column resource path may include a comma separated list of column
ids like so:
/student/parent/employer@id,name,zipcode
<column_group>s
Paths to child <column>s from referenced <column_group>s are constructed
as if the <column> was a direct child of
the <table> which contains the <column_group_ref>.
In the following Pull Reports™ XML Catalog file examples, /table@id refers to the id column of both base
tables.
<?xml version="1.0" encoding="UTF-8"?> <catalog xmlns="http://www.pullreports.com/catalog-1.7.0" id="catalog-id" name="Catalog Name" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.pullreports.com/catalog-1.7.0 https://www.pullreports.com/docs/xsd/pullreports-catalog-1.7.0.xsd"> <report id="report-id" name="Report"> <table id="table" displayName="Details" name="details"> <column id="id" name="id" displayName="ID" paramType="java.lang.Integer"/> </table> </report> </catalog>
<?xml version="1.0" encoding="UTF-8"?> <catalog xmlns="http://www.pullreports.com/catalog-1.7.0" id="catalog-id" name="Catalog Name" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.pullreports.com/catalog-1.7.0 https://www.pullreports.com/docs/xsd/pullreports-catalog-1.7.0.xsd"> <report id="report-id" name="Report with column_group"> <table id="table" displayName="Details" name="details"> <column_group_ref ref="column_group"/> </table> </report> <column_group id="column_group"> <column id="id" name="id" displayName="ID" paramType="java.lang.Integer"/> </column_group> </catalog>