Field Management & Editing

Inspect and correct the field definitions extracted from any PDF form

Overview

After extract_pdf_components() processes a PDF, each detected field is stored with its coordinate record: {page, x0, y0, x1, y1, field_id}. These coordinates come directly from the AcroForm widget annotations in the PDF. Field Management exposes these records through a visual editor — built on PDF.js 5.0.375 inside an Angular SPA located at wwwroot/templates/fill-forms/ — where each field appears as an overlay rectangle on the rendered page.

Fields are classified at extraction time into two groups. TEXT_FIELD_TYPES covers ["Text", "ComboBox", "Time", "Date", "Number"]; CHECKBOX_FIELD_TYPES covers ["CheckBox", "RadioButton"]. This classification drives both rendering (text input vs. checkbox toggle) and the AI fill strategy. When a user edits a field's boundary or type in the visual editor, the change updates the stored coordinate data, and write_widgets.py rewrites the corresponding AcroForm widget annotation in the PDF file itself so that the output PDF remains a valid fillable document.

Key Capabilities

• Visual Field Overlay: PDF.js renders the form page; field bounding boxes from {x0, y0, x1, y1} are drawn as overlays, making it possible to see exactly which area each field covers
• Field Type Editing: Change a field's classification between TEXT_FIELD_TYPES (Text, ComboBox, Time, Date, Number) and CHECKBOX_FIELD_TYPES (CheckBox, RadioButton)
• Coordinate Adjustment: Drag or resize a field overlay to update its {x0, y0, x1, y1} values; changes are written back via write_widgets.py
• Add Missing Fields: Draw a new rectangle on the page to create a field record with a user-assigned name and type; the widget is injected into the PDF by write_widgets.py
• Delete False Detections: Remove a field record to eliminate AcroForm widgets that were incorrectly included in the original PDF
• Validation Rules: Attach format constraints (SSN pattern XXX-XX-XXXX, phone, email, ZIP) and numeric range limits (min/max values, character length) to individual fields
• Required Field Enforcement: Mark fields as always required, conditionally required, or optional; the fill interface enforces this before allowing session submission
• Default Values: Assign a fixed or calculated default; the fill engine populates the field unless overridden by source data
• Tab Order: Set the keyboard navigation sequence across fields on a page independent of their visual position
• Field Descriptions: Add a tooltip or instruction string that appears in the fill interface next to the field

How It Works

1. Open Field Editor: Navigate to a form's detail page and click "Manage Fields". The Angular SPA at wwwroot/templates/fill-forms/ loads the PDF via PDF.js 5.0.375 and overlays each field's bounding box using its stored {page, x0, y0, x1, y1} coordinates.

2. Review Detected Fields: Every field extracted by extract_pdf_components() appears as a colored rectangle. The field name and type (from TEXT_FIELD_TYPES or CHECKBOX_FIELD_TYPES) are shown in a sidebar list alongside the visual overlay.

3. Edit Field Properties: Click a field overlay to open its property panel:

   • Name: Edit the field name as it appears in form records and API responses
   • Type: Switch between Text, ComboBox, Time, Date, Number, CheckBox, or RadioButton
   • Coordinates: Drag the overlay corners to adjust x0, y0, x1, y1; the page index stays fixed
   • Required: Set to always required, conditionally required, or optional
   • Validation: Choose a built-in pattern (SSN, EIN, phone, email, ZIP, date) or enter a custom regex
   • Default Value: Enter a literal value or a field-reference expression
   • Description: Enter tooltip text displayed during filling

4. Add Missing Fields: Click "Add Field", then draw a rectangle on the PDF page. Assign a name and select a type from TEXT_FIELD_TYPES or CHECKBOX_FIELD_TYPES. The new field record is saved with its {page, x0, y0, x1, y1, field_id} coordinates.

5. Delete Incorrect Fields: Select a field overlay and click "Delete". The field record is removed from the database and the corresponding widget is excluded from output PDFs generated by write_widgets.py.

6. Save Changes: Clicking "Save" persists the updated coordinate data and triggers write_widgets.py to rewrite AcroForm widget annotations in the stored PDF, keeping the file and the database record consistent.

Use Cases

Field management is used when extraction results need correction for a specific form. A healthcare organization processing CMS-1500 insurance claims may find that the AI classified certain diagnosis-code boxes as Text when they are ComboBox fields; correcting the type ensures the AI fill engine uses list-selection logic instead of free-text generation. A law firm working with multi-party agreements may need to resize overlapping field boundaries where two adjacent signature lines have bounding boxes that touch. An HR department processing I-9 employment eligibility forms can add a required-field rule to the "List A document number" field so that batch fill sessions cannot complete without that value present. For W-4 withholding forms, adding a numeric range validation to the "Additional withholding" field (minimum $0, must be a whole number) catches data entry errors before the PDF is written.

Automated Field Validation & Error Checking

For compliance-heavy documents where data quality is paramount, field-level validation rules can be configured per field in the visual editor. Validation runs at fill time — before write_widgets.py writes the output PDF — and blocks submission if any rule is violated.

Types of Validation

1. Format Validation

Attach a built-in pattern or custom regex to any text field:

• SSN: XXX-XX-XXXX — blocks submission if hyphens are missing or digit count is wrong
• EIN: XX-XXXXXXX
• Phone: (XXX) XXX-XXXX or XXX-XXX-XXXX
• Email: RFC 5322 format check
• ZIP: 5-digit or ZIP+4 format
• Date: Enforce MM/DD/YYYY, YYYY-MM-DD, or other explicit patterns per field
• ICD-10: A00.0–Z99.9 range check for CMS-1500 diagnosis code fields
• CPT: 5-digit numeric for procedure code fields
• Custom Regex: Any pattern for proprietary codes (employee IDs, case numbers, USCIS receipt numbers in SRC-YY-NNN-NNNNN format)

2. Range & Length Validation

• Numeric Range: Min and max values — e.g., age 0–120, withholding amount ≥ 0
• Character Length: Minimum and maximum character counts per field
• Date Range: Constrain a date field to past only, future only, or a specific window

3. Cross-Field Validation

• Date Ordering: Employment end date must be after start date
• Sum Checks: Total income fields must equal the sum of source income fields
• Conditional Required: Mark a field required only when another field has a specific value — e.g., "Spouse SSN" required when filing status is "Married Filing Jointly" on a W-4

4. Required Field Enforcement

Fields marked required block session submission if empty. Conditionally required fields enforce the rule only when their trigger condition is met. The fill interface displays which fields are still incomplete before allowing the user to generate the output PDF.

Compliance-Specific Validation

Healthcare (CMS-1500, UB-04)

• NPI: 10-digit with Luhn algorithm checksum
• ICD-10 Diagnosis Codes: Format A00.0–Z99.9
• CPT Procedure Codes: 5-digit numeric
• Date of Service: Cannot be a future date

Government (I-9, I-485, W-4)

• A-Number (Alien Registration): 7–9 digits with leading zeros
• USCIS Receipt Number: 13-character alphanumeric (SRC-YY-NNN-NNNNN)
• SSN: Format check plus not-all-zeros validation

Financial (W-9, 1003 Mortgage Application)

• EIN / SSN: Correct format for the TIN type selected by checkbox
• ABA Routing Number: 9-digit with checksum
• Loan Amount: Numeric, positive, within lender-configured range

Benefits

• Accurate Output PDFs: Correcting {x0, y0, x1, y1} coordinates and field types before filling prevents data from landing in the wrong area of the output file
• Data Quality at Source: Validation rules catch formatting errors (missing hyphens in SSN, wrong date format) before write_widgets.py writes the output, eliminating resubmission cycles
• Persistent Corrections: Field edits apply to the form template, so every future session and batch run benefits without repeating corrections
• Type-Accurate Fill Logic: Correctly classifying CheckBox vs. Text fields ensures the AI uses the right fill strategy — checkbox toggling vs. text generation — for each field
• Compliance Enforcement: Required-field rules and format constraints ensure that regulated forms like I-9, CMS-1500, and W-4 cannot be submitted with missing or malformed data

Security & Privacy

Data is scoped to workspaceId and protected via the shared JWT authentication middleware running in both the .NET and Python service layers. Field edits — including coordinate changes and validation rules — apply only to the workspace's copy of the form template. The write_widgets.py rewrite affects only the stored PDF associated with that workspace's form record. Field changes do not propagate to other workspaces, even if those workspaces share the same field-hash for a common government form. Only workspace members with the appropriate role can access the field editor.

Common Questions