USCIS AcroForm Field Migrator

A browser-only utility for migrating the interactive AcroForm field layer from an older USCIS PDF edition to a newer USCIS PDF.

USCIS frequently updates form editions. The visible PDF pages may change, but the underlying AcroForm layer still needs to be inspected, compared, migrated, and verified. This tool helps move that field layer forward without rebuilding every field by hand.

What it does

The migrator takes two PDFs:

1. PDF-1: an older USCIS edition with the AcroForm fields you want to preserve.
2. PDF-2: a newer USCIS edition that should receive those fields.

It extracts the field names, types, widgets, page numbers, rectangles, flags, values, default appearances, and page geometry from PDF-1. It can then transplant the source AcroForm layer into PDF-2 and verify that the generated PDF still contains the expected fields at the expected page coordinates.

Important: this tool does not work directly with the PDFs USCIS provides, because those files are typically XFA forms. In our workflow, we manually convert the USCIS PDF into an AcroForm PDF first, then use this tool on the converted AcroForm version.

Why it exists

This project was built by the founder of Fillvisa, an immigration form workflow product. It is something we use internally in the Fillvisa workflow to keep form automation reliable as USCIS releases new PDF editions.

The broader Fillvisa open-source project is available at athos2113/fillvisa-os.

Why v2.3 matters

Earlier versions recreated fields with pdf-lib's high-level form API and copied selected properties back onto the new fields. That preserved many important details, but pdf-lib could still create its own field/widget structure and regenerate text appearances.

v2.3 uses a raw AcroForm transplant instead. It deep-copies the source PDF's actual /AcroForm object graph into PDF-2 rather than recreating fields with calls such as createTextField() or createCheckBox().

This preserves source PDF objects such as:

• the /Fields tree;
• merged field/widget structures;
• /DA default appearance strings;
• /DR resources and source font resource names;
• /Ff, /MaxLen, /Q, /MK, /BS, /Border, /F, and related dictionary entries;
• the exact presence or absence of /AP appearance streams;
• checkbox and radio On/Off artwork;
• exact widget /Rect values.

Only the widget page relationship is intentionally changed so that copied widgets point to the matching pages in PDF-2.

How it works

The app runs entirely in the browser using pdf-lib.

At migration time, it:

1. loads PDF-1 and PDF-2;
2. temporarily removes /P page references from source widgets so the old page tree is not imported;
3. deep-copies the source /AcroForm into PDF-2 with PDFObjectCopier;
4. restores PDF-1's in-memory /P references;
5. finds copied fields by source manifest name and widget index;
6. sets each copied widget's /P reference to the corresponding PDF-2 page;
7. restores the exact source /Rect;
8. inserts copied widget annotation references into the target page /Annots arrays;
9. saves the generated PDF with updateFieldAppearances: false;
10. reopens the output and verifies field placement and low-level fidelity.

Usage

Open index.html in a browser.

Then:

1. Manually convert the USCIS-provided XFA PDFs into AcroForm PDFs.
2. Upload the old converted AcroForm PDF as PDF-1.
3. Review the extracted field manifest, table, JSON, or CSV export.
4. Upload the new converted AcroForm PDF as PDF-2.
5. Keep Replace existing AcroForm fields in PDF-2 enabled for normal migrations.
6. Optionally enable Copy current values from PDF-1 if you want source values retained.
7. Click Insert fields into PDF-2.
8. Review the migration verification report.
9. Download the generated PDF.

The repository also includes about.html, a short public-facing project page.

Verification

The migration report checks:

• raw-transplanted field and widget counts;
• widget /P references remapped;
• exact /Rect values restored;
• annotations attached to PDF-2 pages;
• maximum coordinate delta;
• AcroForm /DA preservation;
• copied /DR resources;
• per-field /DA and per-widget /AP presence fidelity.

Privacy

PDF parsing and migration happen locally in the browser. The app itself does not upload selected PDFs to a server.

The page loads pdf-lib 1.17.1 from a CDN, so that CDN must be reachable unless you modify the project to serve the dependency locally.

Scope and caveats

• This tool is for AcroForm PDFs. It will not work directly with USCIS-provided XFA PDFs.
• Convert USCIS XFA PDFs into AcroForm PDFs before using this utility.
• XFA data is removed during migration because pdf-lib does not support XFA editing.
• PDF-2 must contain the corresponding page numbers for copied widgets to be placed.
• Page geometry warnings are shown when sizes, origins, or rotation differ.
• Exact source coordinates do not compensate for USCIS moving printed content between editions.
• PDF-2 page content is not replaced or altered.
• Manual adjustment may still be needed when the visible form layout changed between editions.