Implementing a complete high availability Alfresco solution using open source technologies

As a proof of concept, I have done some research and experimenting to determine the best way of clustering Alfresco using completely open source components. I wanted a solution that offered load balancing as well as fault tolerance. There are three components outside of Alfresco that are needed to achieve this.

  1. Load balancer
  2. File system
  3. Database

The load balancer is the simplest component of the three, and the one with the most options available. We just need a load balancer that is able to handle sticky sessions. A dumb load balancer which round robins connections will not work for this scenario.

Alfresco stores all the content as regular files. (Unlike Sharepoint putting content in the database. Yikes!) In order to achieve HA on the content repository we need some sort of clustering or replicating file system. It was not long ago when clustered file systems were out of reach from the open source community. It is great that we now have some viable open source options now.

The last component needed, of course, is the database. Unfortunately, there is no viable multi-master open source option. There are many projects that are working towards this, such as Bucardo. But there is nothing currently that is a drop in replacement and/or production ready. The good news we still have a master-slave(s) setup that can still achieve HA and some sort of load balancing.

Here is the complete solution I implemented:

 

Alfresco: Alfresco Enterprise 4.0.2

I used the latest version of Alfresco Enterprise at the time of writing this, just since it is what I deal with the most. I believe the Community Edition would work just fine as well in this scenario since the heart of Alfresco clustering is within Ehcache.

 

Load balancer: HAProxy

HAProxy is known to be very stable and currently used on some very high traffic web sites. It also gives us the functionality to keep track of sessions via the JSESSIONID cookie. Another great feature is we can take the fault detection further, and test a web script page in Alfresco to determine if Alfresco is currently running. (http://admin:passwd@server1/alfresco/wcs/s is a great page to check.)

Some of you are already looking at the diagram and saying to yourself, “But there is a single point of failure!” HAProxy is a very simple component, and it would be easy to set up an active/passive automatic fail over. Also in a virtualized environment other options are available for redundancy.

I should also note that we have tested HAProxy using single sign on authentication via Active Directory Kerberos. I assume NTLM would work just fine as well.

 

Clustered file system: GlusterFS

I have read good things about GlusterFS, but this was my first hands on experience with it. I was shocked how simple and quick this was to get up and running. A command to add the second server, and another to get the replication going. No messing with configuration files. You can even have 4 servers and enable replication and striping. Similar to the way RAID 10 (or 0+1) works, but across servers. This is a perfect fit for putting Alfresco’s content. Load balancing and seamless fault tolerance.

 

Replicating database: PostgreSQL + pgpool-II

MySQL is still an option, but I chose to go with Postgres here. I liked some of the HA features Postgres provided that seemed lacking in MySQL.  Unfortunately, either way we have to use a master-slave replication configuration.

In order to achieve load balancing and fault tolerance we need to put pgpool-II in front on the databases. It will take read only queries and load balance them between the master and slave(s). Commands that involve any kind of updates, or writes will be forwarded to the master which in turn get streamed to the slaves. This makes writes slower than a standalone database, but most Alfresco installs should be primarily reads for the average implementation. Pgpool can also be configured to use parallel queries. This means large queries can be split up amongst servers.

Pgpool will also detect any faults, so if any of the slaves go down it will just take them out of the pool. And if the master goes down, it will take one of the slaves and promote it to the new master. For the chance of a problem with Pgpool, a similar configuration with HAProxy, an active/passive configuration can be used to add some redundancy.

 

Enjoy your content management uptime! And feel free to drop me a comment.

Alfresco startup script for Ubuntu/Debian

If you have used the script that comes with Alfresco, you have most likely already made your own. I created one for Ubuntu 10.04, but it should work with other variants.

Features

  • NEW! Added support for Alfresco 3.0.X, 3.1.X, 3.2.X, 3.3.X, 3.4.X, and 4.0!
  • Can configure script to run Alfresco as root or a non-privileged user.
  • Firewall rules will be setup at system boot if configured to run as a non-privileged user.
  • Will attempt to shutdown all instances of Alfresco cleanly, will kill them after a set time if they are hung up with a default of 30 seconds.
  • Cleans up rogue processes such as OpenOffice
  • Able to change the umask that Alfresco creates files as. (Handy for multiuser environments.)

Limitations

  • Only tested on Ubuntu Server 10.04 (Lucid LTS)
  • The script calls Java itself to have more control over the process. The down side of this is it will only support Alfresco versions Alfresco 3.0-4.0
  • If you use iptables, and setup Alfresco to run as a non-privileged user, this script will blow away your other rules. Move these rules to your other configuration if needed.

Installation

  1. Copy and paste the script into the file: /etc/init.d/alfresco
  2. Edit the “### Configurable variables” section in the script to suit your environment
  3. chmod +x /etc/init.d/alfresco
  4. update-rc.d alfresco start 99 2 3 4 5 . stop 99 0 1 6 .

Feel free to email myself any bugs, feedback ,or requests. My email address is the user name you see here at the top of the blog @abstractive.ca.

The Script

Here is a link with proper indentation and easier copying:

http://dl.dropbox.com/u/7658190/util/alfresco.sh

Eclipse Run As Java Application – NoClassDefFound

I started having a problem in Eclipse trying to run a Java class with a main() method. (Run As… Java Application).

It kept giving me a NoClassDefFoundException on the class I was trying to run. I swear this worked for this project before. It works fine if I create a new Java project.

I finally managed to fix it by adding a missing buildCommand to my .project file.

This was so frustrating that now that I finally figured it out I decided to share it. I’m using Eclipse Indigo on 64-bit Windows 7 by the way.

Before:

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
  <name>MyJavaProject</name>
    <comment></comment>
    <projects>
    </projects>
    <buildSpec>
    </buildSpec>
    <natures>
      <nature>org.eclipse.jdt.core.javanature</nature>
    </natures>
</projectDescription>

After:

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
  <name>MyJavaProject</name>
  <comment></comment>
  <projects>
  </projects>
  <buildSpec>
    <buildCommand>
      <name>org.eclipse.jdt.core.javabuilder</name>
      <arguments>
      </arguments>
    </buildCommand>
  </buildSpec>
  <natures>
    <nature>org.eclipse.jdt.core.javanature</nature>
  </natures>
</projectDescription>

Show Users In Logs – Alfresco NDC

I was trying to debug a user’s issue on one of our alfresco servers.  I looked through the alfresco log file but of course there are entries from many users there so it was tough to pinpoint the relevant ones.

One of our other alfresco servers adds the user name to the log statements and that would be very helpful in this case.  I couldn’t figure out why our 3.2 server included user names but our 3.4 server did not.

Here’s what I found out:Alfresco’s AuthenticationUtil class (unchanged from 3.2 to 3.4) has a logNDC() method that adds the user name.

NDC (Nested Diagnostic Contexts) is part of Log4j.  Look for “Nested Diagnostic Contexts” way down this page for an explanation: http://logging.apache.org/log4j/1.2/manual.html

Instead of directly using Apache’s NDC, Alfresco uses a delegate to avoid any dependancy. AuthenticationUtil uses org.alfresco.util.log.NDC instead of org.apache.log4j.NDC.

The first thing Alfresco’s NDC class does is to instantiate its delegate (org.alfresco.util.log.log4j.Log4JNDC) which then uses org.apache.log4j.NDC.

HOWEVER

It only does this if org.alfresco.util.log.NDC’s logger has debug enabled.  If not then the delegate is null and any NDC calls do nothing at all.

How to Fix It

The solution is simple, set Alfresco’s NDC logger to debug in your log4j properties file like so:

log4j.logger.org.alfresco.util.log.NDC=debug

That class doesn’t actually log any messages so this won’t add anything to your log files except the user name.

Now just make sure the File appender includes the NDC information by adding %x to the conversion pattern like so:

log4j.appender.File.layout.ConversionPattern=%d{ABSOLUTE} %x %-5p [%c] %m%n

You just get this:

12:25:00,018 User:System DEBUG [org.alfresco.repo.jscript.ScriptLogger] start clean user home script

instead of this:

12:25:00,018 DEBUG [org.alfresco.repo.jscript.ScriptLogger] start clean user home script

You just get this:

12:25:00,018 User:System DEBUG [org.alfresco.repo.jscript.ScriptLogger] start clean user home script

instead of this:

12:25:00,018 DEBUG [org.alfresco.repo.jscript.ScriptLogger] start clean user home script

NOTE

Usually you set your log4j overrides in a file in tomcat/shared/classes/alfresco/extension called custom-log4j.properties or dev-log4j.properties or something like that.  You can go ahead and put the NDC=debug line in this file.  However if you put your new conversion pattern in this file in 3.4 it will be ignored.  See https://issues.alfresco.com/jira/browse/ALF-13742. Instead you must change the conversion pattern in tomcat/webapps/alfresco/WEB-INF/classes/log4j.properties.

About Alfresco Versions

This has been annoying me for a long time.  I looked at Alfresco’s NDC class in 3.2 and it does NOT check if debug is enabled – it just finds org.apache.log4j.NDC and uses it.  I’m not sure when this changed (I haven’t looked at 3.3) but I do know that you need to set NDC to debug in 3.4 and 4.0 as org.alfresco.util.log.NDC is the same in both of those.

 

Alfresco – Version Stamp Your AMP

I always find myself renaming AMP files after building them – I add the module version to the name. Being relatively lazy I decided to see if I could have Alfresco’s ANT build do this for me.

After a bit of trial and error I figured it out and created an ANT macro to do it for me.

I put my macro in a separate file called abstractive-macros.xml.

It has 2 parameters:

  1. modpropsdir is the directory containing the module.properties file. This is where we read the module version. It’s probably already defined in your build.properties under a property called dir.module.MYPROJECT.property.
  2. ampnameproperty is the NAME of the property that contains the AMP file name. We just want the name of the property (not its value) because we want to update the property itself so anything else that uses it will have the new name.

The macro:

  • pulls in the contents of module.properties
  • pulls the extension from the amp file name
  • gets the “module.version” from module.properties
  • builds a new amp file name that includes the version

It turns out you can use javascript within an ANT script – I didn’t know that. You can also use all kinds of other scripts such as groovy, ruby, jython, judoscript, etc.

Here’s the complete macro xml.

abstractive-macros.xml

<project name="abstractive-macros">

   <macrodef name="versionamp" description="Appends the module version to the amp file name">

      <!-- modpropsdir is the VALUE of the dir.module.XXXXX.property -->
      <attribute name="modpropsdir" />

      <!-- ampnameproperty is the NAME of the file.name.amp.XXXXX property
           and its value will be updated to include the module version -->
      <attribute name="ampnameproperty" />

      <sequential>
        <!-- append module version to amp file name -->
        <property file="@{modpropsdir}/module.properties"/>
        <script language="javascript"> <![CDATA[
          amp = project.getProperty("@{ampnameproperty}");
          title = amp.substring(0, amp.indexOf(".amp"));

          version = project.getProperty("module.version");
          project.setProperty("@{ampnameproperty}", title + "_" + version + ".amp");
        ]]> </script>
      </sequential>
   </macrodef>
</project>

The only change to build.xml is to include our new macro xml file.

build.xml

...
  <import file="macros.xml" />
  <import file="abstractive-macros.xml" />
  <import file="projects.xml" />
  ...

And in projects.xml we make the call to the macro. This is done in the package-MYMODULE-extension target. I pass it the path to module properties and the NAME of the property that contains the amp file name.

projects.xml

...
  <target name="package-MYMODULE-extension" depends="package-MYMODULE-jar">

    <versionamp modpropsdir="${dir.module.MYMODULE.property}"
      ampnameproperty="file.name.amp.MYMODULE" />

    <zip destfile="${dir.module.MYMODULE.dist}/${file.name.amp.MYMODULE}" update="true">
      <zipfileset file="${dir.module.MYMODULE.property}/module.properties" />
      <zipfileset file="${dir.module.MYMODULE.dist}/${file.name.jar.MYMODULE}" prefix="lib" />
      <zipfileset dir="${dir.module.MYMODULE}/${dir.name.lib}" prefix="lib" />
      <zipfileset dir="${dir.module.MYMODULE.config}" prefix="config">
        <exclude name="**/module.properties" />
      </zipfileset>
    </zip>
  </target>
  ...

And that’s all there is to it.  So if:

  • your module.properties contains module.version=1.10
  • in your build.properties your file.name.amp.MYPROJECT=MYPROJECT.amp

and you run the package-MYPROJECT-extension target it will generate an amp called MYPROJECT_1.10.amp.

Better Alfresco Script Logging

I was working on some web scripts recently and using log statements to help my development. Does it ever bother you that the only log level available to web scripts is DEBUG? It bugs me.

So I made a simple JavaScript extension that exposes the various log levels of the ScriptLogger to JavaScript.

If you are not familiar with creating Alfresco JavaScript extensions read the Alfresco JavaScript API wiki entry.

The Java class extends BaseScopableProcessorExtension. It provides two log methods for each of these log levels:

  • DEBUG
  • INFO
  • WARN
  • ERROR
  • FATAL

Here are the debug methods an example, the full source code is below:

public void debug(Object message) {
    logger.debug(message);
}

public void debug(Object message, Throwable t) {
    logger.debug(message, t);
}

As you will see below there is not much to the code.

I’ve called it atcLogger (ATC = Abstractive Technology Consulting)

This is nice if, for example, you have a server with the log level set to WARN and you want to quickly toss in a log statement. If you used logger.log(“Some message”) you wouldn’t see the output in the log since that uses DEBUG level. You could use atcLogger.warn(“Some message”) and this would appear in the log without having to change the log level on the server. Even if you change the log level through JMX it’s slightly more effort than lazy developers like me want to expend.

Here is the spring bean for the extension:

<bean id="atc_atcLogger" parent="baseJavaScriptExtension">
    <property name="extensionName">
        <value>atcLogger</value>
    </property>
</bean>

ATCLogger.java:

package ca.abstractive.ecm.alfresco.jscript.io;

import org.alfresco.repo.jscript.BaseScopableProcessorExtension;
import org.alfresco.repo.jscript.ScriptLogger;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

/**
 * Extends Alfresco's JavaScript API to expose a wider range of
 * logging levels.
 *
 * Refer to this class in JavaScript using the alias "atcLogger".
 *
 * @author Tim.Frith
 */
public class ATCLogger extends BaseScopableProcessorExtension {

    // Commons logger
    protected static final Log logger = LogFactory.getLog(ScriptLogger.class);

    /**
     * Standard constructor
     */
    public ATCLogger() {
    }

    /* ------------------------------------------------------------ */
    /* Public methods - available to JavaScript */
    /* ------------------------------------------------------------ */

    /**
     * @see org.apache.log4j.Logger#debug(Object)
     */
    public void debug(Object message) {
        logger.debug(message);
    }

    /**
     * @see org.apache.log4j.Logger#debug(Object, Throwable)
     */
    public void debug(Object message, Throwable t) {
        logger.debug(message, t);
    }

    /**
     * @see org.apache.log4j.Logger#info(Object)
     */
    public void info(Object message) {
        logger.info(message);
    }

    /**
     * @see org.apache.log4j.Logger#info(Object, Throwable)
     */
    public void info(Object message, Throwable t) {
        logger.info(message, t);
    }

    /**
     * @see org.apache.log4j.Logger#warn(Object)
     */
    public void warn(Object message) {
        logger.warn(message);
    }

    /**
     * @see org.apache.log4j.Logger#warn(Object, Throwable)
     */
    public void warn(Object message, Throwable t) {
        logger.warn(message, t);
    }

    /**
     * @see org.apache.log4j.Logger#error(Object)
     */
    public void error(Object message) {
        logger.error(message);
    }

    /**
     * @see org.apache.log4j.Logger#error(Object, Throwable)
     */
    public void error(Object message, Throwable t) {
        logger.error(message, t);
    }

    /**
     * @see org.apache.log4j.Logger#fatal(Object)
     */
    public void fatal(Object message) {
        logger.fatal(message);
    }

    /**
     * @see org.apache.log4j.Logger#fatal(Object, Throwable)
     */
    public void fatal(Object message, Throwable t) {
        logger.fatal(message, t);
    }
}

Possible improvements:

  • expose isDebugEnabled, isInfoEnabled(), etc. to JavaScript

Alfresco List Installed Modules in Explorer Template

UPDATE: I realized that if Alfresco is started with alf_start.bat then this works fine. However if you start it as a service then ALF_HOME and CATALINA_HOME environment variables are not available and it fails. So I’ve updated getCommonArgs() to use hard-coded paths as a work around for now.

Did you ever want to see which modules (AMPs) are currently installed but don’t want to have to log into the server to call the MMT (module management tool) for a list? Or you don’t have access to the MMT on the server. Or maybe you just want to see module version or install dates.

I decided to make this information available in the Alfresco Explorer to make my life easier.

Since the MMT already has a list command I decided just to call it with Java’s ProcessBuilder and parse the output.

Originally I planned to do this as a JavaScript extension that would return a JSON object with the module details. But then I thought this would work nicely in a presentation template that I could tack onto my Alfresco home space or wherever I wanted. So I ended up creating a template extension for Freemarker. The ModuleInfo class is shown below and extends BaseTemplateProcessorExtension.

If you aren’t familiar with extending Freemarker in Alfresco or using custom templates, see the Alfresco Template Guide.

Here is the command we need to run to have the MMT list installed Alfresco modules:

%JAVA_HOME%/bin/java -jar %ALF_HOME%bin/alfresco-mmt.jar list %CATALINA_HOME%/webapps/alfresco.war

And for Share modules we just change the war file it points to:

%JAVA_HOME%/bin/java -jar %ALF_HOME%bin/alfresco-mmt.jar list %CATALINA_HOME%/webapps/share.war

I don’t use ProcessBuilder often at all, but I figured since it has JAVA_HOME, ALF_HOME and CATALINA_HOME in its environment map that it should substitute the values as it’s making the call. Apparently not. Or I wasn’t calling it correctly. In any case I didn’t want to spend much time on that so I “manually” substituted the environment variable values before making the call. This is in the getCommonArgs() method (the full source is included below).

I split the Alfresco module list from the Share module list, having one call for each.

I put the module properties into a map using the names from the MMT output as the keys and I added the Name. So the map includes these properties:

  • Name
  • Title
  • Version
  • Install Date
  • Desription (this isn’t my spelling mistake! The MMT outputs it this way)

Once the template extension is deployed, we just need to make a presentation template that calls it. In the repository in Company Home/Data Dictionary/PresentationTemplates I created ModuleInfo.ftl.

It just calls the Java class to get the module details and throws it into a plain table. Here’s how one of the calls looks:

<#assign alfMods = moduleInfo.getAlfrescoModules()>

Finally, I chose a repository space and set it to use my new custom view.

Here’s what it looks like:

Screen Shot

Here is the spring bean for the template extension:

<bean id="moduleInfoTemplate" parent="baseTemplateImplementation">
    <property name="extensionName">
        <value>moduleInfo</value>
    </property>
</bean>

ModuleInfo.java:

package ca.abstractive.ecm.alfresco.template;

import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.alfresco.error.AlfrescoRuntimeException;
import org.alfresco.repo.template.BaseTemplateProcessorExtension;
import org.apache.commons.io.IOUtils;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

/**
 * Extends Alfresco's FreeMarker API with functions for retrieving
 * information about installed modules.
 * 
 * Refer to this class in FreeMarker templates using the alias "moduleInfo".
 *
 * @author Tim.Frith
 */
public class ModuleInfo extends BaseTemplateProcessorExtension {

    // Commons logger
    protected static final Log logger = LogFactory.getLog(ModuleInfo.class);

    /* ------------------------------------------------------------ */
    /* Public methods - available to FreeMarker */
    /* ------------------------------------------------------------ */

    /**
     * Returns a list of modules currently installed in the Alfresco war.
     *
     * @return a List of module property maps (Name, Title, Version, Install Date, Desription)
     * @throws AlfrescoRuntimeException
     */
    public List<Map<String,String>> getAlfrescoModules() throws AlfrescoRuntimeException {
    	ProcessBuilder processBuilder = new ProcessBuilder();

	String[] args = this.getCommonArgs(processBuilder);
	args[4] += "alfresco.war";

    	return this.getInstalledModules(processBuilder, args);
    }

    /**
     * Returns a list of modules currently installed in the Share war.
     *
     * @return a List of module property maps (Name, Title, Version, Install Date, Desription)
     * @throws AlfrescoRuntimeException
     */
    public List<Map<String,String>> getShareModules() throws AlfrescoRuntimeException {
    	ProcessBuilder processBuilder = new ProcessBuilder();

	String[] args = this.getCommonArgs(processBuilder);
	args[4] += "share.war";

    	return this.getInstalledModules(processBuilder, args);
    }

    /**
     * Gets detailed information about installed modules.
     *
     * @param processBuilder the process builder to be used to execute the command
     * @param args an array containing the command to execute and its args
     * @return a List with a Map for each module
     * @throws AlfrescoRuntimeException if errors retrieving module info
     */
    public List<Map<String,String>> getInstalledModules(ProcessBuilder processBuilder, String[] args) throws AlfrescoRuntimeException {

    	List<Map<String,String>> results = new ArrayList<Map<String,String>>();

    	try {
            processBuilder.command(args);
            Process process = processBuilder.start();

	    InputStream is = process.getInputStream();

	    String output = IOUtils.toString(is);
	    String[] lines = output.split("\n");

	    Map<String,String> workingMap = null;
	    for (String line : lines) {

	        if (line.startsWith("Module")) {
		    if (workingMap != null) {
	  	        Map<String,String> moduleMap = new HashMap<String,String>();
  		        moduleMap.putAll(workingMap);
		        results.add(moduleMap);
 		    }
		    workingMap = new HashMap<String,String>();
		    workingMap.put("Name", this.getModuleName(line));

	        } else {

	    	    String[] prop = this.getModuleProperty(line);
		    workingMap.put(prop[0], prop[1]);
	        }
	    }

	} catch (IOException ioe) {
	    logger.error("Error retrieving module details", ioe);
	    throw new AlfrescoRuntimeException("Error retrieving module details");
	}

	return results;
    }

    /* ------------------------------------------------------------ */
    /* Utility methods - unavailable to FreeMarker */
    /* ------------------------------------------------------------ */

    /**
     * Builds the list of arguments that are common to both Alfresco and Share calls.
     *
     * @param processBuilder the process builder to be used to execute the command
     * @return command and args WITHOUT the war file specified
     */
    protected String[] getCommonArgs(ProcessBuilder processBuilder) {
	String[] args = new String[5];
	args[0] = processBuilder.environment().get("JAVA_HOME") + "/bin/java";
	args[1] = "-jar";
	args[2] = "C:/Alfresco/bin/alfresco-mmt.jar";
	args[3] = "list";
	args[4] = "C:/Alfresco/tomcat/webapps/";

	return args;
    }

    /**
     * Extracts the module name from a line of alfresco_mmt.jar output.
     *
     * @param line a line of output
     * @return the module name
     */
    protected String getModuleName(String line) {
    	// Sample:
    	// Module 'org_alfresco_module_dod5015' installed in 'C:/ALFRES~1/tomcat/webapps/alfresco.war'

    	int startIdx = line.indexOf("'") + 1;
    	int endIdx = line.indexOf("'", startIdx + 1);

    	return line.substring(startIdx, endIdx).trim();
    }

    /**
     * Extracts the property name and value from a line of alfresco_mmt.jar output.
     *
     * @param line a line of output
     * @return an array where [0] = property name, [1] = propery value
     */
    protected String[] getModuleProperty(String line) {
    	// Sample:
    	//   -    Title:        Alfresco DOD 5015 Record Management Extension

    	String[] pair = new String[2];
    	pair[0] = line.substring("   -    ".length(), line.indexOf(":"));

    	int startIdx = line.indexOf(":") + 1;
    	pair[1] = line.substring(startIdx).trim();

    	return pair;
    }
}

ModuleInfo.ftl:

<h3>Installed Alfresco Modules:</h3>

<#assign alfMods = moduleInfo.getAlfrescoModules()>

<#if alfMods?size == 0>
    There are curently no Alfresco modules installed.
<#else>
    <table cellpadding="2">
	<tr>
   	    <th>Name</th>
	    <th>Title</th>
	    <th>Version</th>
	    <th>Install Date</th>
	    <th>Description</th>
	</tr>
	<#list alfMods as module>
	    <tr>
		<td>${module.Name}</td>
		<td>${module.Title}</td>
		<td>${module.Version}</td>
		<#-- convert install date to date so then we can format it back into the string we want -->
		<td>${module['Install Date']?datetime("EEE MMM dd hh:mm:ss zzz yyyy")?string.medium_short}</td>
		<td>${module.Desription}</td>	<#-- the MMT spells it wrong, so we must too -->
	    </tr>
	</#list>
    </table>
</#if>

<h3>Installed Share Modules:</h3>

<#assign shareMods = moduleInfo.getShareModules()>

<#if shareMods?size == 0>
    There are curently no Share modules installed.
<#else>
    <table cellpadding="2">
	<tr>
	    <th>Name</th>
	    <th>Title</th>
	    <th>Version</th>
	    <th>Install Date</th>
	    <th>Description</th>
	</tr>
	<#list shareMods as module>
	    <tr>
		<td>${module.Name}</td>
		<td>${module.Title}</td>
		<td>${module.Version}</td>
		<#-- convert install date to date so then we can format it back into the string we want -->
		<td>${module['Install Date']?datetime("EEE MMM dd hh:mm:ss zzz yyyy")?string.medium_short}</td>
		<td>${module.Desription}</td>	<#-- the MMT spells it wrong, so we must too -->
	    </tr>
	</#list>
    </table>
</#if>

Suggested improvements:

  • change the Java to use regular expressions to extract the details from the MMT output
  • make the presentation template pretty, mine is very plain

Alfresco Process Template on Classpath

Processing a template that is on the classpath instead of in the repository:

I’m deploying an Alfresco module (AMP) with a scheduled script that processes a FreeMarker template. The script resides on the classpath instead of in the repository and I thought it would be cleaner to deploy if the template was also on the classpath. I was sure that processing a FreeMarker template from the classpath must be functionality available in Alfresco out-of-the-box. However, after searching tirelessly for as long as my attention span would allow (admittedly not long) I couldn’t find such a call. So here is what I did…

All work was done on Alfresco 3.2r Enterprise.

The standard JavaScript API allows you to call processTemplate(template, args) on a node. “template” is either a string containing the FreeMarker or a node whose contents contains the FreeMarker. So I looked at org.alfresco.repo.jscript.ScriptNode and in particular at:

public String processTemplate(String template, Object args)

Then I looked at org.alfresco.repo.jscript.ClasspathScriptLocation since I knew the scheduled script bean uses it for the script which is on the classpath.

As described in the Alfresco Wiki (http://wiki.alfresco.com/wiki/3.2_JavaScript_API#Adding_Custom_Script_APIs) I extended the JavaScript API. I’ve already got several handy extensions in a NodeUtilScript Java class with an extension name of “nodeUtil” so I just added to it as follows:

/**
 * Process a FreeMarker Template against the given node.
 *
 * @param templateLocation the classpath of the template to execute
 * @param args Scriptable object (generally an associative array) containing the name/value pairs 
 *			   of arguments to be passed to the template
 * @param node the node to process the template against
 * @return output of the template execution
 * @throws AlfrescoRuntimeException
 */
public String processClasspathTemplate(String templateLocation, Object args, ScriptNode node) {

   ClasspathScriptLocation location = new ClasspathScriptLocation(templateLocation);

   try {
      // retrieve template content
      String template = IOUtils.toString(location.getInputStream());

      // process template
      return node.processTemplate(template, args);

   } catch (IOException ioe) {
      throw new AlfrescoRuntimeException("Error retrieving template", ioe);
   }
}

There’s not much to it:

  • create a ClasspathScriptLocation with a path to the template
  • get the template contents as an InputStream
  • use IOUtils.toString(InputStream) from Apache Commons IO to pull the template into a string
  • call processTemplate() on the given node using the retrieved template string, returning the result

It can then be called from my scheduled script (or from a web script).

Calling Script:

// get a node

var myNode = search.findNode("workspace://SpacesStore/c7e27390-12f0-44dd-b89b-ef63a8320d6b");

// prepare some data to pass to the template
var args = new Array();
args["arg1"] = "Hello";
args["arg2"] = "The World";

// process the template agains the node
var result = nodeUtil.processClasspathTemplate("alfresco/templates/email/MyTemplate.ftl", args, myNode);

MyTemplate.ftl:

I say, ${args[“arg1”]!} to ${args[“arg2”]!}.

Node-uuid is ${document.properties["sys:node-uuid"]}

So after executing the above script “result” contains “I say, Hello to The World. Node-uuid is c7e27390-12f0-44dd-b89b-ef63a8320d6b”.

Having my template deployable within my AMP really simplifies moving from development to UAT to production repositories. I don’t have to remember to actually upload it to the repository separately or to export it as an ACP and bootstrap it.

Of course, in many cases the template is in the repository for a very good reason – so that changes can be made to it by less technical users and those changes can be seen without restarting Alfresco. But it’s still nice to have the choice.

References:

Alfresco Wiki, 3.2 JavaScript API, Adding Custom Script APIs

http://wiki.alfresco.com/wiki/3.2_JavaScript_API#Adding_Custom_Script_APIs

Apache Commons IO (http://commons.apache.org/io/)

IOUtils (http://commons.apache.org/io/api-release/org/apache/commons/io/IOUtils.html)