Version: Unreleased

PDF Report Generation

This guide explains how to configure automated PDF reports using the Auto Trigger feature. PDF reports allow you to visualize Elasticsearch query results with charts and deliver them on a schedule.

Overview

PDF reports transform your data selections into visual charts rendered in document format. The system supports multiple chart types, automatic visualization inference, and flexible page configurations.

Quick Start

To create a PDF report, add toPdf as your format channel transformation type. The minimum configuration requires linking your data selections to chart entries.

Key principle: The variableName in your chart configuration must exactly match the variableName defined in your data selection.

Configuration Reference

Format Channel Structure

"formatChannel": [
  {
    "transformationType": "toPdf",
    "parameters": {
      "pageSize": "A4",
      "orientation": "landscape",
      "charts": [
        {
          "variableName": "YourDataVariable",
          "chartTitle": "Your Chart Title"
        }
      ]
    }
  }
]

Page Settings

Parameter	Options	Default	Description
`pageSize`	`A4`, `Letter`, `Legal`	`A4`	Physical page dimensions
`orientation`	`portrait`, `landscape`	`landscape`	Page orientation

Chart Configuration Options

Each chart entry supports the following properties:

Property	Required	Description
`variableName`	Yes	Must match exactly the `variableName` from your data selection
`chartTitle`	No	Custom title displayed above the chart. Defaults to a formatted version of the variable name (for example: `CallDurationOverTime` → Call Duration Over Time)
`chartType`	No	Explicit visualization type. If omitted, the system automatically infers the best chart type
`maxLength`	No	Maximum items to display (applies to `list` and `table` types)

Automatic Chart Type Inference

When you omit the chartType property, the system analyzes your data and automatically selects the most appropriate visualization.

Chart Selection by Data Type

Category	Condition	Chart
scalar	—	`value`
time-series	nested buckets + nested value	`multipleLine`
time-series	nested buckets only	`stackedBar`
time-series	no nesting	`timedateBar`
categorical	nested + depth ≥ 2	`sunburst`
categorical	nested + depth < 2	`list`
categorical	no nesting + ≤ 8 items	`donut`
categorical	no nesting + > 8 items	`list`
tabular	—	`table`
tuple	≤ 8 items	`donut`
tuple	> 8 items	`list`
unknown	fallback	`value`

Tip: For most use cases, automatic inference produces optimal results. Only specify chartType explicitly when you need a specific visualization that differs from the inferred default.

Chart Type Validation

When you explicitly set a chartType, the system validates that it is compatible with your data structure. If there is a mismatch, the report will fail with a descriptive error message.

Example Error

If you set "chartType": "stackedBar" on a simple date histogram without nested buckets:

Variable "CallsOverTime": Chart type "stackedBar" requires nested buckets in time-series data.
Recommended: "timedateBar".

Tip: If you encounter a validation error, either adjust your Elasticsearch query to match the chart requirements, or use the recommended chart type.

Minimal Schema Example

A simple PDF report with one data selection and one chart:

{
  "$schema": "http://localhost:5555/api/asyncJobs/schema",
  "name": "Daily Call Duration Report",
  "description": "Single chart PDF report example",
  "enabled": true,
  "version": "1.0.0",
  "cronDefinition": "0 6 * * *",
  "type": "user",
  "function": {
    "functionReferenceList": [
      {
        "reportName": "Call Duration Report",
        "description": "Hourly call duration over the last 24 hours",
        "data": {
          "selection": [
            {
              "dataSource": "es",
              "variableName": "CallDurationOverTime",
              "parameters": [
                {
                  "index": "calls",
                  "ignore_unavailable": true
                },
                {
                  "size": 0,
                  "query": {
                    "bool": {
                      "must": [
                        { "query_string": { "query": "attrs.type:call-end" } },
                        { "range": { "@timestamp": { "gte": "now-24h", "lte": "now" } } }
                      ]
                    }
                  },
                  "aggs": {
                    "agg": {
                      "date_histogram": {
                        "field": "@timestamp",
                        "fixed_interval": "1h"
                      }
                    }
                  }
                }
              ]
            }
          ],
          "transformations": {
            "transformationType": "js",
            "codeFunctionReference": ""
          },
          "formatChannel": [
            {
              "transformationType": "toPdf",
              "parameters": {
                "pageSize": "A4",
                "orientation": "landscape",
                "charts": [
                  {
                    "variableName": "CallDurationOverTime",
                    "chartTitle": "Call Duration Over Time (Last 24 Hours)"
                  }
                ]
              }
            }
          ]
        },
        "transport": []
      }
    ]
  }
}

Variable Name Matching

The connection between data selections and charts relies on exact variableName matching.

Data Selection:

{
  "dataSource": "es",
  "variableName": "CallDurationOverTime",
  "parameters": [ ... ]
}

Chart Configuration:

{
  "variableName": "CallDurationOverTime",
  "chartTitle": "Call Duration Over Time (Last 24 Hours)"
}

Important: Variable names are case-sensitive. CallDurationOverTime and calldurationovertime are treated as different variables.

Recommendations

Use Case	Page Size	Orientation	Why
Dashboard Reports	A4 or Letter	Landscape	Multi-chart layouts display better with wider horizontal space
Data Tables	Legal	Portrait	Extra vertical space accommodates more rows without pagination
Single Charts	A4 or Letter	Portrait	Focused visualizations benefit from balanced dimensions

Common Patterns

Single Chart Report

"formatChannel": [
  {
    "transformationType": "toPdf",
    "parameters": {
      "pageSize": "A4",
      "orientation": "portrait",
      "charts": [
        {
          "variableName": "DailyCallVolume",
          "chartTitle": "Daily Call Volume Summary"
        }
      ]
    }
  }
]

Multi-Chart Dashboard

"formatChannel": [
  {
    "transformationType": "toPdf",
    "parameters": {
      "pageSize": "A4",
      "orientation": "landscape",
      "charts": [
        {
          "variableName": "CallVolume",
          "chartTitle": "Call Volume Trend"
        },
        {
          "variableName": "TopAgents",
          "chartTitle": "Top Performing Agents",
          "chartType": "list",
          "maxLength": 10
        },
        {
          "variableName": "CallDistribution",
          "chartTitle": "Calls by Department",
          "chartType": "donut"
        }
      ]
    }
  }
]

Multiple Output Formats

You can generate PDF alongside other formats in the same report:

"formatChannel": [
  {
    "transformationType": "toPdf",
    "parameters": {
      "pageSize": "A4",
      "orientation": "landscape",
      "charts": [
        {
          "variableName": "SummaryData",
          "chartTitle": "Executive Summary"
        }
      ]
    }
  },
  {
    "transformationType": "toCsv",
    "parameters": {}
  },
  {
    "transformationType": "toJson",
    "parameters": {}
  }
]

Best Practices

Use descriptive variable names — Names like CallDurationByHour are clearer than data1
Let inference work for you — Only specify chartType when you need a specific visualization
Match variable names exactly — Copy-paste to avoid typos between data selection and chart config
Use landscape for dashboards — Multiple charts display better in landscape orientation
Limit table rows — Use maxLength to keep table charts readable
Test with Run Now — Validate your configuration immediately before scheduling

Troubleshooting

Issue	Cause	Solution
Chart shows "No Data"	Variable name mismatch	Verify exact spelling and case of `variableName`
Wrong chart type displayed	Inference selected different type	Explicitly set `chartType`
Chart type validation error	Explicit `chartType` incompatible with data	Use a compatible chart type or adjust your ES query
PDF too long	Table has too many rows	Add `maxLength` to limit rows

Overview​

Quick Start​

Configuration Reference​

Format Channel Structure​

Page Settings​

Chart Configuration Options​

Automatic Chart Type Inference​

Chart Selection by Data Type​

Chart Type Validation​

Example Error​

Minimal Schema Example​

Variable Name Matching​

Recommendations​

Common Patterns​

Single Chart Report​

Multi-Chart Dashboard​

Multiple Output Formats​

Best Practices​

Troubleshooting​