TeamSite Tuesday

I have prepared the TeamSite toolbar described in my earlier post for download and use by others.   Instructions may be found below.

Note: use at your own risk with no warranty or support.  However I am happy to take questions or comments if you have any.  It works nicely on a Linux installation of TeamSite, version 6.7.2, and will probably work on others. It’s untested!

1 Put these two files in $IWHOME/httpd/iw

DOWNLOAD: greasemonkey-include.js

DOWNLOAD: greasemonkey-include-iwlogo.gif

You will need to edit the first file.  Find the section marked “Map Environments to TeamSite Servers” to tell the script which TeamSite server to use for each of your sites.

You will also need to set the permissions and ownership of the files to the same as the other files in this location.

2 Put these two files in $IWHOME/httpd/iw-bin

DOWNLOAD: greasemonkey-checklogin.cgi

DOWNLOAD: greasemonkey-checkdcr.cgi

You will need to edit the first line of each of these, to point to your iw-perl path.  You will also need to set the permissions and ownership of these files.

3 Install the GreaseMonkey add-on for Firefox

https://addons.mozilla.org/en-US/firefox/addon/748

4 Configure GreaseMonkey

1. Click “New User Script…”
2. Enter a name, e.g. “TeamSite Toolbar”
3. Enter a namespace, e.g. “teamsitetuesday.co.uk”
4. In the “Includes” section, add an expression which matches your sites, e.g. http://*.mycompany.com/*
5. When prompted, browse to your favourite text editor.
6. When the text editor opens, paste the following script.  Amend the URL so that it picks up the JavaScript you imported in the very first step.

var s = document.createElement('script');
s.setAttribute("src", "http://teamsite-prod.mycompany.com/iw/greasemonkey-include.js");
s.setAttribute("type", "text/javascript");
document.body.appendChild(s);

5 Add metadata into your pages

This new version of the toolbar works by looking for metadata in the HTML served from your site.

5.1 Add “cms.path” metadata

This tells the script which path to use for the DCR when the user clicks “Edit”:

<meta name="cms.path" content="/default/main/branch1/WORKAREA/workarea-name/templatedata/category/type/data/folder/dcr-name"/>

If your site is a static HTML site, this is simply achieved by modifying your TPL to include this metadata in the page header.  To get the path, the function you need to use is iwpt_get_dcr_name(), and you’ll need to strip off the /iwmnt part.

If your site is a dynamic site, you will need to insert the DCR path into the database upon deployment, and amend the application to include this metadata in the page header.

5.2 Optionally, add “cms.newform” metadata

This tells the script which DCR to create when the user clicks “New”

<meta name="cms.newform" content="/default/main/branch1/WORKAREA/workarea-name/templatedata/category/anothertype"/>

If everything is set up ok, you should see the toolbar when you now browse to your site.

Drop me an email if it works for you, or if you’ve got any comments.

Known Issues

I’ve spotted a bug when Firebug is installed, which prevents the toolbar from opening.  Disable Firebug and this problem disappears.

Design Notes

This toolbar originally did not require any metadata to be included into the HTML. It just worked by editing the corresponding HTML file in TeamSite using a mapping mechnism.  I found this to be cumbersome, and it lacked flexibility.  The metadata technique method works on ANY site, whether “flat”, “dynamic” or some combination of the two.

One of the most frequently heard complaints about TeamSite is how difficult it is to navigate.  If an editor knows what page they want to edit, they can sometimes find it time consuming to locate the page within TeamSite’s branch and folder structure.  This is particularly true if the external URL bears little resemblance to the internal structure of the site within the CMS.

This is why I’ve knocked up a “TeamSite Toolbar”:

Editor Functionality

When editors browse a site they are able to edit, they see a floating toolbar at the top of the page presenting the CMS options available to them.  If they’re not logged in to the CMS, they get a login prompt.  Otherwise they see an “Edit” link, which links them directly to the form for the page they’re viewing.  Other TeamSite functionality can also be exposed to them, for example showing if the file is locked, and by whom.

Technical Details

It works using Greasemonkey, a tool that most developers will be aware of, which can be used to inject your own JavaScript into any web pages.  The injected Javascript is pulled from the TeamSite server with each request, allowing the rolling out of toolbar updates without having to involve the editors with installation.

The communication between the toolbar JavaScript and the TeamSite server is handled by JSON.  A Server-side CGI is dynamically included as a JavaScript on the page, and this provides JSON data to the toolbar.  The data contains the URL for editing the page in the CMS and some metadata for other functionality.

I’ve made the code available for download here.

I’ve written an adapter for OpenDeploy, which allows secure deployment over SSH.  An OpenDeploy receiver is not required on the target host – the only requirement is an SSH shell, supporting scp, unzip and rm.

It’s pretty fast.  It works by zipping the files up on the source, deploying the zip, and unpacking it on the target.  Consequently it doesn’t handle any rollback.  However, it does handle deletes.

Download JAR

Source

To use the adapter:

• Put the adapter JAR on the OpenDeploy receiver (this can be your base, which can be configured to deploy to itself).  Put it in $ODHOME/userlib
• Amend your deployment configuration to include the section of XML as shown below
• Create a properties file for the deployment, which also resides on the OpenDeploy receiver, in the location $ODHOME/adapters/delivery/scpadapter.  An example is also shown below.  You’re likely to have a different properties file for each project.

Deployment Configuration

<target useReplicationFarm="MYFARMNAME">
  <odAdapterSet>
    <odAdapter
      name="ODSCPAdapter"
      class="com.teamsitetuesday.odscpadapter.ODSCPAdapter"
      parameterNS="odscp"
      parameter="OD-HOME/adapters/delivery/scpadapter/PROPERTIES_FILENAME"
      async="no"/>
    </odAdapterSet>
    ...

Properties file

remotehost=IP_ADDRESS
remotedir=/path/to/target/folder
username=USERNAME
password=PASSWORD

Warranty

None.  No promises, no comeback, use at your own risk.

I’d be interested to hear how it works out.  Or if you have any suggestions for improvement, do please let me know.

Since I started at Channel 4 a year ago, I’ve had a pet project to solve some of the headaches inherent in TeamSite development.  Here I’d like to share the ideas behind what I’ve done so far, using the Big Brother 2009 project as an example.

This article covers how we’ve got TeamSite project code to behave more like a deployable atomic application.  This has been achieved by two distinct initiatives:

1. Getting project code to run in the same TeamSite branch as the project content
2. Developing a mechanism to promote this code between virtual environments

The remainder of this article relates to the first of these.

Summary

We wanted all the TeamSite code for the Big Brother site to be located in the project branch, including templates, workflow code, modules, CGI callouts, and DNR scripts.  This allows us to have more than one set of Big Brother code running independently on the same server, or located arbitrarily on different TeamSite servers.

Developers develop in a development branch (crikey, that’s a mouthful).  They use standard TeamSite functionality to copy or merge their completed work into a stable Integration branch.  A ‘Code Promotion’ workflow deploys this code from Integration to all other environments: Test, Uat, Stage and Production.  Using this method, all of the TeamSite code and configuration is managed and deployed atomically.

There is a simple relationship between TeamSite code, TeamSite content and the target application – there’s only one of each for each environment, and no interdependencies.   This keeps the Build Manager happy.  If you know a Build Manager, you’ll know this is quite an achievement.

The benefits for Content Management developers are:

• Single-click deployment.  There are no fiddly release notes to follow when deploying a project to an environment, very handy for those 4am red-eye release slots.
• All environments are stable.  The exception is Dev, but that’s what it’s for.
• Several instances of a project can exist on the same TeamSite box, running code completely independent of each other.

The Problems

Cost

In practice most organisations have two or three TeamSite servers.  One production server for the editorial team, a non-production server for development and testing, and sometimes also a DR server for production fail-over if you’re lucky.

In a perfect world, every environment would have its own physical TeamSite server, or perhaps running in a Virtual Machine (this is another interest of mine, I’ll write about this one day).   For both of these options however, the license cost is prohibitive.  It’s hard to justify this expenditure on a back-office system like a CMS.  So we have to make do, we try to maintain multiple versions of the same project from the same server.

iw-home

One of the best things about TeamSite is the virtual file system it uses for versioning and organising content.  Code is a different story, the arrangement is a bit shoddy.  When you work with TeamSite as a developer, one of the first things you notice is how reliant you are on putting code in the file system.  iw-home is the installation directory for the product, and by default you’re required to put your custom code right alongside it.  Not ideal.

Making changes on the file system directly are a really bad idea for many reasons.  Primarily there is the problem of source control, the details of which I won’t go into here.  TeamSite is essentially a file versioning system, so the solution is obvious after you’ve worked with TeamSite for a bit.  Indeed every customer installation I have ever seen gets around  problem in the same way: pull the file system code into a TeamSite branch and manage it from there.  At Channel 4 this is called “TeamSite_Admin”.  Fidelity and Camelot had something similar.  Developers edit their code in this branch, changes are versioned, and a submit workflow sends the files out to the file system.

Sharing iw-home

Now consider having two project branches, Dev and Test, both on the same TeamSite box using the same iw-home.  Developers and Testers need their environment for very different things.

• Developers are in a constant cycle of breaking things and fixing them.
• Testers require a stable project in a known state.

These are clearly diametric needs, and this can only be solved by finding a way of splitting the code base into isolated environments.

Isolated Environments

A little Perl module called “AreaLib” is at the centre of the solution we’ve developed at Channel 4.  I have to give credit for this work to two highly skilled independent consultants, Steve Martina and Lee Ablett, who wrote this for us… albeit from a proof of concept that I put together

If you include AreaLib in a piece of code, it attempts to work out which branch you’re in.  It does this using a variety of methods, such that it will work within a template, workflow task, CGI, a ‘call server’ routine, or wherever.  When you include this module at the top of your code, it then looks locally in the branch for any further dependencies, falling back to the default locations in iw-perl if they’re not found.

It does this by amending Perl’s @INC path.  For example, if you use the following code in a template, in the branch /default/main/Channel4/dev/BigBrother/WORKAREA/editorial:

use C4::AreaLib;
use C4::EvictRacistHousemate;

The “EvictRacistHousemate” module will be picked up from one of the following locations:

/default/main/Channel4/dev/BigBrother/WORKAREA/editorial/iw_admin/perl/lib/C4/EvictRacistHousemate.pm
/default/main/Channel4/dev/BigBrother/STAGING/iw_admin/perl/lib/C4/EvictRacistHousemate.pm
/default/main/Channel4/dev/STAGING/iw_admin/perl/lib/C4/EvictRacistHousemate.pm
/default/main/Channel4/STAGING/iw_admin/perl/lib/C4/EvictRacistHousemate.pm
iw-home/iw-perl/lib/C4/EvictRacistHousemate.pm
iw-home/iw-perl/site/lib/C4/EvictRacistHousemate.pm
iw-home/iw-perl/vendor/lib/C4/EvictRacistHousemate.pm

This is easy to use from a Template.  However other TeamSite code needs a bit more thought, but it boils down to passing all requests through a wrapper within iw-home.  The wrapper uses AreaLib, and then forwards the request off to the right module for the job.  For example, an external task in a workflow uses the wrapper script as its command, passing the name of the required module in a workflow variable.  Control passes from the wrapper script to the module, which takes over the external task processing and calls back to the workflow.

The end result: all code can run, via a small wrapper and AreaLib, from modules located within the branch.

Soon, I’ll describe the Code Promotion workflow, the way we move all this stuff about in one operation.  I promise some fancy diagrams.