Migrating off iText, and the licensing question underneath it

What ports and what does not

The data layer. iText's higher-level document model, with Paragraph, Table and Cell objects, is closer to a document than a canvas, so the structure reads across to markup reasonably well. The low-level content stream code does not. Two things are specific to this migration. iText is dual licensed, with an open source licence that has obligations many organisations cannot accept and a commercial licence that costs money, and that is often what prompts the move, which means the deadline may be commercial rather than technical. And iText codebases frequently also do PDF manipulation, form filling, merging and stamping, which is a different capability from rendering: merge exists here at /v1/pdf/merge, and the rest does not.

What the call becomes

Document, PdfWriter and the add calls become a POST to /v1/pdf with html. Page size and margins, set on the Document, become options.format and options.margin. Page event handlers, which iText used for headers, footers and watermarks, become options.header_html and options.footer_html or CSS. Any form filling, stamping or field manipulation has no counterpart and needs a separate tool in the pipeline, which is the part of the migration to scope before starting.

Side by side

The old shape and the new one, with the parts that have no counterpart called out in comments rather than quietly omitted.

// Before
Document document = new Document(PageSize.A4, 40, 40, 50, 50);
PdfWriter writer = PdfWriter.getInstance(document, out);
writer.setPageEvent(new HeaderFooter());   // draws furniture per page
document.open();
document.add(new Paragraph("Invoice", headingFont));
PdfPTable table = new PdfPTable(new float[] { 220f, 80f, 80f });
table.setHeaderRows(1);
document.add(table);
document.close();

// After
String body = mapper.writeValueAsString(Map.of(
    "html", html,
    "options", Map.of(
        "format", "A4",
        "margin", Map.of("top", "50pt", "bottom", "50pt",
                         "left", "40pt", "right", "40pt"),
        "header_html", "<div style=\"font:bold 12pt sans-serif\">Invoice</div>")
));

/* Scope this before starting, because it is not a rendering feature:
     merging documents        -> POST /v1/pdf/merge
     filling AcroForm fields  -> no counterpart, needs another tool
     stamping an existing PDF -> no counterpart
     digital signatures       -> no counterpart
   An iText codebase that only renders is a straightforward migration.
   One that also manipulates existing PDFs is two projects. */

The CSS delta, in both directions

What the old engine accepted that a current one does not, and what it refused that a current one wants. The second direction is the one people forget, and it is where the value of the migration is.

• Nothing to migrate. The Document constructor's margins are in points and transcribe directly, and PdfPTable's float column widths become CSS widths.
• setHeaderRows becomes a thead, which repeats on every page for the same reason.
• Page event handlers become the header and footer options, which is a narrowing: an event handler could draw anywhere on the page and the header and footer are two regions.
• Everything CSS offers is new, since the old document had no stylesheet at all.

What changes without anything erroring

The dangerous list. Each of these produces a different document and no diagnostic, so none of them are caught by a test that only checks the render succeeded.

• Everything visual, because it is a rewrite.
• Page count.
• Anything a page event drew away from the top and bottom edges.
• Any PDF manipulation the codebase did alongside rendering, which stops happening rather than failing.

What to diff before cutting over

Before diffing anything, inventory what the codebase does with PDFs besides creating them. Search for form field access, stamping and signing. That inventory decides whether this is one project or two, and it is much better known at the start.

The one thing that always breaks

The page event handler. It is registered on the writer, it runs on every page, and it is the mechanism iText codebases use for letterheads, footers, watermarks and page numbers all at once. Removing the writer removes all of it together, and because it is registered rather than called it does not appear anywhere in the document-building code somebody reads to plan the work.

Frequently asked

Other migrations

The nearest neighbours first, then others that started from the same kind of tool, because the model matters more than the language.