Addons

Nuxeo Annotations with ARender

Updated: August 19, 2019 Page Information Edit on GitHub

The more people involved on a document, the more difficult it becomes to collaborate and communicate because every participant has their own device (PC, mobile, tablet, etc.) and their own tools, which means different formats to preview.

The Nuxeo Annotations addon allows users to preview and annotate any document stored in the Nuxeo repository: Office documents, PDF, images, videos, etc., on any device with the ARender previewer from Arondor.

ARender software comprises two parts:

  • previewer
  • rendition

ARender rendition server needs to be installed on a dedicated host.

ARender previewer is extended by Nuxeo to integrate the ARender previewer with the Nuxeo REST API -- it corresponds to nuxeo-arender-connector-hmi in ARender Connector. It is built as a war file to deploy.

Here's a chart illustrating the actions during the first connection to ARender:

arender-flow.png
arender-flow.png

Installation

There are several ways to install ARender software.

For easy deployment, Nuxeo provides two Docker images, one for each part of the ARender software: arender-previewer and arender-rendition.

Private addon
You should contact your Nuxeo Administrator or your Nuxeo sales representative to get access to these images.

Docker Images Version
Docker images have the same versions as marketplace packages. You should always use the same version for Docker images and marketplace packages.

You can also install both parts directly on dedicated hosts by following ARender Documentation.

All communication is done over HTTP; we recommend using HTTPS for production. Below are the ports for each part:

  • previewer is reachable on port 8080 when exposed directly by Tomcat; we recommend to setup an Apache or Nginx in front of it
  • rendition is reachable on port 8761

Below are the requirements for firewall rules / Docker network setup:

  • Nuxeo needs to reach ARender previewer
  • ARender previewer needs to reach ARender rendition
  • ARender previewer needs to reach Nuxeo

Embedded Installation - Development

For development purposes, run the rendition Docker image and bind its port to localhost:

docker run -p 8761:8761 -it ARENDER_DOCKER_IMAGE_ID

Then install the nuxeo-arender-connector marketplace package.

It installs the ARender integration inside Nuxeo and the ARender previewer inside Nuxeo's Tomcat.

Docker Installation - Production

For production, we recommend that each part of ARender software is deployed as a Docker container.

You can deploy several ARender renditions. Their URL needs to be given to ARender previewer. ARender previewer is responsible for renditions loading. ARender renditions don't need to communicate with each other.

Rendition URLs can be passed to ARender previewer with the renditionHostEnv environment variable.

ARender previewer behavior
ARender previewer owns in its cache a session corresponding to the t-uple user, document and blob.
You'll need to ask for a new session if the previewer crashes (action 1. on chart).

ARender previewer clustering
You can't have a cluster of ARender previewers because previewers don't share sessions.

If you need to change these settings while ARender previewer is running, there is a REST API on ARender previewer.

To get current settings:

GET /arendergwt/weather?format=json

To update settings:

POST /arendergwt/weather?format=json
["https://rendition1:8761", "https://rendition2:8761"]

Configuration

Nuxeo Configuration

The ARender connector relies on a JWT to request an OAuth2 token for authentication (See OAuth2 documentation page for more information). You need to define a secret, nuxeo.jwt.secret in your nuxeo.conf, to enable it.

Authentication from ARender to Nuxeo relies on a shared secret between the two applications. This secret is defined with the property nuxeo.arender.secret in your nuxeo.conf.

Shared secret environment variable
If using the Docker image for the ARender previewer, you can also define this shared secret through an environment variable nuxeoArenderSecretEnv.

If your ARender rendition server doesn't run on same host as Nuxeo's Tomcat, you can change the ARender rendition URL by setting arender.server.rendition.hosts in your nuxeo.conf (default value is http://localhost:8761).

You can change the ARender previewer URL used by Nuxeo to open ARender sessions by setting arender.server.previewer.host in your nuxeo.conf (default value if http://localhost:8080).

ARender Previewer Configuration

For an on-host installation, you can follow the ARender Documentation.

For an embedded installation, you can modify the arender-hmi.properties files under NUXEO_HOME/nxserver/config/ARenderConfiguration folder.

For a Docker installation, you can extend our image and copy your properties file to /docker-entrypoint-init.d/arender.properties:

FROM dockerin-arender.nuxeo.com:443/arender-previewer:MP_VERSION

COPY arender.properties /docker-entrypoint-init.d/arender.properties

You can also modify the arender-hmi.properties which is deployed inside the /ARenderConfiguration in the previewer Docker container.

These configuration files let you customize the ARender interface to fit specific UI and UX needs. Please follow the ARender configuration guide for more information.

Examples of possible configurations:

  • Add or remove buttons from the ARender interface
  • Modify ARender behaviors on specific user actions (like entering a comment when the user clicks on "Enter")
  • Reference a new theme (by creating your custom CSS file)

arender-customized.png
arender-customized.png

Functional Overview

Once the ARender addon is properly installed and configured a new Annotations tab is available on each document with the picture or video facet:

annotation-tab.png
annotation-tab.png

Annotations

You can access the different types of annotations available by default directly from the top bar:

annotations-draw-arrows.png
annotations-draw-arrows.png
Add an arrow.
Repeat mode available.
annotations-add-freehand.png
annotations-add-freehand.png
Draw different shapes with the Freehand.
Repeat mode available.
annotations-sticky-note.png
annotations-sticky-note.png
Add a sticky note.
annotations-free-text-box.png
annotations-free-text-box.png
Add a text box.
annotations-draw-circle.png
annotations-draw-circle.png
Add a circle.
Repeat mode available.
annotations-highlight-text.png
annotations-highlight-text.png
Highlight text.
Once your text is selected you can modify the color and opacity of the highlight.
annotations-redact.png
annotations-redact.png
Annotate over text, hiding its contents.
This annotation is only available on text documents.

Repeat mode: Once the annotation is selected, 2 blue arrows are displayed annotations-repeat-mode.png meaning that you can add several annotations is a row. To disable the repeat mode, click on the annotation icon again.

Other buttons are available on the top bar to optimize the visualization of the document: zoom, rotation, full screen, pagination, height and width adjustment, etc.

To add an annotation:

  1. On the top bar, click on an annotation type, like the sticky note.
    An empty box is displayed on your document.
    annotation-sticky-note-empty.png
    annotation-sticky-note-empty.png
  2. Write your annotation and press Enter
    Your annotation is directly displayed, the autosave is enabled by default.
    annotation-sticky-note-displayed
    annotation-sticky-note-displayed

To access annotations:

Three views are available on the left panel:

annotation-views.png
annotation-views.png

  • annotation-document-pages-thumbs.png: Document page thumbnails, opened by default
  • annotation-browser-navigation.png: Annotations Browser
  • annotation-browser-navigation.png: Advanced Search

From the annotations browser, you can see the list of all the annotations made on the document you are viewing, grouped by document pages.

You can search for and filter any annotation:

annotation-search.png
annotation-search.png

You can also manage annotations by:

  • Adding a comment
  • Replying to a comment
  • Deleting a comment

annotation-comment-replied.png
annotation-comment-replied.png

Once added, these comments are available from the view tab of your document.

Arrow

  1. To create an arrow, click on the Add arrow button annotations-draw-arrows.png then click and drag to draw an arrow.
  2. Once your arrow is drawn, you can customize its direction, color, opacity, style, etc.

    annotations-arrow-options.png
    annotations-arrow-options.png

Arrows can also be used to take measurements on a document. To do so, once an arrow is drawn, click on Show measurement on the customization top bar and the measurement will be displayed in your preferred unit (inches, centimeters or pixels).

annotations-jacket-measure.png
annotations-jacket-measure.png

Watermark

To watermark a document, two solutions are available: Add a watermark to each page before printing, as explained in the section below or use a stamp annotation.

To add a stamp annotation, click on the stamp button annotations-stamps.png.
A popup window is displayed:

annotations-popup-stamps.png
annotations-popup-stamps.png

Different options are available: "Urgent", approved on the current date, "Insert signature here:", "draft", or a signature.

Download

Hover over the download icon annotations-download-button.png to display the file menu with several available actions:

annotations-submenu-download.png
annotations-submenu-download.png

  • Download current file
  • Download current file as PDF
  • Download current file with annotations

Print

  1. Click on the Print button annotation-print-button.png at the top right of the screen.

  2. A popup window appears with several print options:

    • Print the current document
    • Print all documents
      annotation-popup-print.png
      annotation-popup-print.png

You can select “Include annotations” to print all annotations on a document, or select "Include watermark" to display the selected watermark on all pages of the document.

Once your choice is made, click on “Ok” button, and the page(s) will be printed.

Document Comparison

Limitations
This feature only allows you to compare the text of two files.

With the ARender addon, you can compare the text of two different versions of a file. By default, ARender compares the binary stored in the file:content property corresponding to the main file. You can access this feature from the Compare Versions Screen by clicking on the eye icon.

compare-arender
compare-arender

A new window is opened with the two documents side-by-side, highlighting text which has been deleted, modified or added.

compare_arender_2
compare_arender_2

You can see the annotations linked to each version on the same screen, and even annotate one file from this view.

Supported File Formats

The annotations module supports a large number of file formats.

  • PDF - all versions, XFA not supported
  • Images: JPEG, PNG, TIFF, GIF, BMP, JNG, PBM, PSD, EPS, PS, DCM (Format DICOM) and all formats supported by ImageMagick
  • Microsoft Office (97-2013): Word (.doc, .docx) , PowerPoint (.ppt, .pptx), Excel (.xls, .xlsx), WordML (.xml), Visio (.vsd)
  • Composite files: ZIP, EML, MSG
  • Others: TXT, OpenDocument (LibreOffice or OpenOffice)

Going Further

The connector can be customized in many different ways, such as adding new watermark stamps, displaying different actions/tools etc.

3 days ago GitHub Fix release date on deprecated addons
History: Created by GitHub

We'd love to hear your thoughts!

All fields required