101 lines
3.3 KiB
Markdown
101 lines
3.3 KiB
Markdown
# Populating Fillable PDF Forms
|
|
|
|
<purpose>
|
|
After collecting data via Chatfield interview, populate fillable PDF forms with the results.
|
|
</purpose>
|
|
|
|
## Process Overview
|
|
|
|
```plantuml
|
|
@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:
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
[
|
|
{"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):
|
|
|
|
```bash
|
|
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>
|