Running the A.nnotate Documentum taskspace plugin behind a proxy

This guide describes how to configure the a.nnotate taskspace plugin when running behind a proxy; see the plugin installation guide for the basics of installation. Proxy support was added in the Feb 2011 version of the plugin.

Proxies overview

The standard installation guide assumes all users access the taskspace and annotate servers at the same standard URL - e.g. the taskspace web app at: http://server123.example.com/taskspace, and the annotate server at http://server456.example.com/annotate, with both taskspace and annotate told the URL of the other server (using the configuration settings in ivf_config.xml and phpconfig.inc).

However, if some of your users will be accessing the taskspace (and annotate) servers through a web proxy, e.g. internal users view the servers as http://server123/taskspace and http://server456/annotate and external users view them as: http://external123.example.com/taskspace and http://external456.example.com/annotate, then you'll need to add both URLs to the taskspace configuration to ensure the plugin can communicate with the taskpace application (to save notes and display documents).

The examples below assume we have an installation of taskspace running internally on the machine http://d65dev:8080/taskspace, and an installation of annotate accessed internally at http://d65dev/annotate. The proxy server for taskspace is accessed as http://external123.example.com/taskspace and the one for annotate is accessed as http://external456.example.com/annotate.

1. Configure the Apache proxies

The sample .htaccess files below use mod_rewrite to send external URL requests to the appropriate server. It is also possible to configure mod_proxy using the apache config files, but this means restarting apache if you make any config changes. 

# .htaccess file for external123.example.com:
# mod_proxy and mod_rewrite should be enabled.

RewriteEngine On
RewriteRule taskspace(.*) http://d65dev:8080/taskspace$1 [P,L]

# .htaccess file for annotate proxy server (external456.example.com)
RewriteEngine On
RewriteRule annotate/(.*) http://d65dev/annotate/$1 [P,L]

With these in place, external users will see the servers as http://external123.example.com/taskspace and http://external456.example.com/annotate, but internal users can continue to access them as the internal machine names (http://d65dev:8080/taskspace and http://d65dev/annotate).

However, the servers need to know the browser URL that the user is using to access them, as the annotate plugin needs access to the taskspace browser session in order to transfer documents out of documentum for viewing and annotation. This must be configured at both ends; taskspace needs to know which annotate URL to use for the viewer iframe; and the annotate viewer needs to know the taskspace URL.

2. Configure the taskspace viewer plugin - ivf_config.xml

The taskspace configuration file is in: webapps/taskspace/wdk/control/imaging/ivf_config.xml and a sample configuration for our test case is shown below (a full sample is included with the plugin bundle). The annotateServerURL parameter is the internal server name; the annotateProxyURLs section has a list of taskspace sites, and the annotate server URL to use for each. 

  

... part of the annotate plugin config section ...
<param>
   <name>annotateServerURL</name>
   <value>http://d65dev/annotate</value>
   <description>Base URL of A.nnotate server</description>              
</param>  
<param>
   <name>annotateProxyURLs</name>
    <value>
[d65dev:8080] http://d65dev/annotate
[external123.example.com] http://external456.example.com/annotate
    </value>
  <description>
    Optional list of annotate server URLs to use, depending on 
    how the user is accessing taskspace.

    The format is 
      [... site of taskspace url...] {annotate server url to use}
      [... site of another taskspace url...] {annotate server url to use}
  </description>
</param>

On changing the ivf_config.xml file, you'll need to restart the taskspace server (it is a good idea to log out first, in case it caches stale session data).

3. Configure the annotate server - phpconfig.inc

The annotate server also needs to know which taskspace URL the user has used to access the system. This is because it uses the user's taskspace login session permissions to send documents for display (and the session is attached to the site the user has in their browser).

It is possible to add a section of code to the php/phpconfig.inc configuration file to set the appropriate settings for taskspace given the URL used to access annotate. The example below uses the HTTP_X_FORWARDED_HOST variable which mod_proxy sets to the original request url used. This is used to update the nnotatepath URL of the annotate server. You can set the nnotateapipath to the URL the taskspace server should use to access the annotate server API (typically the internal server address). 

  // Default settings
  $nnotatesite = "d65dev";
  $nnotatepath = "http://d65dev/annotate";
  
  // {... more config options ... }

  // ... at the end of phpconfig.inc, the taskspace specifics:
  $notifyNoteSaved = 1;
  $checkForAnnotations = 1; 
  $taskspacePath = "http://d65dev:8080/taskspace"; // default

  // ... if accessing annotate through an apache proxy,
  // check the annotate URL the user is using
  // and use it to select the appropriate taskspace URL:
  if (isset($_SERVER["HTTP_X_FORWARDED_HOST"])) {
    // accessed via proxy:
    $ohosts = "".$_SERVER["HTTP_X_FORWARDED_HOST"];
    $bits = explode(",", $ohosts); 
    $ohost = trim($bits[0]); // just in case multiple proxies

    // set the taskspace path depending on the user url: 
    if ($ohost=="external456.example.com") {
      $nnotateapipath = $nnotatepath; // for internal notifynotesaved call
      $nnotatesite    = "external456.example.com";
      $nnotatepath    = "http://external456.example.com/annotate";
      $taskspacePath  = "http://external123.example.com/taskspace";
    }
    // ... could have extra if statements if users use more than 
    // two URLs to access the server. 
  } 

  // The taskspacePath setting must match the user's browser location
  $fetchAnnotationsUrl = "$taskspacePath/imagingservice?type=annotation&command=get&annoformat=anno_tate&";
  $saveAnnotationUrl   = "$taskspacePath/imageservices/saveannotation?fmt=js&annoformat=anno_tate&";

You will also need to patch your annotate server for proxy support; copy the notifyNoteSaved.php and other php files supplied in the annotate-taskspace-bundle-feb2011.tgz to your annotate/php folder. You don't need to restart the apache server after making changes to php files or phpconfig.inc.

4. Testing the proxy setup

After making the changes above, you should be able to visit your taskspace application in the browser using either internal or external URL. It is worth confirming that your configuration is choosing the correct paths; one way is to use firefox with the firebug plugin to track the net requests to check that it is using the correct sites for taskspace and annotate when you log in usingthe different URLs.

For testing, choose a taskspace document which is not cached on the annotate server, as this tests the transfer from documentum into taskspace (which depends on the correct configuration - display of pre-cached documents will work even if annotate has the wrong taskspace url). For documents which are not cached, you will see a couple of 'checking for notes', 'preparing for annotation' messages during the transfer (cached documents display immediately).

You can call the wipedoccache.php script with 'days=-1' to clear the cache for a given month.