Skip to main content

Annotations

Optional addon

Annotations only available if it is enabled by the license

The jadice web viewer contains a set of pre-defined annotations that can be used to highlight parts of the document, add text remarks, draw arrows and more.

These annotations will be rendered on the PDF if the document is exported.

Loading Annotation Streams for Documents​

Configuration Setup​

Make sure that the document data provider is configured to retrieve the document and annotation data.

For instance add the following configuration blocks to your application.yml:

webtoolkit:
  # Configuration to retrieve document via our document data provider
  ddp:
    http:
      authentication: # authentication configuration for the document data provider BASIC authentication
        - host: localhost # match by host
          user: user1 # authentication credentials
          password: test # authentication password

To associate one or more annotation streams with each document in a compositePaged document, add an annotationData array to your compositePaged specification. Each entry in annotationData corresponds, in order, to a single document and may itself contain zero or more annotation-URI strings.

const collection = {
    elements: [
        {
            specification: {
                type: "compositePaged",
                pageSequences: [
                    {
                        mediaType: "application/pdf",
                        contentURI: "http://www.digbib.org/Franz_Kafka_1883/Der_Prozess_.pdf",
                    }
                ],
                annotationData: [
                	["http://example.com/annotation101.xml"]
                ]
            },
            metadata: {override_page_sequence_name: "Der Prozess", override_page_sequence_description: "Franz Kafka: Der Prozess"}
        }
    ]
};
window.viewerApi.collectionApi.showCollection(collection);

How It Works​

  • pageSequences - Defines each document’s media type and source URI.

  • annotationData - An array of arrays, where each inner array holds the annotation-URI strings for the corresponding document in pageSequences.

    • An empty inner array ([]) indicates no annotations for that document.

    • Multiple URIs may be provided to load several annotation streams.

Example: Multiple Documents with Variable Annotations​

annotationData: [
    ["http://example.com/annotation101.xml", "http://example.com/annotation102.xml"], // annotation data for the first document -> two annotation streams
    [], // annotation data for the second document -> empty
    ["http://example.com/annotation301.xml"] // annotation data for the third document -> onw annotation stream
]

Saving Annotations for Documents​

caution

At this point, only jadice annotations are supported to be saved via the description below. We will support other annotation formats in the future. However, you can already still use the jadice web toolkit to read and write your own annotation formats.

To enable users to save annotation data, configure the annotation save service in your application.yml file. This allows annotations to be persisted to external storage via HTTP endpoints.

Configuration Setup​

Add the following configuration blocks to your application.yml:

webtoolkit:
  # Configuration for saving annotations via our http save annotation service
  annotation:
    save:
      http:
        enabled: true # enable or disable the saving of annotations on the Server side
        # Base configuration
        base-url: http://localhost:3000
        url-template: "{baseUrl}/{timestamp}-{streamId}?upload"
        filename-template: "{streamId}"
        connect-timeout: 30  # seconds
        request-timeout: 60  # seconds
        # Authentication configurations (matched by host or regex)
        authentication:
          # Match requests by regex pattern
          - regex: "^http:\\/\\/localhost:3000"
            user: user1
            password: test
  clientConfiguration:
    internalCustomProperties:
      annotationSaveActionEnabled: true

How It Works​

  • enabled - Controls whether the annotation save service is active.
  • base-url - The root URL for your annotation storage service.
  • url-template - Defines how save URLs are constructed using placeholders:
    • {baseUrl} - Replaced with the configured base-url
    • {timestamp} - Replaced with the current timestamp
    • {streamId} - Replaced with the unique annotation stream identifier
  • filename-template - Defines the filename pattern for saved annotations.
  • authentication - Array of authentication configurations matched by host or regex pattern.
  • annotationSaveActionEnabled - Controls visibility of the save button in the UI.

URL Template Examples​

The url-template supports flexible endpoint construction:

# Example 1: Timestamped files with query parameters
url-template: "{baseUrl}/{timestamp}-{streamId}?upload"
# Results in: http://localhost:3000/20240318143022-stream123?upload

# Example 2: RESTful endpoint structure
url-template: "{baseUrl}/annotations/{streamId}"
# Results in: http://localhost:3000/annotations/stream123

# Example 3: Versioned API with timestamp
url-template: "{baseUrl}/api/v1/save/{streamId}/{timestamp}"
# Results in: http://localhost:3000/api/v1/save/stream123/20240318143022

Authentication Configuration​

Configure authentication for different endpoints using host matching or regex patterns:

authentication:
  # Simple host matching
  - host: example.com
    user: api_user
    password: secure_password
  
  # Regex pattern matching for complex URLs
  - regex: "^https:\\/\\/api\\.annotations\\.com"
    user: enterprise_user
    password: enterprise_password
  
  # Local development configuration
  - regex: "^http:\\/\\/localhost:[0-9]+"
    user: dev_user
    password: dev_password

Complete Configuration Example​

# Annotation save service
annotation:
  save:
    http:
      enabled: true
      base-url: https://api.annotations.com
      url-template: "{baseUrl}/v2/annotations/{streamId}?timestamp={timestamp}"
      filename-template: "annotation-{streamId}-{timestamp}"
      connect-timeout: 45
      request-timeout: 120
      authentication:
        - regex: "^https:\\/\\/api\\.annotations\\.com"
          user: annotation_saver
          password: save_token

# UI configuration
webtoolkit:
  clientConfiguration:
    internalCustomProperties:
      annotationSaveActionEnabled: true

Registering the Save Handler for the annotation save button​

window.viewerApi.annotationsApi.createSaveAnnotationsHandler(
  "document.xml", 
  "HttpSaveJadiceAnnotationsHandler",
  {
    onSuccess: () => window.alert("Saved!"),
    onError: (error) => console.error("Error:", error)
  }
);

Saving Annotations via JS​

window.viewerApi.annotationsApi.saveAnnotations(
  "document2.xml",
  "HttpSaveJadiceAnnotationsHandler",
  {
    conversationType: "SAVE_ANNOS",
    annoFormat: "JADICE",
    onSuccess: () => window.alert("Saved!"),
    onError: (error) => console.error("Error:", error)
  }
);

Troubleshooting​

  • Save button not visible: Ensure annotationSaveActionEnabled is set to true.
  • Authentication failures: Verify your regex patterns match the target URLs and credentials are correct.
  • Timeout errors: Increase connect-timeout and request-timeout values for slower networks.
  • Save failures: Check that your annotation service endpoint accepts the configured URL template format.
tip

Annotations are a very flexible tool to work with the document. With the jadice web toolkit it is possbile to read various existing annotation formats and also write them back to the underlying archive. You can define own annotations with fully customizable defaults, looks and editors.

Last updated on by Martin Bachl