Generate Excel / Word / PDF Analysis Report
kobo_build_reportGenerate analytical Excel workbooks, Word reports, or PDFs from KoboToolbox form submissions, with computed tables, charts, and written analysis.
Instructions
Produce finished deliverables from a form's data: an analytical Excel workbook, a written Word report, and/or a PDF — saved to disk.
YOU write the analysis (objective, summary, findings, section commentary, recommendations); the server computes every figure from the real submissions, so the numbers in the deliverable always match the data. Never type counts or percentages into 'custom' tables that the server can compute for you — use the directives below instead.
Each section carries your prose plus 'visuals', declared as directives:
{source:"frequencies", column:"crop_health", chart_kind:"pie"} — counts/% per answer, as table and chart
{source:"numeric_summary", column:"plot_size"} — mean/median/std/quartiles table
{source:"crosstab", row_column:"region", col_column:"crop_health", metric:"count"} — contingency table + grouped chart
{source:"custom", columns:[...], rows:[[...]]} — only for figures the server cannot derive Each accepts: show ('table'|'chart'|'both'), chart_kind, title, note (a "how to read this" caption), top_n.
What the Excel workbook contains: a summary sheet (objective, executive summary, findings, recommendations), one sheet per section with tables and NATIVE, editable Excel charts, a cross-tab sheet, the cleaned data as a real Excel Table named 'DonneesKobo' (select it, then Insert > PivotTable to build your own pivot in two clicks), and a data-quality sheet.
Note on pivot tables: cross-tabs are delivered as computed tables, not as live PivotTable objects — no open-source library can create those. The named Excel Table above is there precisely so you can add one yourself instantly.
Args:
uid (string): the form's asset uid
objective (string): the analytical question this report answers
formats (array): any of 'xlsx', 'docx', 'pdf'
title, methodology, summary, findings[], recommendations[]: your written content
sections[]: {heading, text, visuals[]}
file_name (string, optional): base name without extension
query (string, optional): Mongo-style filter restricting the analysis
Returns: the full path of each generated file.
Run kobo_load_data first so you know which questions exist and what shape the data is in.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | Asset uid of the form (from kobo_list_forms) | |
| query | No | Optional Mongo-style filter applied server-side, e.g. '{"region":"Sud-Ouest"}' or '{"_submission_time":{"$gte":"2026-01-01"}}' | |
| title | No | Report title. Defaults to 'Analyse — <form name>'. | |
| formats | No | Deliverables to produce: 'xlsx' analytical workbook, 'docx' written report, 'pdf' of that report | |
| summary | No | Executive summary: the headline answer to the objective | |
| findings | No | Key findings, one per bullet, each citing a figure | |
| max_rows | No | How many submissions to pull. Defaults to 50000, which protects against dragging a huge project into memory; pass a higher value explicitly to analyse a project larger than that. | |
| sections | Yes | Body of the report: your analysis, section by section, with the tables and charts to compute | |
| file_name | No | Base file name without extension. Defaults to a slug of the form name and date. | |
| objective | Yes | The analytical objective this report answers, in the user's own terms | |
| methodology | No | How the analysis was conducted, including any filters applied | |
| recommendations | No | Actionable recommendations that follow from the findings |