A.nnotate as a Documentum Taskspace viewer and annotation plugin

This guide describes how to install a.nnotate as a document viewing and annotation plugin for Documentum Taskspace. See the screencast for an overview of the features. To use the plugin you need a license for an annotate server, plus integration API.

Installation overview

Taskspace includes a viewer plugin architecture which allows different document viewers and annotation components to be embedded within taskspace applications. A.nnotate can be used to provide high quality document viewing and shared annotation within Taskspace, all in the browser without needing clients to install Flash, Java, or Adobe reader.

The A.nnotate plugin slots into this framework, allowing you to select which document formats to use with A.nnotate. Supported document formats include:
PDF, Microsoft Word (.doc and .docx), Powerpoint, Excel, OpenOffice, Images (JPG, TIFF, PNG), TXT, RTF.

The current version of the plugin is designed to work with Documentum Taskspace 6.5SP2, and has been tested on Linux and Windows Server 2003 installs. The steps to install the plugin are:

The annotate taskspace plugin consists of a small number of java and javascript files which need to be installed in your taskspace web area (source code is included). This connects your taskspace web application with an A.nnotate server, which runs on PHP and Apache (or IIS). When users click on a document link from within taskspace, the plugin uses the Annotate API to display it in the browser, and enables viewing and annotation. Download (requires password; contact us):

Download and extract the plugin for documentum taskspace:

(an earlier release is still available - bundle-jul4.tgz [2010-07-04])

Extract the bundle to a new folder. It includes the files below: 

  packages/
      annotate-taskspace-plugin-feb2011.tgz  --- patches to Taskspace

      --- sample a.nnotate configuration files for use with taskspace:
      phpconfig-windows-taskspace.inc
      phpconfig-linux-taskspace.inc
  
      --- misc example configuration & test files
      phpinfo.php
      php.ini
      httpd.conf
      test.pdf

      --- patches to annotate server if you need proxy support:
      notifyNoteSaved.php   [updated: feb 2011 with proxy support]
      annotate.php          [updated: feb 2011 with extra reload args]
      wipedoccache.php      [updated: feb 2011]
      apiPostTempFile.php   [updated: apr 2010]

1. Install dependencies (PHP, Apache, Openoffice)

The A.nnotate server requires a web server running PHP; see the Server installation guide for full details, an outline of the steps to install PHP, Apache and Openoffice on windows is given below; for linux, you can use your standard package installer. 

--- Outline of a sample Windows installation of PHP + Apache ---

a) PHP
  [[[ Downloaded from: http://php.net/downloads.php
        ('windows binaries' PHP 5.2.11 zip package)
  ]]]

  Extract to: 
    c:\php5
  using winrar, winzip etc.

  --- add c:\php5 to PATH if you want:
   (r-click my computer - Properties - Advanced - 
       Environment variables  ...  append ;c:\php5)

  --- to check it installed, start a command prompt 
      and type 'php -version'

b) Apache
  [[[
  Downloaded from: http://httpd.apache.org/download.cgi
        ('Win 32 binary')
  ]]]

  Typical installation
    c:\program files\apache software foundation\apache

  --- to check, Visit http://localhost  - should say 'it works'
  --- documents in:
      C:\Program Files\Apache Software Foundation\Apache2.2\htdocs


c) Connecting Apache to PHP:
  --- copy packages/php.ini to c:\windows\php.ini
 
  [[[  or:
      copy c:\php5\php.ini-dist c:\windows\php.ini  ]]]

 
     > Edit the php.ini settings to allow larger document uploads:
        max_execution_time = 300
        upload_max_filesize = 20M
        post_max_size = 80M
  ]]]

  --- copy packages/httpd.conf to 
      C:\Program Files\Apache Software Foundation\Apache2.2\conf\
 
   [[[ Edit Apache's httpd.conf to enable PHP for the directory:
      C:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf

     # ... in the section for the htdocs directory:
     <Directory "C:/Program Files/Apache Software Foundation/Apache2.2/htdocs">
       # *** Change from 'None' to 'All' to support .htaccess security
       AllowOverride All

     # ... at the end of the #LoadModule entries, add the lines below
     # to support PHP:

     # A.nnotate: to support PHP
     LoadModule php5_module "c:/php5/php5apache2_2.dll"
     AddType application/x-httpd-php .php
   ]]]

  --- restart apache:  
      ( Start - Programs - Apache HTTP Server 2.2 - Control Apache Server - Restart )
      - or r-click on the apache icon in the toolbar, open apache monitor, restart

  --- test installation by copying packages/phpinfo.php to 
         C:/Program Files/Apache Software Foundation/Apache2.2/htdocs
      point browser at http://localhost/phpinfo.php
      - this should show the PHP configuration settings.


d) OpenOffice
  [[[ Download from:
    http://download.openoffice.org/
    --- will install to: 
      C:\Program Files\OpenOffice.org 3\program
  ]]]

  (Start - Programs - OpenOffice to run)
  --- the first time you run it, you might want to disable 
      the 'check online for updates' option if your server
      doesn't have internet access.
  --- also right-click on the quickstarter icon in the toolbar
      and 'disable quickstart'

2. Install A.nnotate server

Download 'annotate server and api' from the installation pages for Linux or Windows.

For Linux, follow the install instructions on the guide above; a basic install will support PDF files only. To enable OpenOffice support, (for Word, TXT, RTF, TIFF, Images etc) see the modules installation guide.

Full instructions are in the install guides above - a sample install sequence for windows is given below: 

For Windows:
  > create a new folder 
     C:/Program Files/Apache Software Foundation/Apache2.2/htdocs/annotate
  > extract the annotate-server-and-api zip file there.
  > start a command line and run the 'install.bat' script:
    cd C:/Program Files/Apache Software Foundation/Apache2.2/htdocs/annotate
    install.bat 
    - this will copy some files and set permissions on the private/ and docs/ folders

You need to configure your a.nnotate server to point at the path of your Taskspace installation by editing the configuration file in php/phpconfig.inc. Samples are provided in packages/phpconfig-windows-taskspace.inc and packages/phpconfig-linux-taskspace.inc, and the appropriate one needs to be copied to the php/phpconfig.inc file in your annotate installation: 

 > For a *normal* a.nnotate server installation, you would
    copy php/phpconfig-linux.inc or php/phpconfig-windows.inc to:
    php/phpconfig.inc and edit the settings.

 > For use as a taskspace plugin, samples are supplied in:
       packages/phpconfig-windows-taskspace.inc for Windows (used for the Win2003 VM) 
       packages/phpconfig-linux-taskspace.inc for Linux

    These need to be copied to annotate/php/phpconfig.inc and edited with a text
    editor (e.g. WordPad on windows, emacs on linux) to match your settings.
    Some important ones are highlighted below:
[[[ 
    // *** change the settings below for your installation ***
    $adminusers = array('docadmin@example.com');
    $win32bin = "C:/Program Files/Apache Software Foundation/Apache2.2/htdocs/annotate/win32/";
    $nnotatesite = "d65dev";
    $nnotatepath = "http://d65dev/annotate";
    $licensecode = "0000-0000-0000-0000";


    // *** Important: If you will be installing to a server which
    // does not have internet access, you will need to uncomment
    // both lines below to stop your server trying to send emails:
    //
    // $noNewAccountEmail = 1;
    // $mailsender = "none";   


    // *** Extras for documentum plugin: ***
    // [ included near the end of the sample phpconfig.inc files ]
    $taskspacePath = "http://d65dev:8080/taskspace"; 

    // These two settings enable the callback to save notes in documentum,
    // and the check on upload to load notes from documentum.
    $notifyNoteSaved = 1;
    $checkForAnnotations = 1; 

    // These should be left unchanged:
    $fetchAnnotationsUrl = "$taskspacePath/imagingservice?type=annotation&command=get&annoformat=anno_tate&";
    $saveAnnotationUrl = "$taskspacePath/imageservices/saveannotation?fmt=js&annoformat=anno_tate&";

]]]

Some notes on checking your a.nnotate server installation on windows are given below; see the main installation guide for Linux details: 

  --- check the PDF extraction works from the command line:
     cd annotate\win32
     c:\php5\php test.php
     - should show a sequence of 'SUCCESS' messages.
     - if your machine doesn't have internet access, 
       the 'Checking PHP can fetch URLs' test will timeout,
       this is OK.

Installing your license and generating an annotate API key

To complete your install, create the Admin account and install your license:
  --- check you can visit (e.g.): http://localhost/annotate/index.php
  --- click the green 'Register' button and log in as the admin email 
      your entered in phpconfig.inc (e.g. 'docadmin@example.com') to 
      create the admin account.
  --- check you can view the sample document and add notes
  --- visit your 'Account' page and change the admin password
      (a random password is created for new accounts, and usually
       emailed to the user; if your machine doesn't have internet
       access though, you should set the password at the start).
  --- install your license 
    To install a license:
     a) set the license code in php/phpconfig.inc
      i) if your machine has internet access, go to your 'Account' 
         page and 'click to install license code 1234-5678-...'
      ii) if your machine doesn't have internet access, 
         you need to contact support@nnotate.com for details
         of a manual license installation.
  --- try uploading a small *PDF* document (from the 'Documents' page, 
      'Upload...' and check you can add notes to highlighted text)

API-KEY:
  This is needed to control your annotate server from outside
  (e.g. your taskspace server) securely.
  --- log on as an admin user
  --- go to 'account' page and scroll down to the bottom to the  
      'For developers only: API access' section
  --- copy the 'API Key' displayed (needed for plugin config below)

3. Install A.nnotate plugin for taskspace.

3.1 Add the 'anno_tate' annotation format to documentum:

The A.nnotate plugin needs to store annotations in the 'anno_tate' format in Documentum.

To register this format, log in to the documentum admin interface, visit: http://localhost:8080/da and use menu options: 

      Administration -> Formats, File->New->Format

Create a format named 'anno_tate' , description 'A.nnotate annotations', mime type 'text/html': (see screenshot).

3.2 Install the a.nnotate plugin for taskspace


A: Extract the plugin
   extract: packages\annotate-taskspace-plugin-jul3.tgz
   into: 
   c:\Program Files\Tomcat 6.0\webapps\taskspace\annotate

 Start a command prompt in this folder:
   cd c:\Program Files\Tomcat 6.0\webapps\taskspace\annotate
   c:\php5\php install.php

   [[[  
       ... This applies patched files from import/ and copies a backup of 
       original files to bak-YYYY-MM-DD/ 

       If you want to revert to the original versions from a backup
          move import  originals
          move bak-2009-01-01...  import
          php install.php          
   ]]]



B: Edit the plugin configuration settings
   The configuration settings are stored in 
       webapps\taskspace\wdk\config\imaging\ivf_config.xml:

   --- edit 'ivf_config.xml' settings for both the 'Annotate' plugin and 
       the 'AnnotateViewer' plugin, using notepad.exe: 
       You need to change the annotateServerURL, annotateApiKey and 
       annotateApiUser parameters:

  <ViewerProvider name="Annotate">
   annotateServerURL - http://d65dev/annotate
   annotateApiKey    - abc12334beb34b354b3    <<< need to set to API key for your a.nnotate server ***
   annotateApiUser   - docadmin@example.com
   annotateTestMode  - set to 'true' to force re-upload of documents (testing only) 

  <ViewerProvider name="AnnotateViewer">
   annotateServerURL - http://d65dev/annotate
   annotateApiKey    - abc12334beb34b354b3    <<< need to set to API key for your a.nnotate server ***
   annotateApiUser   - docadmin@example.com
   annotateTestMode  - set to 'true' to force re-upload of documents (testing only) 



C: Restart Taskspace
   --- Log out of taskspace, then reboot the system.

   In 'Configure' panel of the taskspace application, , "Viewers and Formats"
   sections lets you change file mappings for PDF to 'Annotate'.
   Click the 'PDF' format, Edit, then select Viewer Name: Annotate.
   (or 'Annotate (viewing only)' if you don't need annotation enabled).

   You'll need to Save (bottom right) to store the updated configuration
   in the taskspace application.


   [Start with 'PDF' for testing; to support Word and other office formats,
    you'll need to install extra a.nnotate modules (see below).]

   Check you can click on a pdf file in 'my folders' to view it in the
   right panel.

   --- if this works OK, change 'annotateTestMode' config field in 
       ivf_config.xml to 'false' and restart Tomcat.  This will use
       cached versions of documents in A.nnotate, and the annotations
       will be shared with all viewers of a document.

   --- if the document isn't displayed, possible problems are:
     - Tomcat is using a stale cached session - clear browser cookies and cache. 
     - Documentum didn't boot up properly

3.3 Running OpenOffice as a scheduled task to add Office support

In order to support annotating and viewing formats apart from PDF (Word, Powerpoint, RTF, TXT), you need to have openoffice running in server mode. This is used by a.nnotate to convert other document formats to PDF on the server. 

[[[ see http://a.nnotate.com/modules-installation.html for Linux openoffice support ]]]

For Windows:
WinServer2003: 
 Start - Settings - Control Panel - Scheduled Tasks - OpenOffice
 checkbox 'open advanced properties when finished'

Edit the Run: parameters to add parameters below:
C:\PROGRA~1\OPENOF~1.ORG\program\soffice.exe -accept="socket,port=8100;urp;" -norestore -nofirststartwizard -headless -nologo

The Settings tab: uncheck the 'Stop the task if it runs for 72hrs'

To start it running by hand, right-click and Run on:
  Start - Settings - Control Panel - Scheduled Tasks - OpenOffice

Use the task manager to check if a 'soffice.exe' process is running
in the background.

Taskspace: 
  Configuration - Add :  viewer mapping from msw8 to Annotate

Save.

My Folder - click on a .doc file.
 First conversion might be slow, as it needs to start up openoffice.
 Later conversions should be faster.

3.4 A note on recompiling the A.nnotate plugin

There is a bat file in webapps/taskspace/WEB-INF/classes
  annotate-compile.bat
which recompiles 
  com/documentum/web/formext/control/imaging/AnnotateParameterHandler.java,
    ViewerParameterHandler.java, 

and for storing and fetching annotations from/to documentum:
  com/documentum/web/imaging/AnnotationHandler.java, SaveAnnotationServlet.java

3.5 Wiping A.nnotate's cache of documents

On viewing a documentum document, it is first transferred to the annotate server and then converted to images for the browser. The annotate server stores a cache of documents, which can fill up your hard disk if it is not occasionally cleared. A script is provided for this [since Oct 2010], which you can view in your browser to run: 

  wipedoccache.php?y=2010&m=09&days=7&c=xyz

 - wipes documents uploaded in given year, month
 - days= only wipes documents not viewed for this number of days
 - c=xyz - an authorization code to view this page.  This must match
   an auth code you choose in phpconfig.inc: $cronAuthCode='xyz';

 - you can set days=-1 if you need to remove documents viewed
   today (e.g. for testing)

4. Running the plugin behind a proxy

If you need to access the plugin via a web proxy and give different URLs for internal and external users, then check the running the taskspace plugin behind a proxy guide for configuration details. [added in Feb 2011 release]

Please email any questions to support [at] nnotate.com.