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.
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
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:
- 1. Install dependencies (PHP, Apache, OpenOffice).
- 2. Install A.nnotate server
- 3. Install A.nnotate plugin for Taskspace
Download and extract the plugin for documentum taskspace:
[updated 2011-02-06; password required, contact us for details]
(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
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('firstname.lastname@example.org'); $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. 'email@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 firstname.lastname@example.org 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 - email@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 - firstname.lastname@example.org 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.