README

This is the documentation for the SFU Tips & Alerts Zimlet. Internally,
it's referred to as the MOTD (Message Of The Day) Zimlet, so that name
will be used throughout this document

ARCHITECTURE

While installing the motd Zimlet at your site will be straightforward,
some of the components, as distributed, are not suited to large-scale
production and will need to be modified or rewritten. To better
understand what is involved, it'll help to understand how the Zimlet works.

This package consists of three pieces: The motd Zimlet, a javascript-based
admin app, and a perl-based REST server as the data source.

The motd Zimlet itself is a relatively simple 'presentation layer' which
does little more than retrieve HTML "blobs" from a remote data source and
display them for the user. 'Tips' blobs are displayed when the user
requests them while 'alerts' blobs are displayed as soon as they're pulled
from the data source. The only configuration parameter inside the Zimlet
is the URL to its data source.

The Admin app consists of a set of web pages that use javascript and AJAX
to view and store data in the data source. The data consists of HTML text
for tips and alerts and a number of settings - some unique to each tip or
alert, others for the Zimlet itself. The data is read and stored using REST.
The only configuration parameter the Admin app needs is the URL path to the
REST server.

The Perl-based REST server is the data source. It's a CGI web app designed
to run behind an Apache web server. The REST server uses the underlying
filesystem as its data store - no database is used. REST uses standard HTTP
GET and POST commands to read and store data (respectively) in unique
URL-addressable locations.  Every HTTP request is a completely self-contained
transaction - no session needs  to be established, or state saved, between
transactions.

INSTALLATION

1. Start by choosing a location to host the REST server code. It probably won't
be on the same server as your Zimbra server, as it requires Apache to be
running. Install the 'zimbrarest.cgi' perl program in your chosen location.
You will also need two perl modules - CGI.pm (quite possibly already
installed) and JSON.pm (probably not). You can install them with CPAN - e.g:
'perl -MCPAN -e "install CGI"'

2. Edit zimbrarest.cgi and set $basedir to the path to use as the datastore. It
shouldn't be a path that Apache can access directly - i.e. make it something
outside of your htdocs doctree.  There are no other changes to the perl code
that you must make, although read on below for improvements you may want to
consider.

3. Verify that your perl program will run - 'perl -c zimbrarest.cgi'

4. Unpack the sample REST data into whatever directory you've chosen to be your
datastore. This will give you some tips and alerts text to play with, and also
sets up default settings for the Zimlet

5. Unpack the admin app into a directory accessible to Apache on the same server
 - i.e. somewhere under the docroot. Because the admin app makes use of
Javascript AJAX calls to talk to the REST server, it must be accessed from
the same server as the REST server (your browser security model won't allow
Javascript AJAX calls to go to a different server than the javascript came from)

6. In the admin app, 2 files need to be edited to define your URLs:
   ./motd/settings/index.html - search for urlBase and set appropriately
   ./motd/_js/motd.js - change the GET and POST URLs at the top of the file

7. Verify that you can access your admin app. If your server is www.site.edu and
you put the admin app at the root level, the URL will be
http://www.site.edu/motd/settings .

8. Assuming the admin app works, make sure you can view and edit the sample tips.

9. Now you're ready to deploy the zimlet. First, unzip it in a temporary directory
as you'll need to edit the .js and .xml file

10. Edit config_template.xml and change the 'allowedDomains' property to be
your own domain. This property configures the Zimbra proxy servlet with the
list of domains that Zimlets are allowed to communicate with

11. Edit ca_sfu_icat_motd.js and change the value of 'ca_sfu_icat_motd.host'
right near the top of the file. There's also a Help URL later in the file
that you may want to change. Search for 'sfu.ca'.

12. If desired, edit ca_sfu_icat_motd.xml and change the right-click action
for the zimlet. Right now, it produces a link to SFU's Zimbra Help website.

13. Rezip the files back up: "zip /tmp/ca_sfu_icat_motd.zip *"

14. Copy the zip file to your zimlets directory, /opt/zimbra/zimlets

15. Deploy the zimlet:
"zmzimletctl deploy /opt/zimbra/zimlets/ca_sfu_icat_motd.zip"

16. If you have more than one COS, you'll need to permit the zimlet to your
other COS's using the 'zmzimletctl acl' command.


A NOTE ABOUT SECURITY

As distributed, this zimlet and admin app has none (security, that is). At SFU,
we have an extensive web-based single-signon infrastructure that both this admin
app and the Zimlet make use of, but none of that is portable so it was stripped
out of this public version.

It would be relatively harmless to leave security out of the Zimlet itself. It's
primarily a read-only client - the only data it writes back to the server is the
end-user's preference on whether they want to see tips by default at login or not.
So with that in mind, there are at least two ways you can secure this app. The
first is easier but less secure and convenient:

 1) Protect the admin app with .htaccess files and modify the Perl REST server so
 that POSTs can only come from a specified set of IP addresses unless the POST
 is to the user datastore area ("/datastore/motd/<userid>/"). The set of IP
 addresses will be that set that can run the admin app.

 If you do choose this method, you can enable the whoami.php calls in the
 admin app. These calls will determine the user ID based on the ID that
 authenticated to the server, and use that ID in the "user" field of the
 Tips and Alerts. This allows you to track who created which tip or alert


 2) (more work) Modify the Zimlet to store its settings in "the Zimbra way"
 rather than to the REST server, develop your own app to directly store tips,
 alerts and settings in the datastore (rather than using the admin app) and
 disable POSTing to the REST server entirely.


There are other solutions that could be developed too, such as using a
token-based security system, where the Admin app is protected using .htaccess
files but it has a token that it passes along to the REST server to ensure the
POST is permitted. Doing that would eliminate the need to check IP addresses
on the REST server


ROOM FOR IMPROVEMENT

Beside the security improvements mentioned above, there's also lots of room for
improvement with the REST server. The server that's bundled with this code is
a very simple implementation, using the underlying OS filesystem for data storage.
It is neither fast nor efficient. It could be improved substantially by turning
it into an applet. Use something like FastCGI so that it continues to run between
calls. That way, it can cache all of its data at startup rather than having to go
to disk for each query. And replace the filesystem with a database.

Better yet, rewrite it as a JSP so that it can run on the Zimbra server. Zimbra
already has a mechanism built-in that allows Zimlets to communicate with JSPs
that run on the server. If you do this though, you'd have to get creative
with the Admin App too


CONTACT

The Zimlet and Admin app were both written by Graham Ballantyne (grahamb@sfu.ca).
The REST server, this documentation, and modifications to make the code work
for the general public were done by Steve Hillman (hillman@sfu.ca). 

