Catalog Configuration Introduction

Abstract

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:

Learning by Example

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.

What is Catalog Configuration?

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.

Catalog Configuration Initialization

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.

XML Catalog Configuration

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.5.0" id="my-catalog" name="My Catalog">
    <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>

Catalog Configuration Java API

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

public class MinimalCatalogConfigurationFactory implements CatalogConfigurationFactory {

    @Override
    public CatalogConfiguration makeCatalog(ServletContext servletContext) {

        ColumnConfiguration myColumnConfiguration = new ColumnConfigurationBuilder(
            new ColumnId("my-column"),"column_name").setDisplayName("Column Name").build();

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

        TableConfiguration myTableConfiguration = new TableConfigurationBuilder(
            new TableId("my-table"),"My Table",columnConfigurations)
            .setName("schema_name.table_name").build();

        ReportConfiguration myReportConfiguration = new ReportConfigurationBuilder(
            new ReportId("my-report"),"My Report",myTableConfiguration).build();
        
        List<ReportConfiguration> reportConfigurations = Arrays.asList(
            new ReportConfiguration[]{myReportConfiguration});

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

            

Catalog Configuration Concepts

Table Resource Paths

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.

Excluding the Base Table Path

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.

Base table path required for <join_column> referencedTablePath attribute

The 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

Example Report Configuration

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.5.0" id="class" name="Class Reports">
    <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 cardinality="many">
                <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 cardinality="many">
                        <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 cardinality="many">
                <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>

Note

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.

Column Resource Paths

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

Excluding the Base Table Path

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

Column Resource Paths in the columns Parameter

When 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 Resource Paths with <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.5.0" id="catalog-id" name="Catalog Name">
    <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.5.0" id="catalog-id" name="Catalog Name">
    <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>

XML Validation

Eclipse is a popular open source Integrated Development Environment which can validate Pull Reports™ XML Catalog files via these steps:

Steps created with Eclipse Luna 4.4.1.

  1. Open the Eclipse project which contains the Pull Reports™ XML Catalog file to validate.

  2. Open the Preferences dialog via the Window > Preferences menu item.

  3. In the left hand navigation of the Preferences dialog, select XML > XML Catalog.

  4. On the XML Catalog panel, click the Add button.

  5. In the Add XML Catalog Element dialog, create a new Catalog entry by filling out the following inputs and clicking OK.

    The Location should be the Location of the Pull Reports™ XSD file, the Key type should be Namespace name, and the Key should be http://www.pullreports.com/catalog-1.5.0.

  6. After clicking "OK" to close the Preferences dialog, open a Pull Reports™ XML Catalog file, right click on the file, and select Validate to see validation errors.