<description>

Abstract

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


Table of Contents

Catalog Configuration Java API analog:  CannedQueryConfigurationBuilder#setDescription, ColumnConfiguration.Builder#setDescription, ReportConfiguration.Builder#setDescription, TableConfiguration.Builder#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™ 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 Report Creator.

Table 1. Where <description>s display in the Pull Reports™ Report Creator
<description> Parent ElementCreator Display
<report>The Help Tab, Description Panel
<table> and <table_ref>The Columns panel, description section.
<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

Usage

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.6.1" id="my-catalog" name="Described Reports"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.pullreports.com/catalog-1.6.1
    https://www.pullreports.com/docs/xsd/pullreports-catalog-1.6.1.xsd">
    <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>.
            <ul>
            <li>There is even a list to describe</li>
            <li>several items</li>
            </ul>
            ]]></description>
            <subquery>
                <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>
            <column id="the_date" name="the_date" paramType="java.sql.Date"/>
        </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.description;

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.ReportConfiguration;
import com.pullreports.model.config.TableConfiguration;

import javax.servlet.ServletContext;
import javax.servlet.http.HttpServletRequest;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.Optional;

public class DescriptionCatalogConfigurationFactory implements CatalogConfigurationFactory {

    @Override
    public CatalogConfiguration makeCatalog(ServletContext servletContext) {

        ReportConfiguration reportConfiguration = makeReportConfiguration();
        
        List<ReportConfiguration> reportConfigurations = 
                Collections.singletonList(reportConfiguration);

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

    private ReportConfiguration makeReportConfiguration(){

        TableConfiguration tableConfiguration = makeTableConfiguration();

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

    private TableConfiguration makeTableConfiguration(){

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

        ColumnConfiguration dateColumn= new ColumnConfiguration.Builder(
            new ColumnId("the_date"),"the_date").setParamType(ParamType.DATE)
            .build();

        List<ColumnConfiguration> columnConfigurations = Arrays.asList(idColumn,dateColumn);

        return new TableConfiguration.Builder(
            new TableId("table-1"),"Table With Description",columnConfigurations)
            .setDescription(
            "This description contains <strong>HTML</strong>. " +
            "<ul>" +
            "<li>There is even a list to describe</li>" +
            "<li>several items</li>" +
            "</ul>"
            		)
            .setSubqueryProvider(new MySubqueryProvider()).build();
    }
    
    private static class MySubqueryProvider implements SubqueryProvider {
        @Override
        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()");
                }
            };
        }
    }
}
                

Parents

<canned_query>
<column>
<report>
<subquery>
<table>
<table_ref>