Introduction

Document annotation is a critical feature in many enterprise content management systems. Business users often need to review, mark up, redact, approve, or collaborate on documents without changing the original source file. In IBM Content Navigator and Daeja ViewONE Virtual Viewer environments, annotations provide a powerful way to support these workflows while preserving document integrity.

This blog post walks through the implementation of a custom ViewONE Plugin. The plugin demonstrates how to load annotations, save annotations, burn annotations permanently into documents, and support export workflows for PDF and TIFF outputs.

The goal of this implementation is to provide a practical, production-ready foundation for teams that need deeper control over annotation storage, formatting, persistence, and export behavior in a Daeja ViewONE-based document viewing solution.

What the Plugin Does

The ViewONE Plugin provides a complete annotation lifecycle around documents displayed in the ViewONE Virtual Viewer and exporting document.

At a high level, it supports:

• Loading existing annotations for a document
• Creating and editing annotations in the viewer
• Saving annotations to the server
• Preserving ViewONE annotation file formatting requirements
• Burning annotations permanently into the document output
• Exporting annotated documents as PDF or TIFF
• Tracking viewer events for debugging and diagnostics
• Providing a configurable foundation for enterprise deployment

This makes the plugin useful for different processes.

Architecture Overview

The implementation is structured around a simple web application pattern. The browser hosts the ViewONE Virtual Viewer, while JSP handlers manage annotation retrieval, persistence, and burn/export operations on the server side.

The design intentionally separates the viewer interface from the server-side annotation operations. This makes the plugin easier to maintain, debug, and extend.

Technology Stack

The plugin uses a lightweight stack that fits naturally into existing Java-based enterprise environments.

Although the sample implementation uses JSP files, the same pattern can be adapted to servlets, REST APIs, Spring Boot services, or repository-backed persistence layers.

Components:

Virtual-plugin.html is the main viewer interface. It is responsible for launching the ViewONE Virtual Viewer and passing the correct parameters to enable annotation behavior.

This page typically handles:

• Viewer initialization
• Document URL configuration
• Annotation URL configuration
• Save handler configuration
• Burn/export handler configuration
• Viewer event tracking
• Debug console output

A simplified conceptual structure looks like this:

The most important responsibility of this file is to connect the viewer to the correct server-side handlers. In a production environment, this page would usually receive document identifiers, repository identifiers, or case identifiers through request parameters or application context.

load.jsp retrieves the annotation file associated with the document being viewed.

When the viewer opens a document, it needs to know whether annotations already exist. The load handler receives the document reference, locates the matching annotation content, and returns it in the format expected by ViewONE.

Typical responsibilities include:

• Reading the document identifier from the request
• Resolving the annotation file path or repository object
• Validating access to the annotation resource
• Returning annotation content to the viewer
• Handling the case where no annotation exists yet

A simplified flow is shown below:

This component should be kept simple and predictable. The viewer depends on a valid response, even when no annotations exist.

save.jsp persists annotation updates from the viewer.

This is one of the most important parts of the plugin because ViewONE annotation files have formatting requirements that must be preserved. In particular, blank-line formatting can matter. If annotation content is saved incorrectly, the viewer may fail to reload annotations or may display them incorrectly.

The save handler is responsible for:

• Receiving annotation content from the viewer
• Validating the document identifier
• Validating annotation payload size and structure
• Preserving required line breaks and blank lines
• Writing the annotation content to storage
• Returning a success or failure response

A conceptual save flow looks like this:

The formatting behavior is especially important. Annotation persistence is not just a matter of writing raw text to a file. The handler must preserve the annotation file structure expected by the viewer.

burn.jsp handles permanent annotation burning.

Normal annotations are separate from the original document. This is useful because users can edit, hide, or remove them later. However, some business workflows require annotations or redactions to become part of the final exported document.

That is where annotation burning is used.

The burn handler typically supports:

• Taking a source document
• Taking its associated annotation file
• Invoking ViewONE export or burn behavior
• Producing an output document with annotations applied
• Returning the generated PDF or TIFF result

A simplified burn flow looks like this:

This is especially useful for redaction workflows where the final document must permanently include redaction marks before being shared, archived, or sent downstream.

Understanding the ViewONE Annotation File Format

ViewONE uses a proprietary annotation format. The exact content depends on annotation type, page number, coordinates, color, author, timestamp, and other metadata.

A simplified annotation file may contain information such as:

The real format can be more detailed, but the key point is that ViewONE expects the annotation content to follow a specific structure. Line breaks, section boundaries, and blank lines may affect how the viewer parses the file.

For this reason, the save operation should avoid unnecessary transformations such as trimming all whitespace, collapsing blank lines, changing encodings incorrectly, or rewriting content in a way that breaks the expected structure.

Exporting Annotated Documents

A major feature of the plugin is support for exporting documents with annotations.

Depending on business requirements, export behavior may include:

• Exporting the original document without annotations
• Exporting the document with editable annotations
• Exporting the document with annotations burned in
• Exporting PDF output
• Exporting TIFF output
• Applying special behavior for redactions

For example, a document review workflow may allow users to save editable annotations during review. After approval, the same document may be exported with annotations burned into the final PDF.

In another workflow, TIFF output may be needed for compatibility with downstream imaging systems.

The plugin structure makes this behavior easier to manage because export and burn logic is isolated in burn.jsp rather than mixed directly into the viewer page.

Debug Console Integration

A practical annotation plugin should be easy to troubleshoot. Viewer integrations can fail for several reasons, including incorrect document URLs, missing annotation files, invalid server responses, CORS issues, permissions problems, or malformed annotation content.

The implementation includes debug console integration to help diagnose these problems.

Useful debug information may include:

• Document URL being loaded
• Annotation load URL
• Annotation save URL
• Burn/export URL
• Viewer initialization status
• Save response status
• Viewer events
• Error messages returned from server-side handlers

A debug console is especially useful during development and customer issue reproduction because it makes viewer behavior visible without requiring full server-side tracing for every issue.

Viewer Event Tracking

Viewer event tracking provides additional visibility into user and viewer behavior.

Events that may be useful to track include:

• Viewer loaded
• Document opened
• Page changed
• Annotation created
• Annotation modified
• Annotation deleted
• Annotation save started
• Annotation save completed
• Export requested
• Burn operation completed
• Viewer error occurred

This event information can be written to the browser console, displayed in a debug panel, or sent to a server-side logging endpoint.

For enterprise environments, event tracking can also help support audit requirements, performance analysis, and user behavior diagnostics.

Deployment Guide

A typical deployment process may look like this:

Step 1: Package the plugin files

Include the main viewer page and server-side handlers:

Step 2: Deploy to the application server

Place the files in the appropriate web application directory or package them into a deployable application archive, depending on your environment.

Step 3: Configure document storage

Make sure the plugin can resolve document URLs or repository document references correctly.

Step 4: Configure annotation storage

Choose where annotation files will be stored. This may be a file system, database, object store, or enterprise content repository.

Step 5: Configure viewer parameters

Set the ViewONE parameters required for document loading, annotation loading, annotation saving, and export behavior.

Step 6: Validate permissions

Confirm that users can only access documents and annotations they are authorized to view or modify.

Step 7: Test

Test the full lifecycle:

Step 8: Enable logging and debugging

Enable enough logging to troubleshoot issues during rollout. Debug logging can be reduced after the implementation is stable.

Troubleshooting Common Issues

Issue 1: Annotations do not load

Possible causes:

• Incorrect annotation load URL
• Missing annotation file
• Invalid document identifier
• User does not have permission
• Server returns an unexpected response format

Recommended checks:

• Open browser developer tools
• Confirm the request to load.jsp succeeds
• Check the response body
• Validate the annotation file exists
• Review server logs for access or path errors

Issue 2: Annotations save but do not reload

Possible causes:

• Annotation file formatting was changed during save
• Blank lines were removed
• Incorrect encoding was used
• Annotation was saved under the wrong document identifier

Recommended checks:

• Compare the saved annotation file with a known working file
• Confirm blank-line formatting is preserved
• Check whether the document ID used during save matches the document ID used during load

Issue 3: Burned output does not include annotations

Possible causes:

• Burn handler is not receiving the annotation reference
• Annotation file is empty or inaccessible
• Export parameters are incorrect
• Burn operation is using the source document only

Recommended checks:

• Confirm burn.jsp receives both document and annotation inputs
• Check server logs during export
• Validate the annotation file content before burn
• Test with a simple annotation first

Issue 4: Export format is incorrect

Possible causes:

• Output format parameter is missing
• Viewer or server defaults to PDF
• TIFF-specific behavior is not enabled
• PDF input is handled differently from image input

Recommended checks:

• Confirm the requested output format
• Validate export parameters
• Test PDF and TIFF inputs separately
• Document expected behavior for each input/output combination

Issue 5: Viewer works locally but fails in production

Possible causes:

• Different context root
• Reverse proxy or load balancer path changes
• Authentication differences
• CORS or CSP restrictions
• Missing application server permissions

Recommended checks:

• Compare local and production URLs
• Check browser console errors
• Review network requests
• Validate proxy headers and context paths
• Confirm production security policies allow viewer resources to load

Conclusion

The ViewONE Annotation Plugin provides a complete foundation for managing annotations in a Daeja ViewONE Virtual Viewer environment. It supports the core annotation lifecycle: loading, editing, saving, exporting, and permanently burning annotations into output documents.

By separating the viewer interface from server-side handlers, the implementation remains understandable and extensible. The use of Virtual-plugin.html, load.jsp, save.jsp, and burn.jsp creates a clean structure that can be adapted for file-based storage, repository-backed storage, or larger enterprise content management systems.

For teams working with IBM Content Navigator, Daeja ViewONE, or document-heavy enterprise workflows, this plugin is a practical starting point for building controlled, secure, and auditable annotation capabilities.

With additional enhancements such as audit logging, repository persistence, versioning, and role-based permissions, the same foundation can evolve into a robust production annotation service for enterprise document processing.

Virtual-plugin.html

load.jsp

save.jsp

burn.jsp