xls_doc/docs/digital-employee-runbook.md

Digital Employee Runbook

This file is the minimal operating contract for calling docfill from a digital employee, scheduler, or shell script.

Inputs

Each run needs:

• A task.json config file.
• A data source: .xlsx or SQLite .db.
• Optional business filters in filter.equals.
• A template: .docx or .xlsx.
• An output path pattern in task.json.

Paths inside task.json are resolved from the config file directory.

Use one task.json per business task. Use --var for values that change per run, such as date, ticket number, person, or batch.

Command

docfill run -c /path/to/task.json --var date=2026-06-18

Use repeated --var key=value arguments for runtime values:

docfill run -c task.json --var date=2026-06-18 --var ticket_no=GD-002

Priority:

row data > CLI --var > task.json vars

CLI variables override vars in task.json. The selected row data overrides both when rendering templates and output paths.

If task.json has a filter:

"filter": {
  "equals": {
    "日期": "{{date}}",
    "工单编号": "{{ticket_no}}"
  },
  "expect": "one"
}

then the command:

docfill run -c task.json --var date=2026-06-18 --var ticket_no=GD-002

selects the row where 日期 = 2026-06-18 and 工单编号 = GD-002.

Use --verbose only when diagnosing a failed or suspicious run:

docfill run -c task.json --var date=2026-06-18 --var ticket_no=GD-002 --verbose

Success

Exit code 0.

Stdout contains generated files:

generated 2 file(s)
- /path/to/out/report_张三.xlsx
- /path/to/out/report_李四.xlsx

Failure

Exit code 1 means the task ran but failed.

Exit code 2 means the command line was invalid.

Errors are written to stderr with the docfill: prefix:

docfill: [TEMPLATE_FIELD_MISSING] render row 1: missing template field "done"
hint: Add column "done" to the data source or pass --var done=...
context: field=done template=/path/template.docx

Verbose logs are also written to stderr:

log: load config path=/path/task.json
log: read data type=excel path=/path/data.xlsx
log: read data type=excel path=/path/data.xlsx rows=3
log: filter rows=3 matched=1 expect=one
log: render row=1 output=/path/out/work_order_2026-06-18_GD-002.docx

Error Codes

CLI_USAGE

The command line is invalid.

CONFIG_READ

The config file cannot be read.

CONFIG_PARSE

The config file is not valid JSON.

CONFIG_VALIDATE

The config is missing required fields or uses unsupported values.

DATA_EXCEL

Excel data cannot be opened or read.

DATA_SQLITE

SQLite data cannot be opened, queried, or parameterized.

DATA_EMPTY

The data source returned no rows.

DATA_FILTER_FIELD

The filter references a field that is not in the data.

DATA_FILTER_VALUE

The filter references a variable that was not provided.

DATA_FILTER_NO_MATCH

The filter matched no rows.

DATA_FILTER_MULTI_MATCH

The filter expected one row but matched multiple rows.

TEMPLATE_OPEN

The template file cannot be opened or inspected.

TEMPLATE_FIELD_MISSING

The template references a field that is not available.

TEMPLATE_UNRESOLVED

The rendered file would still contain a {{field}} placeholder.

OUTPUT_EXISTS

The output file exists and overwrite is not enabled.

OUTPUT_WRITE

The output directory or file cannot be written.

INTERNAL

An unexpected unclassified error occurred.

Common Errors

missing template field

The template contains a {{field}} that is not present in data, vars, or CLI --var.

output already exists

The output file exists and output.overwrite is not true.

missing sqlite params field

A SQLite query parameter such as {{date}} was not provided.

filter matched no rows

Check filter.equals, --var values, or the source table contents.

filter matched N rows but expected one

Add another filter condition or clean duplicate rows in the source table.

filter field is not in data

Check Excel headers or SQLite query column names.

unresolved placeholder

The rendered document still contains {{field}}. Check the source data value and the template.

Build

bash scripts/build.sh

The local build output is:

dist/docfill-darwin-arm64

Smoke Test

bash scripts/smoke.sh

Smoke test builds a temporary binary, generates temporary example files, runs example configs including the filter case, and checks generated outputs.