An introduction to pdfXFA

Thu - 03/02/2017

pdfXfa is the successor to XFA Worker. It allows you to process and finalize dynamic forms by automating form filling and later flattening for easy use and security.

Share this article

pdfXfa is the successor to XFA Worker. It allows you to process and finalize dynamic forms by automating form filling and later flattening for easy use and security. pdfXFA offers all of the same functionality as XFA Worker, but also offers a convenient API.

To get started with pdfXFA, read on!

Load your License Key

Before we begin we'll need to load the license file. This is done using our license key library. Make sure to use version 2 and higher. These version are meant to be used in tandem with iText 7 products, while versions 1.x.y are meant to be used with iText 5.


If this throws an exception, then your key is either invalid or corrupt. Either way, contact us to resolve this issue. If it didn't throw an exception, your key has been loaded and it should work perfectly.

You can acquire a trial license key on our trials page


Flattening a form means that you remove the functionality of the form but keep the visual layout intact. This can be seen as a way to finalize a form. You can use pdfXFA to flatten your files. All you need to provide is the input XFA form and an OutputStream. We provide a convenience class to make it easier for you to flatten your files.

final FileInputStream xfaInputStream = new FileInputStream("path/to/data.xml");
final FileOutputStream pdfOutputStream = new FileOutputStream("path/to/output.pdf");

final XFAFlattener xfaFlattener = new XFAFlattener();
xfaFlattener.flatten(xfaInputStream, pdfOutputStream, properties);

There are ways to customize this process. This will be done through the use of XFAFlattenerProperties.

XFA Flattener Properties

pdfXfa allows you to customize the mapping process in many ways. Customization is done through the XFAFlattenerProperties class. This post will try to give you a brief overview of the more important options.


pdfXfa can flatten to PDF/A compliant files. To do so, you'll need to set a few things on the XFAFlattenerProperties object.

  • PdfAConformanceLevel

  • OutputIntent

Normally you need to set the tagging and the XMP Metadata, but if you chose a PdfAConformanceLevel that needs tagging, pdfXfa will automatically enable it for you. Metadata is always turned on for PDF/A. If you don't require PDF/A, but you do want Metadata or tagged PDF, then you can still turn them on.

XFAFlattenerProperties properties = new XFAFlattenerProperties()
                .setOutputIntent(new FileInputStream(icc), ocId, oc, registryName, ocInfo);

XFAFlattener xfaFlattener = new XFAFlattener();
xfaFlattener.flatten(xfaInputStream, pdfOutputStream, properties);

Triggering Javascript events

XFA Forms can contain JavaScript. pdfXFA can execute JavaScript inside XFA forms when flattening. There is one catch and that is that you can't declare which specific event you want to trigger. You can only provide pdfXFA with the trigger you wish to activate.

XFAFlattener xfaFlattener = new XFAFlattener();

List javaScriptTriggers = new ArrayList();


xfaFlattener.flatten(new FileInputStream("path/to/input.pdf"), new FileOutputStream("path/to/output.pdf"));

Font customization

Sometimes you'd like to map the fonts used in an XFA form onto other fonts that are available on the system. pdfXFA provides an easy to map these fonts onto each other. You provide the XFAFlattener a Map containing entries mapping one font onto an other:

XFAFlattener xfaFlattener = new XFAFlattener();

Map fontMapping = new HashMap();
fontMapping.put("font1", "font2");

XFAFlattenerProperties properties = new XFAFlattenerProperties();
properties.setXfaFontSettings(new XFAFontSettings(fontMapping));

xfaFlattener.flatten(new FileInputStream("path/to/input.pdf"), new FileOutputStream("path/to/output.pdf"), properties);

Other settings like font embedding or the path to the fonts folder can be set on the XFAFontSettings object.


As you have noticed, you can can flatten your XFA files quite easily using pdfXFA's convenience API. Want to find out more and/or try pdfXFA for free? Than click here.


Still have questions? 

We're happy to answer your questions. Reach out to us and we'll get back to you shortly.

Contact us
Stay updated

Join 11,000+ subscribers and become an iText PDF expert by staying up to date with our new products, updates, tips, technical solutions and happenings.

Subscribe Now