Learn to configure the <catalog> element for Pull Reports™ Ad Hoc report and data service software.

Table of Contents

Catalog Configuration Java API analog:  CatalogConfiguration

The root element of a Pull Reports™ XML Catalog file. One <catalog> groups one to many reports into a common resource path within the Pull Reports REST API. This allows all <report>s within <catalog> to share a common URL path, JNDI javax.sql.DataSource, and <access_control_voter> security.

Specify Pull Report catalogs via XML Catalog files or via the Catalog Configuration Java API's CatalogConfigurationFactory. See the catalogs configuration property for more information.


Minimal <catalog> example with multiple <report>s

The following minimal example contains a <catalog> with three reports, each with one <table> containing one <column>.

The three reports are available at the following Export Report REST API paths based on their <catalog> and <report> ids:

  • /[context]/pullreports/catalog/my-catalog/report/my-report-1/export

  • /[context]/pullreports/catalog/my-catalog/report/my-report-2/export

  • /[context]/pullreports/catalog/my-catalog/report/my-report-3/export

Example 1. Via an XML Catalog file
<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="http://www.pullreports.com/catalog-1.6.1" id="my-catalog" name="My Catalog"
    <report id="my-report-1" name="Report 1">
        <table id="table1" name='table_name1' displayName="Table 1"> 
            <column id="column1" name="column_name" displayName="Column Name 1"/>
    <report id="my-report-2" name="Report 2">
        <table id="table2" name='table_name2' displayName="Table 2"> 
            <column id="column2" name="column_name" displayName="Column Name 2"/>
    <report id="my-report-3" name="Report 3">
        <table id="table3" name='table_name3' displayName="Table 3"> 
            <column id="column3" name="column_name" displayName="Column Name 3"/>

Example 2. Via the Catalog Configuration Java API

The following example is an identical Catalog Configuration Java API configuration.

package com.pullreports.examples.catalog;

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 javax.servlet.ServletContext;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class SimpleCatalogConfigurationFactory implements CatalogConfigurationFactory {

    public CatalogConfiguration makeCatalog(ServletContext servletContext) {

        ReportConfiguration report1Configuration = makeReportConfiguration(1L);
        ReportConfiguration report2Configuration = makeReportConfiguration(2L);
        ReportConfiguration report3Configuration = makeReportConfiguration(3L);
        List<ReportConfiguration> reportConfigurations = 

        return new CatalogConfiguration(new CatalogId("my-catalog"),"My Catalog",reportConfigurations);

    private ReportConfiguration makeReportConfiguration(Long id){

        TableConfiguration tableConfiguration = makeTableConfiguration(id);

        return new ReportConfiguration.Builder(
            new ReportId("my-report-" + id),"Report " + id,tableConfiguration).build();

    private TableConfiguration makeTableConfiguration(Long id){

        ColumnConfiguration.Builder columnBuilder = new ColumnConfiguration.Builder(
            new ColumnId("column" + id),"column_name")
            .setDisplayName("Column " + id + " Name");

        List<ColumnConfiguration> columnConfigurations = Collections.singletonList(columnBuilder.build());

        return new TableConfiguration.Builder(
            new TableId("table" + id),"Table " + id,columnConfigurations)
            .setName("table_name" + id).build();


<table>* (Global tables)



The unique id of the catalog within the Pull Reports™ installation. This id forms part of the REST API and is thus a useful way to organize reports under a common URL. For example:

<catalog id="financial" ...>

creates Export Report REST API endpoint:

/[context]/pullreports/catalog/financial/report/[report id]/export

Catalog id's may be composed of alphabetical characters, digits, or the - and _ characters.

Splitting a <catalog> id across many Pull Reports™ XML Catalog files

Although it is common to place all <report>s for one <catalog> into one Pull Reports™ XML Catalog file, it is permitted to duplicate a <catalog> id across two or more Pull Reports™ XML Catalog files. In this case, the report parser will combine the <report>s as if they had been defined in a single Pull Reports™ XML Catalog file. However, the following rules apply:

  • The parser only honors the <catalog> name attribute of the first Pull Reports™ XML Catalog file with the same <catalog> id.

  • The parser only honors the first <report> of a unique id found within a <catalog>, even if that catalog id is found in multiple Pull Reports™ XML Catalog files.


The human-readable catalog name.