<catalog>

Abstract

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

Usage

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.5.0" 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"/>
        </table>
    </report>
    <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"/>
        </table>
    </report>
    <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"/>
        </table>
    </report>
</catalog>
                

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 java.util.List;

import javax.servlet.ServletContext;

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.ColumnConfiguration.ColumnConfigurationBuilder;
import com.pullreports.model.config.ReportConfiguration;
import com.pullreports.model.config.ReportConfiguration.ReportConfigurationBuilder;
import com.pullreports.model.config.TableConfiguration;
import com.pullreports.model.config.TableConfiguration.TableConfigurationBuilder;
import java.util.Arrays;

public class SimpleCatalogConfigurationFactory implements CatalogConfigurationFactory {

    @Override
    public CatalogConfiguration makeCatalog(ServletContext servletContext) {

        ReportConfiguration report1Configuration = makeReportConfiguration(1L);
        ReportConfiguration report2Configuration = makeReportConfiguration(2L);
        ReportConfiguration report3Configuration = makeReportConfiguration(3L);
        
        List<ReportConfiguration> reportConfigurations = 
                Arrays.asList(new ReportConfiguration[]{
                    report1Configuration,report2Configuration,report3Configuration});

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

    private ReportConfiguration makeReportConfiguration(Long id){

        TableConfiguration tableConfiguration = makeTableConfiguration(id);

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

    private TableConfiguration makeTableConfiguration(Long id){

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

        List<ColumnConfiguration> columnConfigurations = Arrays.asList(
            new ColumnConfiguration[]{columnBuilder.build()});

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

Children

<access_control_voter>?
<report>+
<column_group>*
<table>* (Global tables)
<global_label_value_list>+

Attributes

id

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.

name

The human readable catalog name.