Report Generation

The doover report command group provides tools for generating reports from Doover agent data. Reports can aggregate data across multiple agents and time periods, producing output in various formats including XLSX.

Available Commands

Command	Description
`compose`	Generate a report locally

Composing Reports

The doover report compose command generates a report using a specified report generator module.

Usage

doover report compose [OPTIONS]

Options

Option	Description	Default
`--period-from`	Start of the reporting period	7 days ago
`--period-to`	End of the reporting period	Now
`--agent-ids`	Comma-separated list of agent IDs	(empty)
`--agent-names`	Comma-separated list of agent display names	(empty)
`--package-path`	Python module path for the report generator	`pydoover.reports.xlsx_base`
`--profile`	Configuration profile to use	`default`

Example

# Generate report for specific agents over the last week
doover report compose --agent-ids "abc123,def456" --agent-names "Sensor 1,Sensor 2"

# Generate report for a custom date range
doover report compose \
  --period-from "2024-01-01" \
  --period-to "2024-01-31" \
  --agent-ids "abc123"

# Use a custom report generator
doover report compose \
  --package-path "my_reports.custom_generator" \
  --agent-ids "abc123,def456"

Output

Reports are saved to a temporary directory:

Progress: 10%
Progress: 50%
Progress: 100%
Report composed successfully!
Output saved to: /tmp/doover_report_output/

Report Generation Process

When you run doover report compose, the following steps occur:

Initialize workspace - Creates/clears the temporary output directory
Determine timezone - Detects your local timezone for proper date handling
Load generator - Imports the specified report generator module
Instantiate generator - Creates the generator with all parameters
Generate report - Runs the report generation logic
Save output - Writes results to the output directory

Report Generator Interface

Report generators follow a standard interface. The default generator is pydoover.reports.xlsx_base, which produces Excel spreadsheets.

Generator Parameters

When instantiated, generators receive:

Parameter	Description
`tmp_workspace`	Directory for output files
`access_token`	API token for authentication
`agent_ids`	List of agent IDs to include
`agent_display_names`	Human-readable names for agents
`period_from_utc`	Start of period (UTC)
`period_to_utc`	End of period (UTC)
`for_timezone`	Timezone for display
`logging_function`	Function for log output
`progress_update_function`	Function for progress updates
`api_endpoint`	Doover API base URL
`report_name`	Name for the report
`test_mode`	Whether running in test mode

Creating Custom Generators

To create a custom report generator:

# my_reports/custom_generator.py

class Generator:
    def __init__(
        self,
        tmp_workspace,
        access_token,
        agent_ids,
        agent_display_names,
        period_from_utc,
        period_to_utc,
        for_timezone,
        logging_function,
        progress_update_function,
        api_endpoint,
        report_name,
        test_mode,
    ):
        self.workspace = tmp_workspace
        self.agent_ids = agent_ids
        self.period_from = period_from_utc
        self.period_to = period_to_utc
        self.log = logging_function
        self.update_progress = progress_update_function
        # ... store other parameters

    def generate(self):
        self.log("Starting report generation...")
        self.update_progress(0.1)

        # Fetch data from Doover API
        # Process and aggregate data
        # Generate output files

        self.update_progress(1.0)
        self.log("Report complete!")

# Required: module-level generator reference
generator = Generator

Use your custom generator:

doover report compose --package-path "my_reports.custom_generator"

XLSX Report Output

The default pydoover.reports.xlsx_base generator produces Excel spreadsheets with:

Summary sheets with key metrics
Data sheets with detailed readings
Charts and visualizations
Proper date/time formatting for your timezone

Dependencies

XLSX report generation requires additional packages:

pip install openpyxl xlsxwriter

Or with uv:

uv add openpyxl xlsxwriter

Date and Time Handling

Specifying Periods

Dates can be specified in various formats:

# ISO format
--period-from "2024-01-01T00:00:00"

# Date only (midnight)
--period-from "2024-01-01"

# Relative (handled by the shell)
--period-from "$(date -d '30 days ago' +%Y-%m-%d)"

Timezone Handling

Input dates are interpreted in your local timezone
Internally, dates are converted to UTC for API queries
Output displays use your local timezone

The CLI automatically detects your local timezone using tzlocal.

Multi-Agent Reports

Reports can span multiple agents:

doover report compose \
  --agent-ids "agent1,agent2,agent3" \
  --agent-names "Pump Station 1,Pump Station 2,Pump Station 3"

The agent names are used for display in the report output. Ensure the order matches between --agent-ids and --agent-names.

Progress Tracking

During report generation, progress updates are displayed:

Progress: 0%
Progress: 10%
Progress: 25%
Progress: 50%
Progress: 75%
Progress: 100%
Report composed successfully!

Progress is reported as a percentage (0.0 to 1.0 internally, displayed as 0% to 100%).

Error Handling

If report generation fails:

Error during report generation: Connection timeout

Common issues:

Error	Cause	Solution
Module not found	Invalid package path	Check the module path and ensure it's importable
No 'Generator' found	Missing generator class	Ensure module has a `generator` attribute
Connection timeout	API connectivity issues	Check network and authentication
Permission denied	Cannot write to output directory	Check directory permissions

Output Directory

Reports are saved to /tmp/doover_report_output/ by default. This directory is:

Created if it doesn't exist
Cleared before each report generation
Contains all generated files (XLSX, CSV, images, etc.)

To preserve previous reports, copy them before running a new generation.

Workflow Example

A typical reporting workflow:

# 1. Identify agents to report on
doover agent list --profile production

# 2. Generate weekly report
doover report compose \
  --agent-ids "abc123,def456,ghi789" \
  --agent-names "Site A,Site B,Site C" \
  --profile production

# 3. Check output
ls -la /tmp/doover_report_output/

# 4. Copy report to permanent location
cp /tmp/doover_report_output/*.xlsx ~/reports/weekly-$(date +%Y%m%d).xlsx

# 5. Generate monthly report with custom generator
doover report compose \
  --period-from "2024-01-01" \
  --period-to "2024-02-01" \
  --package-path "company_reports.monthly_summary" \
  --agent-ids "abc123,def456" \
  --profile production

Integration with CI/CD

Reports can be generated automatically in CI/CD pipelines:

# GitHub Actions example
name: Weekly Report

on:
  schedule:
    - cron: '0 0 * * 1'  # Every Monday at midnight

jobs:
  generate-report:
    runs-on: ubuntu-latest
    steps:
      - name: Install doover-cli
        run: pip install doover-cli

      - name: Configure credentials
        run: |
          doover configure-token \
            --token ${{ secrets.DOOVER_TOKEN }} \
            --agent-id ${{ secrets.AGENT_ID }} \
            --base-url https://my.doover.com

      - name: Generate report
        run: |
          doover report compose \
            --agent-ids "${{ secrets.REPORT_AGENTS }}" \
            --agent-names "${{ secrets.REPORT_NAMES }}"

      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: weekly-report
          path: /tmp/doover_report_output/