Populating Fillable PDF Forms

After collecting data via Chatfield interview, populate fillable PDF forms with the results.

Process Overview

@startuml Populating-Fillable
title Populating Fillable PDF Forms
start
:Parse Chatfield output;
:Read <basename>.form.json for metadata;
:Create <basename>.values.json;
repeat
  :Validate .values.json
  (see validation checklist);
  if (All checks pass?) then (yes)
  else (no)
    :Fix .values.json;
  endif
repeat while (All checks pass?) is (no)
->yes;
:Execute fill_fillable_fields.py;
:**✓ PDF POPULATION COMPLETE**;
stop
@enduml

Process

1. Parse Chatfield Output

Run Chatfield with --inspect for a final summary of all collected data:

python -m chatfield.cli --state='<basename>.chatfield/interview.db' --interview='<basename>.chatfield/interview.py' --inspect

Extract field_id and the proper value for each field.

2. Create `.values.json`

Create <basename>.values.json in the <basename>.chatfield/ directory with the collected field values:

[
  {"field_id": "name", "page": 1, "value": "John Doe"},
  {"field_id": "age_years", "page": 1, "value": 25},
  {"field_id": "age_display", "page": 1, "value": "25"},
  {"field_id": "checkbox_over_18", "page": 1, "value": "/1"}
]

Value selection priority:

CRITICAL: If a language cast exists for a field (e.g., .as_lang_es, .as_lang_fr), always prefer it over the raw value
This ensures forms are populated in the form's language, not the conversation language
The language cast name matches the form's language code (e.g., as_lang_es for Spanish forms)
Only use the raw value if no language cast exists

Boolean conversion for checkboxes:

Read .form.json for checked_value and unchecked_value
Typically: "/1" or "/On" for checked, "/Off" for unchecked
Convert Python True/False → PDF checkbox values

3. Validate `.values.json`

Before running the population script, validate the .values.json file against the validation checklist below:

Verify all field_ids from .form.json are present
Check checkbox values match checked_value/unchecked_value from .form.json
Ensure numeric fields use numbers, not strings
Confirm language cast values are used when available

If validation fails, fix the .values.json file and re-validate until all checks pass.

4. Populate PDF

Once validation passes, run the population script (note, the scripts directory is relative to the base directory for this skill):

python scripts/fill_fillable_fields.py <basename>.pdf <basename>.chatfield/<basename>.values.json <basename>.done.pdf

## Validation Checklist

<validation_checklist>
**Missing fields:**
- Check that all field_ids from `.form.json` are in `.values.json`
- Verify field_id spelling matches exactly

**Wrong checkbox values:**
- Check `checked_value`/`unchecked_value` in `.form.json`
- Common values: `/1`, `/On`, `/Yes` for checked; `/Off`, `/No` for unchecked

**Type errors:**
- Ensure numeric fields use numbers, not strings: `25` not `"25"`
- Ensure boolean checkboxes use proper values from `.form.json`

**Language translation (for translated forms):**
- Ensure language cast value is used when it exists (e.g., `as_lang_es` for Spanish forms)
</validation_checklist>

3.3 KiB Raw Blame History