Some test text!

Search
Hamburger Icon

Ruby / Guides / Import form data into PDF

Merge Form Data File (FDF or XFDF) to PDF Forms in Ruby

Depending on the type and origin of the XFDF or FDF, one of the following methods should be used:

  1. Replace all annotations in the PDF document with the annotations from XFDF or FDF using FDFUpdate API.
  2. Add all annotations from XFDF or FDF to the PDF document using FDFMerge API (potentially introducing duplicates).
  3. Merge XFDF directly into the PDF document using MergeXFDF API (introduced in PDFNet 9.2)
  • In order for the API to function, annotations in XFDF should be named (see below)
  • MergeXFDF API is the recommended solution for command XFDF files

See below, which API is best suited to the given use case.

Replacing all annotations in the document

This is a 2-step process: first XFDF needs to be converted into FDF, then FDF needs to be passed to FDFUpdate API. As a result of the import operation, the PDF document will have all annotations from XFDF and no other:

  1. Annotations that are in XFDF only will be added
  2. Annotations that are both in XFDF and PDF will be modified as needed
  3. Annotations that are only in PDF and not in XFDF will be removed

FDFUpdate API works best for the scenarios like restoring annotations from a backup. Also it would be a good option when bringing in annotations creating in WebViewer, i.e. use FDFUpdate to import XFDF written by WebViewer.

Note, FDFUpdate should be used only for the full XFDF files exported by Apryse API (Apryse SDK or WebViewer) from the same document. This method is not applicable to partial (incomplete) XFDF, because all the annotations that are not included in XFDF will be removed from the document. If XFDF was created by another tool, all widgets will be removed.
# Import annotations from XFDF to FDF
fdf_doc = FDFDoc.CreateFromXFDF(xfdf_filename)

# Optionally read XFDF from a string
fdf_doc = FDFDoc.CreateFromXFDF(xfdf_string)

# Merge FDF data into PDF doc
doc = PDFDoc.new(filename)
doc.FDFUpdate(fdf_doc)

Adding all annotations from XFDF

This is a 2-step process: first XFDF needs to be converted into FDF, then FDF needs to be passed to FDFMerge API. As a result of the import operation, all the XFDF annotations will be added to the PDF document:

  1. Annotations that are in XFDF only will be added
  2. Annotations that are both in XFDF and PDF will also be added, i.e. duplicating those annotations
  3. Annotations that are only in PDF and not in XFDF will not be modified

FDFMerge API works best for bringing new annotations into a document from a partial XFDF and for adding annotations to an empty PDF document.

Note, FDFMerge does not modify the existing annotations. When an annotation is present in both XFDF and PDF, it will be duplicated.
It also works well for importing field-only XFDF (e.g. field data exported from other PDF solutions).
Duplicate prevention
To prevent duplicates, remove all the annotations expected to be present in the PDF document from XFDF before using FDFMerge API.
# Import annotations from XFDF to FDF
fdf_doc = FDFDoc.CreateFromXFDF(xfdf_filename)

# Optionally read XFDF from a string
fdf_doc = FDFDoc.CreateFromXFDF(xfdf_string)

# Merge FDF data into PDF doc
doc = PDFDoc.new(filename)
doc.FDFMerge(fdf_doc)

Merging XFDF directly into the PDF

This is a 1-step process: XFDF is passed directly to MergeXFDF API. The API can both add and modify the annotations, but not delete them (except when using a command file). :

  1. Annotations that are in XFDF only will be added
  2. Annotations that are both in XFDF and PDF will be modified (see below)
  3. Annotations that are only in PDF and not in XFDF will not be modified
Note, MergeXFDF API relies on annotation names for matching the annotations. If XFDF file contains unnamed annotation, merge operation will be aborted with an exception. In order to proceed, set Force option, some annotations may be duplicated.
Name generation
XFDF files exported using PDFNet API version 9.0 and higher always contain annotation names, even if the annotations in the PDF document don't have them. When imported, those annotations will still be matched correctly.

MergeXFDF is also the API that should be used with command files (a flavor of XFDF with add-delete-modify instructions, see GetAnnotCommand() or AnnotationManager.exportAnnotCommand in WebViewer). In case of command XFDF, all operations specified by the command file, including deletions will be performed on the document.

# Merge FDF data into PDF doc
doc = PDFDoc.new(filename)
doc.MergeXFDF(xfdf_filename)

Common use cases

Use caseAPI
Restoring annotations from backupFDFUpdate
Importing all changes made to annotations in WebViewerFDFUpdate
Importing form data exported from other PDF solutionsFDFMerge or MergeXFDF
Introducing several new annotations to a document while keeping the existing document's annotationsFDFMerge or MergeXFDF
Importing partial XFDF that contains modifications to annotations that already exist in the document (assuming XFDF annotations are named)MergeXFDF
Importing command xfdf file, which allows fast application of annotation changes made on another WebViewer or Apryse SDK instance.MergeXFDF

PDF Form fill and form data extraction
Full sample code which illustrates basic FDF merge/extract functionality and full support for FDF (Forms Data Format)

Get the answers you need: Chat with us