WebViewer Server progressive annotation loading causes duplicates when using external XFDF with loadDocument

Technical Support WebViewer
, , ,
1

WebViewer Version: 11.12

Do you have an issue with a specific file(s)? Its happening for pdf files larger than 10Mb file
Can you reproduce using one of our samples or online demos? No
Are you using the WebViewer server? Yes
Does the issue only happen on certain browsers? No
Is your issue related to a front-end framework? Yes
Is your issue related to annotations? Yes

Please give a brief summary of your issue:

Duplicate annotations are displayed in the webviewer when loaded after upgrading to modularUI.

In the below screenshot, only 1 annotation is there in the pdf, but multiple duplicates of the same annotation are displayed.

image
image1271×934 217 KB

Environment:

  • WebViewer SDK version: 11.x (modular UI)

  • Configuration: fullAPI: true, forceClientSideInit: true, webviewerServerURL configured

Problem:

When using WebViewer Server with an external XFDF file, annotations are duplicated for large PDF files (>~18MB).

Our workflow:

  1. Load document via

    instance.UI.loadDocument(fileUrl, {

            filename: fileName,

            cacheKey: cacheKey,

            customHeaders: { Authorization: `Bearer ${token}` },

        });

  2. Wait for annotationsLoaded via
    await documentViewer.getAnnotationsLoadedPromise();

  3. Delete all existing annotations (server-extracted from PDF)

    annotationManager.deleteAnnotations(existingAnnotations, {

                    imported: true,

                    force: true,

                });

  4. Import our authoritative XFDF via

    await annotationManager.importAnnotations(xfdfString, {

                imported: true,

            });
1 Like
3

Hi Priya.

Thank you for reaching out.

WebViewer Server loads annotations in chunks for large files. If you import XFDF before all native annotations are loaded, both sets can merge and cause duplicates, and deleting annotations immediately after annotationsLoaded may not remove all server-provided annotations if they are still being loaded incrementally.

Instead of waiting for annotationsLoaded and then deleting/importing, set up your annotation import using setDocumentXFDFRetriever before loading the document:

WebViewer({
  ...,
  // other options
}, viewerElement).then(instance => {
  const { documentViewer } = instance.Core;

  documentViewer.setDocumentXFDFRetriever(async () => {
    // Fetch your authoritative XFDF here
    const response = await fetch('path/to/annotation/server');
    const xfdfString = await response.text();
    return xfdfString;
  });

  instance.UI.loadDocument(fileUrl, {
    filename: fileName,
    cacheKey: cacheKey,
    customHeaders: { Authorization: `Bearer ${token}` },
  });
});

This approach ensures that your XFDF is loaded at the correct time, preventing duplicates from incremental server annotation loading.

Here is the documentation for this API:

Let us know if you have any questions.

Best Regards,
Mickaël.

1 Like
4

Hi,

Thank you for the suggestion to use setDocumentXFDFRetriever. We have implemented it and it resolves the duplicate annotation issue for large files.

However, we have a concern about the delete annotation scenario:

Our workflow:

  1. A PDF file has annotations embedded in it (previously added by users)

  2. We store annotations externally in an XFDF file (separate from the PDF)

  3. When a user deletes an annotation and saves, the XFDF file is updated (annotation removed), but the PDF file still contains the embedded annotation

  4. On the next load, setDocumentXFDFRetriever returns the updated XFDF (without the deleted annotation)

Question:
Does setDocumentXFDFRetriever fully replace the PDF’s embedded annotations with the XFDF content? Or does it merge/supplement them?

Specifically — if an annotation exists in the PDF but is absent from the XFDF returned by the retriever, will that annotation:

  • (a) Not appear at all (XFDF is authoritative, PDF annotations are ignored), or

  • (b) Still appear (PDF annotations load independently, XFDF adds on top)

With WebViewer Server in the picture, the server extracts annotations from the PDF and sends them to the client. We need to confirm that setDocumentXFDFRetriever suppresses those server-provided annotations entirely, so that only the XFDF content is displayed.

If setDocumentXFDFRetriever does not suppress PDF-embedded annotations, could you recommend an approach that ensures our external XFDF is treated as the sole source of truth — where annotations deleted from the XFDF do not reappear from the PDF?

Thanks, and Regards,

Priya Krishna

1 Like
5

Hi Priya,

Thank you for your reply.

setDocumentXFDFRetriever does not suppress PDF-embedded annotations.

To recommend the best approach, could you please provide more context on why you are keeping annotations in the PDF if you are keeping them separated in an XFDF file?

Best Regards,
Mickaël.

1 Like
6

Hi,

In one of our operations, we add comments to a PDF using WebViewer. In this workflow, only the XFDF file is updated; the PDF itself is not modified.

Therefore, any annotations already embedded in the PDF should be removed, and only the annotations contained in the XFDF file should be imported and displayed when the PDF is viewed in WebViewer. In other words, the XFDF file should be the sole source of annotations, and any embedded PDF annotations should be ignored.

Thanks.

Priya

1 Like
7

Hi Priya,

Thank you for your reply. Sorry for the delay.
setDocumentXFDFRetriever is intended to provide XFDF that is imported during the document loading process, which resolves the timing issues that can occur with WebViewer Server’s progressive annotation loading. However, it is not designed to treat the returned XFDF as a complete replacement for annotations embedded in the PDF itself.

Because of this, if an annotation still exists in the PDF and is removed only from the externally stored XFDF, the annotation may still be loaded from the PDF on subsequent document loads. In other words, the XFDF returned by setDocumentXFDFRetriever should generally be considered additive/imported annotation data rather than an instruction to discard all annotations originating from the document.

For your specific scenario:

  1. Annotation exists in the PDF.
  2. Annotation is removed from the external XFDF.
  3. The document is reloaded.
  4. Since the annotation is still embedded in the PDF, it can be loaded again from the document even though it is no longer present in the XFDF.

If your external XFDF is intended to be the sole source of truth, we recommend one of the following approaches:

  1. Keep the PDF and XFDF synchronized by removing deleted annotations from the PDF as well as from the XFDF.
  2. Store annotations exclusively in XFDF and use source PDFs that do not contain embedded annotations.

These approaches ensure that annotations deleted from your authoritative XFDF store do not reappear because they are still present in the underlying PDF.

Based on the workflow you described, I would not recommend relying on the absence of an annotation in the XFDF as a mechanism for suppressing an annotation that remains embedded in the document.

The second approach can be easily implemented by loading the document without any embedded annotations:

documentViewer.loadDocument('file/path', {
    loadAnnotations: false
});

You can then fetch your XFDF and use the importAnnotation API.
Once the annotations from your XFDF are imported, every modification made by your user would update your XFDF, meaning the next document load would be up to date.

Let me know if that is what you had in mind.

Best Regards,
Mickaël.

1 Like