Custom import/export of annotations

Skip to first unread message

Ryan - PDFNet Developer

Jul 30, 2014, 5:28:16 PM7/30/14

I am researching how to integrate the HTML5 WebViewer with a web service for annotations. The annotations service is a custom service developed in-house. It is based on OData ( and its default wire format is JSON.

From an engineering perspective, the cleanest approach to this integration would be to augment the AnnotationManager with custom import/export functions specific to the needs of our service. E.g., AnnotationManager.prototype.ImportAnnotationsCustom = function (jsonPayload) { ... }

My question is: how difficult would this be? Export seems relatively straightforward; we can get the current set of annotations from the manager and serialize each as JSON. Import seems like it might be more challenging. Based on my comparison of an in-memory annotation and its XFDF serialization, it feels like there is some not insignificant deserialization logic inside the black box. For example, there seem to be many undocumented properties on an in-memory annotation that have no direct mapping from the XFDF.

All comments/advice/direction much appreciated.


If you can avoid it, I would not modify/extend the AnnotationManager, in this case. Instead I would recommend working with XFDF, and doing the XFDF to/from OData conversion outside of webviewer.

The XFDF spec is open, and we do follow it, with a few extensions, but these don't break XFDF compatbility. For example, we support Widget annotations, which are the visual aspect of PDF fields. We also add a <defmtx> entry, which maps the coordinate system of the XFDF annotations, into XPS coordinate system (which has a flipped y, and a different default dpi then PDF). You can ignore both of these in your conversions. The Xod file itself contains its own defmtx entries, so those will be used if none are found in the XFDF file.

If you are only dealing with certain annotations (such as text highlights) then you would not need to write a full XFDF/OData converter, and just worry about those particular entries.

If the above information doesn't help, then feel free to explain in more detail what you are doing (you can also contact support in this case, instead of this forum).

Also, note that there is a separate WebViewer forum. I will cross post this conversation there.!forum/pdfnet-webviewer

Len Charest

Jul 30, 2014, 9:12:55 PM7/30/14
It sounds like you are recommending that, for example, I export (serialize) to XFDF via the AnnotationManager, and parse the resulting string in order to generate an OData payload. Likewise for import, I would generate an XFDF instance (string) from the OData payload, and then pass that to the AnnotationManager. 

How is that approach materially different from skipping the XFDF representation altogether, and simply translating to/from OData directly to a Javascript annotation object?

I should point out that I will be using a data transfer object to represent an OData annotation in Javascript. So the crux of the problem is a mapping to/from my OData annotation objects to one of WebViewer's annotation objects (e.g., Annotations.TextHighlightAnnotation).


Matt Parizeau

Jul 31, 2014, 5:09:25 PM7/31/14
Hi Len,

I suppose it's not completely different and if you know exactly what properties you want to map to certain properties on an Annotation object then it might not be overly difficult. One thing that's nice about the default serialize/deserialize is that it handles the conversion from/to PDF coordinates because different coordinates are used inside the XOD file. To workaround this you can use the GetPDFCoordinates and GetXODCoordinates functions on the Document object to convert your points.

Matt Parizeau
Software Developer
PDFTron Systems Inc.
Reply all
Reply to author
0 new messages