Report Builder

Report Builder

Build automated data reports with scheduled delivery. Create report templates, schedule automated generation, and deliver reports via email in multiple formats.

Features

• Report Templates: Define reusable report configurations with aggregation and filtering
• Scheduled Reports: Automate report generation on daily, weekly, monthly, or custom schedules
• Data Aggregation: Sum, average, count, min, max operations on data
• Visualizations: Integrated charts from chart-generator
• Multi-format Export: HTML, CSV, JSON, PDF-ready reports
• Email Delivery: Automatic report delivery to specified recipients
• Report History: Track all generated reports with metadata

Installation

npm install
npm run build

Configuration

The report builder requires the following dependencies to be configured:

1. data-connector: Set up data connections to your sources
2. chart-generator: No additional config needed
3. email: Configure Gmail OAuth for email delivery

Usage

CLI

# Check health
npm run status

# Create a report template
npm run cli -- template-create --name "Sales Report" --connection 1 --value Revenue --label Month --chart bar

# List templates
npm run cli -- template-list

# Create a scheduled report
npm run cli -- schedule-create --template 1 --name "Weekly Sales" --period weekly --day-of-week 1 --time 09:00 --formats html,csv --recipients team@company.com

# Generate report immediately
npm run cli -- generate 1 --output report.html

# Execute a scheduled report
npm run cli -- execute 1

# Check and run due reports
npm run cli -- due

# View report history
npm run cli -- history

# Show statistics
npm run cli -- stats

Library

import { ReportBuilderSkill } from '@openclaw/report-builder';

const skill = new ReportBuilderSkill();

// Create a report template
const template = await skill.createTemplate({
  name: 'Monthly Sales Report',
  description: 'Revenue by month',
  connectionId: 1,
  aggregationType: 'sum',
  groupByColumn: 'Month',
  valueColumn: 'Revenue',
  labelColumn: 'Month',
  chartType: 'bar',
  includeChart: true,
  includeTable: true,
  includeSummary: true
});

// Create a scheduled report
const schedule = await skill.createSchedule({
  templateId: template.id!,
  name: 'Weekly Sales Email',
  period: 'weekly',
  dayOfWeek: 1, // Monday
  timeOfDay: '09:00',
  formats: ['html', 'csv'],
  emailRecipients: ['boss@company.com', 'team@company.com'],
  emailSubject: 'Weekly Sales Report',
  enabled: true
});

// Generate report immediately
const htmlReport = await skill.generateHtmlReport(template.id!);
fs.writeFileSync('report.html', htmlReport);

// Execute scheduled report
const results = await skill.executeReport(schedule.id!);

// Check for and run due reports
const dueResults = await skill.checkAndExecuteDueReports();

// Close
await skill.close();

Report Templates

Templates define the structure and content of reports:

Scheduled Reports

Schedules control when and how reports are generated:

Report Formats

HTML

Full-featured report with:

• Professional styling
• Summary statistics
• Interactive charts (SVG)
• Sortable data tables

CSV

Raw data export:

• Header row
• Comma-separated values
• Proper escaping for special characters

JSON

Structured data export:

{
  "generatedAt": "2024-01-15T10:00:00Z",
  "summary": {
    "total": 150,
    "aggregated": { "Q1": 45000, "Q2": 52000 }
  },
  "data": [...]
}

PDF

PDF-ready HTML output - convert using external tools:

# Using Chrome headless
google-chrome --headless --print-to-pdf report.html

# Using wkhtmltopdf
wkhtmltopdf report.html report.pdf

Aggregation Types

• sum: Total of values
• average: Mean of values
• count: Number of records
• min: Minimum value
• max: Maximum value
• none: No aggregation (raw data)

Automation

Set up a cron job to check for due reports:

# Edit crontab
crontab -e

# Run every hour
0 * * * * cd /path/to/report-builder && npm run cli -- due

Or use with systemd timer for more control.

Report History

All generated reports are tracked with:

• Generation timestamp
• Format and file location
• Record count
• Success/failure status
• Email delivery status

Examples

Sales Dashboard Report

# Create template with chart
npm run cli -- template-create \
  --name "Sales Dashboard" \
  --connection 1 \
  --aggregation sum \
  --group-by Region \
  --value Sales \
  --label Region \
  --chart bar \
  --include-chart \
  --include-summary

# Schedule weekly delivery
npm run cli -- schedule-create \
  --template 1 \
  --name "Weekly Sales Dashboard" \
  --period weekly \
  --day-of-week 1 \
  --time 08:00 \
  --formats html,csv \
  --recipients sales@company.com \
  --subject "Weekly Sales Report"

Monthly Financial Report

# Create template
npm run cli -- template-create \
  --name "Monthly P&L" \
  --connection 2 \
  --aggregation sum \
  --group-by Category \
  --value Amount \
  --chart pie

# Schedule monthly
npm run cli -- schedule-create \
  --template 2 \
  --name "Monthly P&L Report" \
  --period monthly \
  --day-of-month 1 \
  --time 09:00 \
  --formats html,pdf \
  --recipients cfo@company.com,finance@company.com

Ad-hoc Report Generation

# Generate immediately
npm run cli -- generate 1 --output /tmp/sales.html

# Preview data
npm run cli -- preview 1