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

Table of Contents

Catalog Configuration Java API analog:  ColumnConfigurationBuilder#setDescription, ReportConfigurationBuilder#setDescription, TableConfigurationBuilder#setDescription Subquery#getDescription

A <description> contains a textual description of the parent element. The description text is returned from the GET Report Information or GET Export Report REST APIs and reflected within the Pull Reports™ Ad Hoc Report Creator or export output respectively. Use <description> elements to provide helpful information about <report>, <table>, <table_ref>, <subquery>, or <column> elements.

<description> elements may contain well-formed HTML. However, note that open HTML elements without an end tag will cause errors in the Ad Hoc Report Creator.

Table 1. Where <description>s display in the Pull Reports™ Ad Hoc Report Creator
<description> Parent ElementCreator Display
<report>The Help Tab, Description Panel
<table> and <table_ref>The Tables Tab, Description Panel
<subquery>Within the Export Report REST API export metadata. The exact location of the <subquery> description depends on the export format. For instance, the html format places the <subquery> descriptive text above the exported HTML table.
<column>The Tables Tab, Columns Panel


Catalog with <description>s

The following Pull Reports™ XML Catalog file demonstrates several uses of the <description> element.

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="Described Reports">
    <report id="my-report" name="Report with Description">
        <description>This description describes the purpose of the report.</description>
        <table id="table-1" displayName="Table With Description"> 
            <description><![CDATA[This description contains <strong>HTML</strong>.
            <li>There is even a list to describe</li>
            <li>several items</li>
                <description>Records in the returned result have a date greater than the time
                the report is run.</description>
            select * from table_1_name where the_date > now()</subquery>
            <column id="id" name="id" paramType="java.lang.Integer">
                <description>A column description displays as column "Metadata"
                in the Ad Hoc Report Creator.</description>
            <column id="the_date" name="the_date" paramType="java.sql.Date"/>

Example 2. Via the Catalog Configuration Java API

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

package com.pullreports.examples.description;

import java.util.Arrays;
import java.util.List;
import java.util.Optional;

import javax.servlet.ServletContext;
import javax.servlet.http.HttpServletRequest;

import com.pullreports.model.CatalogId;
import com.pullreports.model.ColumnId;
import com.pullreports.model.ParamType;
import com.pullreports.model.ReportId;
import com.pullreports.model.Subquery;
import com.pullreports.model.SubqueryProvider;
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 DescriptionCatalogConfigurationFactory implements CatalogConfigurationFactory {

    public CatalogConfiguration makeCatalog(ServletContext servletContext) {

        ReportConfiguration reportConfiguration = makeReportConfiguration();
        List<ReportConfiguration> reportConfigurations = 
                Arrays.asList(new ReportConfiguration[]{reportConfiguration});

        return new CatalogConfiguration(new CatalogId("my-catalog"),"Described Reports",reportConfigurations);

    private ReportConfiguration makeReportConfiguration(){

        TableConfiguration tableConfiguration = makeTableConfiguration();

        return new ReportConfigurationBuilder(
            new ReportId("my-report"),"Report with Description",tableConfiguration)
        		.setDescription("This description describes the purpose of the report.").build();

    private TableConfiguration makeTableConfiguration(){

        ColumnConfiguration idColumn= new ColumnConfigurationBuilder(
            new ColumnId("id"),"id").setParamType(ParamType.INTEGER)
            .setDescription("A column description displays as column \"Metadata\" in the Ad Hoc Report Creator.")

        ColumnConfiguration dateColumn= new ColumnConfigurationBuilder(
            new ColumnId("the_date"),"the_date").setParamType(ParamType.DATE)

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

        return new TableConfigurationBuilder(
            new TableId("table-1"),"Table With Description",columnConfigurations)
            "This description contains <strong>HTML</strong>. " +
            "<ul>" +
            "<li>There is even a list to describe</li>" +
            "<li>several items</li>" +
            .setSubqueryProvider(new MySubqueryProvider()).build();
    private class MySubqueryProvider implements SubqueryProvider {
        public Subquery createSubquery(HttpServletRequest arg0) {
            return new Subquery() {
                @Override public Optional<String> getDescription(){
                    return Optional.of("Records in the returned result have a date greater than the time the report is run.");
                @Override public Optional<String> getValue(){
                    return Optional.of("select * from table_1_name where the_date > now()");