Table of Contents

• Introduction
• PDF Document Processing
  • Bursting PDF Reports
    • PDF Bursting Configuration Steps
  • Sample: Bursting Invoices-Oct.pdf
  • Merging PDF Reports
• Excel Document Processing
  • Overview
  • Burst by Distinct Sheets
  • Burst by Distinct Column Values
    • How It Works

Introduction

ReportBurster splits reports into separate documents using burst tokens - unique identifiers for each document section. These tokens can be invoice numbers, customer IDs, email addresses, or any other identifying information that distinguishes different portions of your reports.

This guide explains how to burst and merge both PDF and Excel reports, and how to configure ReportBurster to meet your specific needs.

PDF Document Processing

Bursting PDF Reports

ReportBurster identifies burst tokens in PDF documents by looking for text wrapped in curly brackets { }. When the software encounters a new burst token, it breaks the document at that point, creating separate files.

For example, the burst token {[email protected]} identifies pages that should go into Alfreda Waldback's PDF document.

ReportBurster includes a sample three-page samples/burst/Payslips.pdf document (in the samples/burst folder). When you burst this report, it will generate three output files for the distinct employees found in the input report:

• [email protected]
• [email protected]
• [email protected]

Check the samples/burst/Payslips.pdf report to see how the burst tokens are defined like email addresses delimited by curly brackets, { and }

PDF Bursting Configuration Steps

Follow these steps when bursting any PDF report:

1. Identify the appropriate burst token for your report type (e.g. invoice number, customer ID, etc.)
2. Modify the input report to include curly brackets { } around your identified burst token
3. Configure ReportBurster if needed (the default configuration often works well)
4. Burst the report and check the output files

Tip: Use white font color for the burst tokens or curly brackets to maintain the visual appearance of your reports.

Sample: Bursting Invoices-Oct.pdf

This example demonstrates how to burst the samples/burst/Invoices-Oct.pdf report:

1. Identify the appropriate burst token
   We'll use the invoice number since it uniquely identifies each invoice.

2. Modify the input report
   Have the PDF report include curly brackets around invoice numbers, as shown below:

   

3. Configure custom output file names

   By default, output files are named ${burst_token}.${input_document_extension}, this would generate file names like 0011.pdf and 0012.pdf.

   We'll customize this to create more descriptive filenames like Invoice-0011.pdf

   

4. Burst the report
   

   As per our custom Burst File Name configuration, the output files are now named Invoice-0011.pdf, Invoice-0012.pdf, Invoice-0013.pdf and Invoice-0014.pdf

   

Merging PDF Reports

Before bursting, you may need to merge multiple reports. ReportBurster lets you combine reports and optionally burst the merged result.

To merge PDF files

1. Select multiple files to merge (use Ctrl+click to select multiple files)

2. Set your merge options:
   • Control merge order with the Up and Down buttons
   • Set a Merged File Name (default: merged.pdf)
   • Check Burst Merged File if you want to split the merged result

Excel Document Processing

Overview

ReportBurster supports Excel files from all versions (Excel 97 through the latest Excel releases), without requiring Microsoft Excel to be installed on the processing machine. This allows you to deploy ReportBurster (Server) on dedicated servers for batch processing.

ReportBurster supports two methods for bursting Excel reports, specifically:

1. Burst by Distinct Sheets - Creates a separate file for each sheet
2. Burst by Distinct Column Values - Creates a file for each unique value in a specific column

Burst by Distinct Sheets

This straightforward method creates a separate output file for each Excel sheet in the input report. The sheet name becomes the burst token.

For example, the samples/burst/Payslips-Distinct-Sheets.xls report contains income data for three employees on separate sheets.

Each sheet is named with an employee's email address (e.g., [email protected]).

When burst, this report generates three distinct files named after each sheet [email protected], [email protected], and [email protected]

Using email addresses as sheet names is convenient when distributing the output files by email.

Note: Burst by Distinct Sheets is ReportBurster's default Excel bursting method

Burst by Distinct Column Values

This method generates a separate file for each unique value found in a specified column. For example, you might burst a customer list by country, creating a separate file for each country's customers.

The sample report samples/burst/Customers-Distinct-Column-Values.xls contains customer data from various countries. When burst by country, each output file contains only the customers from that country:

Each configured burst token will generate a different output file.

How It Works

To burst by column values:

1. Create a burst metadata sheet: The last sheet of your Excel report must be named burst and contain the required metadata

2. Define burst parameters: Specify settings including:

   • burstMethod: Set to distinct-column-values or distinct-sheets
   • burstSheetIndex: Zero-based index of the sheet to split (default -1 means first sheet)
   • burstColumnIndex: Zero-based index of the column to use for splitting (default -1 means last column)
   • burstTokens: List of distinct values to generate separate files for
   • userVariables: Specify custom variables for each burst token when needed. These variables can be used in output file names, email templates, and other configurable elements. For more details, see Excel User-Defined Variables
   • configFile: Specify a custom configuration file for processing different types of Excel reports. By default, ReportBurster uses ./config/burst/settings.xml, but you can create specialized configurations for different report types. This lets you apply unique settings for each report format. For more information, see Process Excel Reports Using a Custom Configuration File

3. Add a classification column: Create a (typically hidden) additional column in your (main) Excel sheet that contains the burst token value for each row. This column tells ReportBurster which output file each row should belong to. For example, in a customer list, this column would contain the country name for each customer.

   

Important: If your report contains Excel formulas, replace them with their calculated values before processing

Copy/Preserve Report Header/Footer and Empty Rows

Most Excel reports contain standard headers and/or footers (such as company logos, report titles, or timestamps) that should be preserved in each output file. ReportBurster automatically maintains these static elements in all generated files, ensuring consistent formatting and branding across split reports.

Empty Rows

ReportBurster automatically keeps rows that don't contain burst token values in the output files. This preserves important formatting elements like headers, titles, and footers across all generated reports, ensuring consistent presentation throughout split documents.