Report jobs

Edition: Commercial

Report Factory and the durable runner are part of the Commercial edition (authenticated package index, latest published release 2.3.0). Community (MIT, public PyPI, 2.0.9) does not include them. See Install for the difference between the editions.

Report Factory accepts a versioned, host-neutral job envelope. The same document can be preflighted by wolfxl-report-factory or scheduled by the durable wolfxl-runner; hosts do not need to know the Python request class for the selected recipe.

{
  "schema_version": 1,
  "kind": "report_job",
  "workflow": "monthly_operating_review",
  "request": {
    "schema_version": 1,
    "request_id": "august-review",
    "template_path": "monthly-review.xlsx",
    "outputs": {
      "xlsx": "out/august-review.xlsx",
      "pdf": "out/august-review.pdf"
    },
    "transactions": [
      {
        "period": "Aug",
        "region": "West",
        "account": "Services",
        "revenue": 125.0,
        "expense": 70.0
      }
    ],
    "kpis": {"total_revenue": 125.0, "target_revenue": 150.0},
    "periods": [{"label": "Aug", "revenue": 125.0}],
    "max_rows": 1000,
    "max_columns": 5,
    "logo": null,
    "data_sheet": "Data"
  }
}

The envelope schema and the recipe request schema are intentionally versioned separately. Unknown envelope fields, workflow identifiers, kinds, and schema versions fail closed before a workbook is opened. Workflow dispatch is closed and engine-owned; a request cannot import or execute a caller-named Python function.

Single-job execution

wolfxl-report-factory preflight report-job.json
wolfxl-report-factory generate report-job.json

For compatibility, these commands still accept the original unwrapped monthly_operating_review request document. New durable integrations should write the explicit envelope.

Durable batches

Batch schema version 2 stores report-job envelopes:

{
  "schema_version": 2,
  "policy": "per_job",
  "max_concurrency": 4,
  "items": [
    {
      "schema_version": 1,
      "kind": "report_job",
      "workflow": "monthly_operating_review",
      "request": {"...": "same request fields as above"}
    }
  ]
}

Batch schema version 1 remains readable and resumable. It contains unwrapped monthly operating review request objects in items. The runner promotes each one to a report job in memory and persists new immutable plans with the generic envelope; it never rewrites an existing version 1 run.

The existing MonthlyOperatingReviewRequest, preflight_monthly_operating_review, generate_monthly_operating_review, and run_monthly_operating_review Python APIs remain supported as the compatibility recipe surface.