Research who/what generates each form PDF + overflow page

[mackhowell-nava]

Based on our inventory of form PDFs and overflow pages here: https://app.mural.co/t/departmentofveteransaffairs9999/m/departmentofveteransaffairs9999/1726591426989/547c59766d621518292bfe86530a1b5608419234?sender=uf3d2a9320ea286a502077710

Priorities of PDFs

• Shannon indicated the 526 overflow problem is of particular frustration
• Pensions form/overflow as well -- because that team is stretched.
• Note: it seems more realistic to make changes to the overflow (with less buy-in), and changes to forms might require more buy-in or cross-team communication.
• For now, we can think of all other forms as lower priority until we understand what changes might be across all forms

We want to understand:

• How each form PDF + overflow page is generated
• Where does the logic live?
• What team owns this logic?
• Any signal on the best way to make changes? Should our approach be:
  • 1) Make code changes ourselves or...
  • 2) Ask these teams to make the changes for us

[nanotone]

Third-party Ruby libraries

PdfForms is an open source Ruby interface to PDFtk, a popular PDF toolkit. This pairing provides generic PDF operations -- filling out fields, splitting or combining documents, etc. PdfForms / PDFtk is best for working with existing documents along the lines of what you'd do with Acrobat Reader or OSX Preview.

Making modifications to the capabilities of either is most likely out of the question.

Prawn is a pure Ruby library that creates PDFs from scratch, using basic drawing and text-writing operations. Prawn is best for authoring new documents, along the lines of a presentation slideshow editor. Prawn-markup is an add-on library that enables some HTML-to-PDF conversion (even though Prawn discourages this).

Note: on the RRD project, ARSD's were created by Prawn / Prawn-markup.

Making modifications to Prawn / Prawn-markup is not exactly a breeze, but there is precedent on our very own team and the maintainer has been pretty receptive.

Shared Ruby code in vets-api

PdfFill is the primary utility used by the various parts of VA.gov for PDF generation. It:

• provides a way to translate JSON saved from VA.gov form UI to fields on "paper" forms,
• uses the third-party library PdfForms to fill out those fields,
• determines which data will end up on overflow pages
• uses the third-party library Prawn to create overflow pages, and
• combines the filled-out pages with the overflow pages.

PdfFill has two sibling utilities organized under PdfUtilities:

• DatestampPdf adds a date/time stamp to a PDF. Note that VSRs rely on a particular location/formatting of the stamp to see that a PDF was generated by VA.gov.
• PDFValidator verifies that PDFs don't exceed a file size or page limit, aren't password-protected, etc.

Forms that use vets-api PdfFill

The vast majority of forms generated by VA.gov use PdfFill, including 527 (pensions), 686c (dependents), and 21-22 (POA). Importantly, 526 does not use PdfFill; see the next section below.

• lib/pdf_fill/forms contains code, organized by form name, to translate form data into PDF fields.
  • The pdfs subdirectory contains blank forms to be filled out
  • Note that a form existing in this subdirectory doesn't imply active use, and that forms not in this subdirectory can still use PdfFill and the overflow page generator.
• To see examples of what filled-out forms and overflow pages look like, check the test fixtures directory -- although the supplied data is often non-realistic.
• LH Benefits Claims API keeps its code and resources in a separate directory
• The pensions team's PDF code has their own directory as well, even though the pensions app is a part of VA.gov rather than a separate LH API.

Non-Ruby PDF code outside of vets-api

526 PDFs are generated by an LHDI app, unsurprisingly named Form 526EZ PDF Generator, which is maintained by Lighthouse's #team-firefly. It is called by the LH Benefits Claims API but is not itself a publicly-available LH API. The app is written in Java and uses the Java-based Apache PDFBox library for actually working with PDF files. We are unlikely to contribute any code to this, but the LH team will probably be open to requests.

Takeaways

Nearly all VA.gov-generated forms are generated by a vets-api library called PdfFill, which handles filling out fields into existing blank PDFs, as well as creating overflow pages. There are some minor inconsistencies (but likely not visual) in how each team calls PdfFill.

I expect that modifications to PdfFill to support our desired visual changes would need approval both from the platform team, since PdfFill code is shared by so many VFS teams, as well as from teams that maintain any affected forms. We can likely work with the platform team to engineer a slow-release of visual changes to affect one form at a time, but on the plus side, if they're successful it should be easy to roll improvements out to additional forms.

Any modifications to the 526 PDF will have to go through the LH team that maintains the 526 PDF generator service, which doesn't share any code with the others.