===================================================
Nuxeo Digital Asset Management - Technical overview
===================================================

Olivier Grisel <ogrisel@nuxeo.com>
Thomas Roger <troger@nuxeo.com>
July 2009

TODO: convert this to docbook format to be able to generate HTML / PDF versions.


High level functional goals
===========================


Functional overview
-------------------

DAM stands for Digital Asset Management which means collection manager
for digital assets which can be office (MS, OOo, PDF, ...) or multimedia
(pictures, audio and video) files.

The main difference with Nuxeo DM (Document Management) is that DAM
is not aimed at "producing" new documents with collaborative editing /
review workflows but merely at browsing an existing collection that have
been authored externally and imported in batch in the DAM application.

User will merely edit the properties / categories or add annotations to enrich
the asset without editing the main attached file.


Ajaxified search centric UI
---------------------------

The navigation is not document-centric and organised in collaborative
workspaces as in Nuxeo DM but is instead search-centric. Furthermore the
application ergonomy should feel like a rich collection browser such as iTunes
or iPhoto by extensively using Ajax. Speed and responsiveness to user actions
should be considered a major feature of DAM.

Ajax features are implemented using the Rich faces components and the Ajax4JSF
extensions. The online demo is available here:

  http://livedemo.exadel.com/richfaces-demo/richfaces/support.jsf?c=support&tab=usage

Some a4j tips are gathered on the following wiki page:

  http://doc.nuxeo.org/xwiki/bin/view/Main/Ajax4JSF+Good+practices

In addition to JSFs ajax features, we plan to also reuse existing ajax
features of Nuxeo DM such as the right click actions menu based on
jquery plugins.


Three columns user interface
----------------------------

The file photoshop-mockup-3columns.png shows the expected look and feel of the
app. The navigation works a follow:

1- the left column hosts a set of search parameters (a.k.a. the filters) such as
   document categories, author name, creation date min / max, ... Upon changing
   the values of any of those filters the second column content is refresh using
   a4j reRender with target: 'filterResultTable' in the
   nuxeo.war/incl/filtered_search_results.xhtml template.

2- the middle column hosts the paginated list of assets matching the search
   parameters. This column has two rendering views: columns listing and
   thumnails panel (with 3 adjustable sizes for the thumbnails). Clicking on the
   title or thumbnail of a result in that listing selectes the asset and trigger
   the rendering of the right columns using a4j reRender target '???'.

3- TODO: right column displaying currently selected asset's tabs

TODO: jquery adjustable vertical column separator

TODO: import form, user management screens and other global screens as modal
popup (question: how to make them ajaxified to reduce the rendering load?)


Developer environment and source code layout
============================================

Source code
-----------

The source code specific to the DAM project is located here:

  http://hg.nuxeo.org/nuxeo-dam/

The project layout is as follows:

- nuxeo-dam-core

  core document schemas definitions and other contributions to services
  to be deployed on the stateful machine in multi machine setup

- nuxeo-dam-webapp-common

  Common contributions and web resources needed by DAM and Nuxeo DM (when
  running Nuxeo DAM and Nuxeo DM on the same repository)

- nuxeo-dam-webapp-core

  DAM specific seam components

- nuxeo-dam-webapp

  Webapp resources for the DAM UI

- nuxeo-dam-webapp-override

  Contains the web resources that need to override the default ones copied
  in nuxeo.war.

- nuxeo-dam-distribution

  Assembly files to package the DAM application as:
    - A nuxeo.ear
    - A JBoss distribution
    - A Jetty distribution
    - A Tomcat distribution


Continous integration
---------------------

The automated build / selenium test reports are hosted there:

  http://qapriv.nuxeo.org/hudson/job/nuxeo-dam/
  http://qapriv.nuxeo.org/hudson/job/nuxeo-dam-ftest/

Hudson also publishes nightly builds there:

Jboss distribution:
  http://maven.in.nuxeo.com/nexus/content/groups/internal-snapshots/org/nuxeo/dam/distribution/nuxeo-dam-distribution-jboss/1.0-SNAPSHOT/

Jetty distribution:
  http://maven.in.nuxeo.com/nexus/content/groups/internal-snapshots/org/nuxeo/dam/distribution/nuxeo-dam-distribution-jetty/1.0-SNAPSHOT/


Document types and schemas
==========================

A specific DAM schema is added: dam_common. It is used to store DAM related
information like author of the assets, authoring date of the assets, ...

We reuse the document types defined in a standard Nuxeo, but types are
overridden to use our custom schema.

- Picture: for image related files (jpeg, png, gif, bmp, ...)
- File: for Office document files (Microsoft Office documents, OpenOffice
  documents, PDF, text files, ...)
- Video: to be defined in a generic video module (like imaging one)
- Audio: to be defined in a generic audio module

2 new document types are defined for DAM:

- ImportSetRoot: the root folder where the ImportSets are stored. Extends
  Folder type.
- ImportSet: extends Folder type, contains the assets related to a given
  import.

One ImportSet is created for each import.


Batch import of assets
======================

Physical document hierarchy layouting
-------------------------------------

As stated previously, an ImportSet document is created for each import,
regardless of whether the file being imported is a composite file (eg. a zip
file) or a single file (eg. a single jpg image).

They are all stored in the same ImportSetRoot: /default-domain/import-sets in
the repository.

See the accompanying document: import.txt for a full example.


Each ImportSet document contains the assets imported.

Hierarchy example:
/default-domain/import-sets-root
                  |- folder1
                  |     |- import-set-1
                  |     |     |
                  |     |     |-file1
                  |     |     |-image1
                  |     |     |-subfolder1
                  |     |     |  |-image2
                  |     |     |  |-image3
                  |     |     `-audio_file1
                  |     `- import-set-2
                  |     |
                  |     |-file2
                  |     |-image4
                  |     `-audio_file2
                  `- folder2
                        |- import-set-3
                        |     |
                        |     |-file3
                        |     |-image5
                        |     |-subfolder2
                        |     |  |-image6
                        |     |  |-image7
                        |     `-audio_file3
                        `- import-set-4
                        |
                        |-file4
                        |-image8
                        `-audio_file4

type of the folder1 & folder2 is now "ImportFolder"


Blobs stored externally (default in VCS?).

---

Could be a directory based hierarchy so we can move assets from one folder to
another, we can set permissions on the folders (required by potential DAM
client).


Import process
--------------

2 new FileManager plugins are contributed by DAM, one to handle Office Files
documents and one to handle ZIP files. The ZIP plugin recursively import all
documents contained in the archive file. The hierarchy of documents from the
archive is maintained during the import.

- the user chose a ZIP or a file to import
- the FileManager handle it with the help of our contributions
- an ImportSet is created under the ImportSetRoot folder
- all the documents are added to the newly ImportSet, maintaining the hierarchy
  of documents.

An extension to the FileManager was added to exclude some of the files during
the import. For now, it is configured to ignore hidden files created by the MAC
OS X archiver, 'thumbs.db' generated by Windows.

Perf issues:

  - for huge ZIP files => doing the upload asynchrnously?
  - lots of documents in the ZIP file => doing the creation of documents
    asynchrnously and find a way to tell the user that his import is done (can
    be doable by ajax pulling?). Maybe cumulating the 2 things.
  - Change the way to handle high volume import: see below Zip extractor.


Zip extractor
-------------

The Zip import screen is currently implemented as a plugin for the FileManager.

In the long term we might want to switch to high volume importer written by TD
currently avaible as a sandbox plugin and probably to be packaged as a generic
NXP service:

  https://hg.nuxeo.org/sandbox/nuxeo-platform-importer/

The goal is to be able to implement long running import tasks with
subtransactions.


Imaging integration
===================

Thumbnails generation
---------------------

For our Picture documents, the imaging module only generate the 3 default
views: Original, Medium (~540px), and Thumbnail.

We can't use the default mechanism provided by the imaging module to create new
views because our Picutures documents aren't stored in a PictureBook document.

For DAM, we will need to have more generated views: at least 3 sizes of
thumbnails for the content view, a different thumbnail for the list view,
different sizes (?) for the preview.

  => enhance the imaging module to be able to generate more views without using a PictureBook (new extension point?)

Thumbnails sizes to be defined:

- Default size for the preview
- the 3 different sizes for the thumbnails view
- the size for the list view


Preview integration
===================

We will need to handle multiple preview for a same Picture document:
 - the annotation preview which should take the original size
 - maybe we want the user to chose between different preview size (?)

For now, we can make a PreviewAdapterFactory for a given document type that
will set the (only) blob to preview when asking for /default/, or we can set in
the preview URL the xpath of the blob we want to preview which end up with URLs
like:

 restAPI/preview/default/9ef9fdec-698b-4e8e-a20d-533efe825a6f/file:file/content/

Enhancing the preview extension points can allow to bind a "nicer name" to a
defined Blob property xpath:

 medium_size => views:views[1]/content

So we end up with something like:

 restAPI/preview/default/9ef9fdec-698b-4e8e-a20d-533efe825a6f/name/medium_size
or
 restAPI/preview/default/9ef9fdec-698b-4e8e-a20d-533efe825a6f/medium_size

=> really needed?

===> Default preview size to be discussed (a fixed smaller image that fits in a 400x400 iframe?)

===> How to handle preview without annotations (for the information tab)

=======> Not really needed as we decided to not use the preview for the Informations


Annotations integration
=======================

===> To be discussed (in the preview tab, or a fullscreen modal popup)

Text and image annotations: same as in Nuxeo 5.2. Maybe some UI things to
update.

Video annotations:

 - a new wrapper has to be done to handle the API of the chosen player (if not
   Quicktime)
 - backport the video annotation code from 5.1.6 to 5.2 => some refactoring
   needed to adapt to the new architecture.

General:
 - handling i18n in the iframe
 - fixing text annotations under Safari 4 (if we want to support Safari)


Batch editing
=============

Most of the editing job will be done with a list of documents.

=> Reusing DocumentListManager? Seam level... not at servie / core level.
=> ResultPageProvider already contains the logic for pagination, but the API is
   a mess. Finish and merge Olivier's work on the new Provider?
=> Create a module to handle correctly batch editing / saving of documents:
   service + core. For instance, there is no way to save a list of documents
   without calling saveDocument() on each one...
 ==> Done in Nuxeo generic


Search centric navigation
=========================

Stateful querymodel and provider
--------------------------------

TODO: seam component names + query model name


Selected document
-----------------

- Seam component handling the current selected document for viewving / editing
  purposes

The selected document is shown in the right column with multiple tabs:

 - informations tab: thumbnail of the current document (rezied image for a
   Picture document, thumbnail of the first page for an Office document or a
   big icon representing the documenttype if the thumbnail is not available)
 - Rights
 - Transformations
 - Delivery

Selected documents
------------------

- Seam component handling the current selection editing: delegate to the
  service defined above (if a new service is done).

As for one selected document, the selection is shown in the right column with
displaying only the common metadata.


Ajaxified document tabs
-----------------------

TODO


Security model
==============

Virtual storage (default one) will use SecurityPolicies to restrict permissions on assets.

It will be probably done on checking metdata / tags on the assets

==> Recreate permissions management screens


Delivery Service
================

Check what have been done for NewsWave ans Prisma project

==> See if we can get a generic delivery service from those implementations. If
not, make one.


Factorizing code with NXP and Nuxeo DM
======================================


Reusing existing NXP services
-----------------------------

The DAM JSF application should delegate business logics to Nuxeo Runtime
services. Most of them are already part of NXP. New ones will most probably
packaged as NXP services too without any dependency on the DAM webapp.

Planned new services include:

- picture and video watermarking.
- delivery service
- video module (like imaging one)
- audio module (like imaging one)

TODO: list them all here


Reusing Seam components
-----------------------

We are working on our branch 'NXP-3610-webapp-cleanup':

- to move what can be reused in DAM from nuxeo-platform-webapp-core to
  nuxeo-platform-webapp-base
- to do some refactoring on Seam bean: removing dependency on InputController
  for the beans that don't need it
  (no more dependency on navigationContext which is not needed for DAM)

Follow http://jira.nuxeo.org/browse/NXP-3610 for the progress.

==> At some point, it has to be merged in Nuxeo so that we can reuse it for futur projects.


URL navigation and browser history
==================================

By default ajax prevents traditional RESTful URL navigation, bookmarks
and history (browser back button) management.

However we want users to be able to bookmark and copy and paste the URL of the
current state of the view of the application (). To achieve this while
preserving the ajax driven UI we plan to use the following jquery plugin that
mimicks the gmail and other mainstream ajax application URL handling:

  http://www.mikage.to/jquery/jquery_history.html

We will need to define a coding and decoding of all the following states
parameters:

- search filters values
- current page position in the paginated results
- currently selected document
- currently selected document tab


==========================================
To put in Video module specification
==========================================

Video streaming
===============

===> we must only require http access, so all non http based protocols should be dropped

Target implementation
---------------------

We want a recent flash plugin as only dependency. We also want to be able to
handle HD quality stream (at least 720p) hence we will probably focus on MP4
container (with h264 video codec and mp3 or AAC audio codec). The ffmpeg lib can
be used to perform video conversion from almost anything to that target.

The most only protocol to stream MP4 content to flash players is RTMP which is
an extension of the HTTP protocol hence should simplify firewall and SSO
integration.

On the server side, the red5 LGPL java project aims to provide a streaming
server implementation with experimental RTMP support in the trunk (target 0.9):

  http://code.google.com/p/red5/

Red5 is packaged as a war to be deployed on a tomcat server hence could run in
the same JVM as nuxeo which should make it easier to plug ACL security checks
and SSO / login module authentication using the nuxeo libs.

On the client side there is good (but GPL) player with jquery scripting and RTMP
streaming support (MP4 decoding is provided by the flash plugin v10 or later):

  http://flowplayer.org/

Nice forum post with state of the art RTMP / MP4 streaming options:

  http://stream-recorder.com/forum/real-time-messaging-protocol-rtmp-broadcasting-flv-t3934.html


Alternatives
------------

It is also possible to target RSTP streams of other formats using browser
plugins such as Quicktime or VLC and darwin streaming server. However the setup
my be more complex and so are the security / ACL checks to acces the stream of
a blob stored in the VCS.

It is also possible to stream OGG videos using the opensource icecast2
streaming server over HTTP and have any HTML5 enabled browser (FF 3.5+, Safari
4+, Google Chrome, Opera 10 but not IE) with a fallback to VLC plugin. This is
probably more robust and opensource friendly but won't suit the average windows
IE6 corporate users + we need to deal with authorized access to the stream so
configure icecast2 to ping nuxeo to check security on video blobs.


Nuxeo DM and Nuxeo DAM on the same repository
=============================================

Deployment
----------

* To deploy DM and DAM on the same repository, the clustering needs to be
  enabled on the 2 servers:

  - the documentation to enable the clustering can be found here:
    http://www.nuxeo.org/xwiki/bin/view/FAQ/NuxeoClustering

* The jars nuxeo-dam-core, nuxeo-dam-webapp-common, nuxeo-platform-audio-core
  and nuxeo-platform-video-* need to be deployed on Nuxeo DM.

Features
--------

In the Default Domain, an Assets Library folder is available where the assets
visible in Nuxeo DAM will be stored.

The folders structure is the following:

Assets Library
 `- Import Folder
    |- Import Folder
    `- Import Set
       |- Picture file
       |- Video file
       `- Folder
          |- Audio file
          `- Office File

All the specific DAM metadata are available on the assets visible in Nuxeo DM
(and can be modified).

