Visualising Geotagged Content with Google Maps

Following Steve Reiner’s Twitter post last week, I was inspired over the weekend to add a similar Google Maps-based dashlet to share-extras, to show the locations of geotagged content items on a map view.
Since the repository has full support for extracting geographic data using Tika in version 3.4, all I needed to do to assemble some test content was upload a few photos taken on my phone into the site Document Library.
If you look at the Document Details page of a geotagged photo, you’ll see that this displays a latitude and longitude value at the end of the item’s properties list. These are part of a new aspect named Geographic.

Latitude and Longitude on the Document Details page

Latitude and Longitude

Using Firebug’s Net console, I noticed that the JSON data for the document list view makes these values available on a new geographic property placed on each list item.
Firebug Net Console

Firebug's Net Console

So to keep things simple the initial version of the dashlet simply re-used the doclist web script to grab a list of all content items in the root of the document library space, but the final version now on share-extras comes bundled with a dedicated webscript to list all items in the site that have the Geographic aspect applied.
Using this data, the dashlet displays a marker for each geotagged item, auto-centering itself on the centre point of all the items.

Clicking on a marker takes you to the Document Details page for that item. In the next update I’ll look at displaying a snippet of information for the item, which the Google Maps API makes pretty easy.

Share Import-Export 1.1 released

The v1.1.1 release of Share Import-Export has been up for a few days now, but I wanted to summarise some of the changes in the new version.
The most significant addition is support for importing and exporting security groups in JSON format, via the new and scripts.
As well as this the script has been made slightly more flexible, with the addition of a --users argument to allow you to import just a few users from a larger set. Since the sample data contains a large number of users that are used across all the different sample sites, you can now import just the users you need for a particular site.
As well as these functional improvements I’ve started cleaning up the code internally, an area I intend to focus a little more on over the next few weeks. For now I’ve just cleaned up the docstrings within each script, and updating the --help flags to re-use the usage information in there.
Last but not least, I should thank Dick from Formktek for reporting an issue with the user export script, which was causing some exported profile images to become corrupted when saved.
Beyond a few more tidy-ups the code is almost where I want it to be within the current constraints of the repository. But there have been a couple of ideas suggested for future uses of the scripts, so if there’s a particular purpose you think the scripts could have or you just want to share your experiences, please leave a comment below.

Adding dates in alfresco.log

By default, Alfresco’s log4j configuration specifies that only the current system time, and no date, are output as the first entry in log messages output in alfresco.log, producing output such as the following.
12:21:23,658 INFO [org.alfresco.config.JndiPropertiesFactoryBean] Loading properties file from URL [file:/home/wabson/Downloads/alfresco-enterprise-tomcat-3.3.1/tomcat/shared/classes/]
12:21:24,009 INFO [org.alfresco.config.JndiPropertyPlaceholderConfigurer] Loading properties file from class path resource [alfresco/]
12:22:40,726 INFO [org.springframework.extensions.webscripts.TemplateProcessorRegistry] Registered template processor Repository Template Processor for extension ftl
12:22:40,747 INFO [org.springframework.extensions.webscripts.ScriptProcessorRegistry] Registered script processor Repository Script Processor for extension js
12:23:09,470 INFO [org.alfresco.repo.domain.schema.SchemaBootstrap] Schema managed by database dialect org.hibernate.dialect.MySQLInnoDBDialect.
12:23:11,774 INFO [org.alfresco.repo.domain.schema.SchemaBootstrap] No changes were made to the schema.

This is the line responsible for setting the configuration in (found in the root of the classpath in the alfresco webapp)
log4j.appender.File.layout.ConversionPattern=%d{ABSOLUTE} %-5p [%c] %m%n
That’s fine in theory, since the configuration also specifies that the log file should roll over using a date-based suffix on a nightly basis. However, in practice the log rotation can sometimes fail on running systems, leaving log entries spanning more than one day in a single log file and ambiguity over which day a particular message was output on.
Fortunately, log4j’s PatternLayout is quite flexible, and allows you to specify a date-time format instead (in fact, this is the default if no date format specifier is given.
To print the date in ISO-8601 format, e.g. “1999-11-27 15:49:37,459”, use
log4j.appender.File.layout.ConversionPattern=%d{ISO8601} %-5p [%c] %m%n
For classic date format, e.g. “06 Nov 1994 15:49:37,459”, use
log4j.appender.File.layout.ConversionPattern=%d{DATE} %-5p [%c] %m%n
To also add dates into the console logging output (which is redirected into Tomcat’s stdout logs when running as a service), update the property log4j.appender.Console.layout.ConversionPattern.

Refreshing Site Tags in Share

Sometimes the site tag data used in Share’s document library can get out of sync with the tags on the content itself, especially in older versions of the 3.x product.
I came across this today on the Partner Sales Enablement site that we’ve just launched fully today on, but fortunately the tag scope data is easy to rebuild.
To do this, you need to create a small JavaScript file that will execute the ‘refresh-tagscope’ action against a space.

var refresh = actions.create("refresh-tagscope");

Once you’ve created this file (I called mine refresh-tagscope.js) in Data Dictionary > Scripts, use Alfresco Explorer to navigate into the documentLibrary space within the site you want to refresh, and click View Details from the More Actions menu.
You can then use the Run Action dialogue to execute the JavaScript file you’ve just created. You might also want to do the same for the site space itself, which also collects tag scope data.
Once that’s done you should be able to navigate back into the site document library in Share and you should find that the tag data has been fully refreshed!

Site Blog Dashlet for Alfresco Share

Updated December 2010: Site Blog Dashlet is now hosted on Share Extras.
This extension to Alfresco Share provides a custom Site Dashlet, which displays the most recent ten posts from the site blog component.

Site Blog Dashlet

Site Blog Dashlet

To install the dashlet download the ZIP file package the latest blog-dashlet.jar file from the Share Extras project and extract the contents into the tomcat directory of your Alfresco installation drop it into tomcat/shared/lib or WEB-INF/lib inside the Share webapp. The package will install the dashlet web script and a single CSS file.
Also pictured in the screenshot is the Site Tags Dashlet, which displays a tag cloud visualisation for all the tags within a site.

Share Custom Actions in a JAR

Update, 4th May 2011: The Backup action is now part of Share Extras and documentation and downloads are now available on the Custom Backup Action page.
Since the ability to package Share extensions was added in the HEAD codeline some weeks ago, both Kev and myself have demonstrated how you can package up dashlets in a JAR file for deployment into Share.
The example we both used was my Site Tags dashlet that we showed at the Alfresco Meetups last year, but at the Madrid meetup we also showed an example of how Share’s Document Library can be extended with a custom ‘backup’ action.
Custom backup action
Document Library actions have no web-tier webscripts, but hook into the client-side actions framework using a bit of custom JavaScript. Each action has a small 16×16 icon and a bit of CSS code to apply this image, one or more text labels (which should of course be externalised for i18n goodness) and a bit of config to hook them into the app. Lastly, since most actions by their nature do something, it’s likely that they will make a RESTful call back to the repository to perform their work, which may require a custom webscript there.
That’s quite a few files, but fortunately we can use the JAR extension mechanism to package everything up nicely.
Just like the Site Tags dashlet, I set this up in Eclipse using a standard project layout and my share extensions build script (with a couple of minor changes) to build the JAR file.
To make it easy to copy this structure, I’ve uploaded a ZIP of the project directory, containing the following files

  • build.xml – the extensions build script
  • config/alfresco/messages/ – contains the strings used for the action label and confirmation/failure messages
  • config/alfresco/templates/webscripts – contains the repository-tier webscript used to create a back-up copy of the file
  • config/org/springframework/extensions/surf/slingshot-custom-backup-action-context.xml – Spring config used to initialise the i18n messages
  • config/spring-surf-config-custom.xml – not used at present, but could define additional Surf endpoints for calling third-party RESTful services
  • web – contains all client-side resources used by the action

It should be relatively easy to copy this structure to define your own custom action, following the custom action wiki document to understand what each file does. This will help you to build other actions that call back to the repository via a web script, but actions aren’t limited to calling Alfresco services only. For some examples, take a look at my own list of Share action ideas.
Once you have your structure you can build the JAR file using Ant, e.g.


The JAR file can then be dropped into Tomcat’s shared/lib directory, and all that remains is to configure the document actions web scripts to pull in the action definition. This is the slightly fiddly bit.
Firstly, copy the web script configuration file WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/documentlibrary/documentlist.get.config.xml from the Share webapp into the directory alfresco/web-extension/site-webscripts/org/alfresco/components/documentlibrary in Tomcat’s shared/classes to override it. You should see a section <actionSet id="document"> which defines all the actions shown for a normal document in the document list view.
To add the backup action to this list, add the following line just before the </actionset> element for that block.

<action type="action-link" id="onActionBackup" permission="" label="actions.document.backup" />

If you also want the action to show up in the document details view, you need to copy the file WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/document-details/document-actions.get.config.xml into alfresco/web-extension/site-webscripts/org/alfresco/components/document-details in shared/classes in the same way.
Lastly, we need to ensure that the client-side JS and CSS assets get pulled into the UI as unfortunately the config files do not allow us to specify these dependencies.
To do this, we must override the file WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/documentlibrary/actions-common.get.head.ftl. Again, copy this into the corresponding directory in shared/classes/alfresco/web-extension and add the following lines at the bottom of the file.

<@link rel="stylesheet" type="text/css" href="${page.url.context}/res/components/documentlibrary/backup-action.css" />
<@script type="text/javascript" src="${page.url.context}/res/components/documentlibrary/backup-action.js"></@script>

That’s it. Now you can restart Tomcat and you should see the ‘Backup’ action – complete with UI labels and icon – in the Document Library.

Adding Custom Aspect Support in Alfresco Share

Since Alfresco 3.2 introduced the ability to configure the metadata forms used in the Document Library, there have been several good articles published on how to add support for custom document types.
One of the first questions people often ask when they see Share is how they can easily extend the metadata fields that are stored against a document. Whilst this can be done using custom document types, aspects often provide a more agile solution.
So this article should explain how Share can be easily extended to support custom aspects using good practice techniques, specifically

  • Ensuring all extended configuration is placed outside of the share webapp, so protecting it from upgrades and redeployments, and
  • Using i18n labels for all text strings that appear in the UI, thus allowing translation of the labels.

The example provides a number of files, all of which should be placed below the tomcat/shared/classes directory of your Alfresco installation. If you are not using the Alfresco-bundled version of Tomcat then you may need to create this directory yourself and configure Tomcat’s shared classloader to use it.
First you will need to configure the repository with your custom model definition. In my case I am using a simple knowledge base model that defines a single aspect kb:referencable. The aspect adds a new text property that allows a unique KB reference number to be added to documents.
First, the Spring configuration defined in alfresco/extension/kb-model-context.xml

<?xml version='1.0' encoding='UTF-8'?>
    <!-- Registration of new models -->
    <bean id="extension.kb.dictionaryBootstrap" parent="dictionaryModelBootstrap" depends-on="dictionaryBootstrap">
        <property name="models">
     <bean id="extension.kb.resourceBundle" class="org.alfresco.i18n.ResourceBundleBootstrapComponent">
       <property name="resourceBundles">

Then, define the model itself in alfresco/extension/kb-model.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Definition of Knowledge Base Model -->
<model name="kb:knowledgebase" xmlns="">
   <!-- Optional meta-data about the model -->
   <description>Knowledge Base Model</description>
   <author>Will Abson</author>
   <!-- Imports are required to allow references to definitions in other models -->
      <!-- Import Alfresco Dictionary Definitions -->
      <import uri="" prefix="d"/>
      <!-- Import Alfresco Content Domain Model Definitions -->
      <import uri="" prefix="cm"/>
   <!-- Introduction of new namespaces defined by this model -->
      <namespace uri="" prefix="kb"/>
      <!-- Definition of new Content Aspect: Knowledge Base Document -->
      <aspect name="kb:referencable">
         <title>Knowledge Base Referencable</title>
            <property name="kb:documentRef">

The last file in our model definition adds some i18n labels for the aspect and property names. Add the following content to the file alfresco/messages/

# Custom knowledge base messages Reference
kb_knowledgebase.aspect.kb_referencable.title=Knowledge Base Referencable
aspect.kb_referencable=Knowledge Base Referencable

With the model added the repository should start up without errors and will know about the new aspect. In order to use it, we need to configure Share to show this aspect in the Manage Aspects dialogue and to display the KB Reference field in forms, when a node has the aspect applied.
The file alfresco/web-extension/share-config-custom.xml can be used to do both these things.

   <!-- Document Library config section -->
   <config evaluator="string-compare" condition="DocumentLibrary">
         Used by the "Manage Aspects" action
         For custom aspects, remember to also add the relevant i18n string(s)
            cm_myaspect=My Aspect
         <!-- Aspects that a user can see -->
            <aspect name="cm:generalclassifiable" />
            <aspect name="cm:complianceable" />
            <aspect name="cm:dublincore" />
            <aspect name="cm:effectivity" />
            <aspect name="cm:summarizable" />
            <aspect name="cm:versionable" />
            <aspect name="cm:templatable" />
            <aspect name="cm:emailed" />
            <aspect name="emailserver:aliasable" />
            <aspect name="cm:taggable" />
            <aspect name="app:inlineeditable" />
            <aspect name="kb:referencable" />
         <!-- Aspects that a user can add. Same as "visible" if left empty -->
         <!-- Aspects that a user can remove. Same as "visible" if left empty -->
   <!-- cm:content type (existing nodes) -->
   <config  evaluator="node-type" condition="cm:content">
         <!-- Default form configuration used on the document details and edit metadata pages -->
               <show id="kb:documentRef" />
         <!-- Document Library pop-up Edit Metadata form -->
         <form id="doclib-simple-metadata">
               <show id="kb:documentRef" />
            <edit-form template="../documentlibrary/forms/doclib-simple-metadata.ftl" />
         <!-- Document Library Inline Edit form -->
         <form id="doclib-inline-edit">
               <show id="kb:documentRef" />

This configuration will add the KB reference field at the bottom of the main Edit Metadata form, the pop-up edit form used in the document list view and lastly the in-line edit form used for HTML, text and XML content (introduced in Alfresco 3.3).
Note: More advanced control is possible over the placement of the field within the form, but this requires copying over the full form definitions for the cm:content type from the file alfresco/web-framework-config-commons.xml (or alfresco/share-form-config.xml in 3.3 onwards) inside the Share webapp and adding the attribute replace="true" on the <config> element.
Now that you’ve configured Share, you must restart Tomcat so that the changes are picked up. The application should start up and you should be able to add the aspect to some content and see the document reference field appear in forms.
The last thing to do is to add an i18n label for the Knowledge Base aspect in the Manage Aspects dialogue. To do this we need to define a small bit of Spring configuration in the file alfresco/web-extension/custom-slingshot-application-context.xml, which will wire the file we created earlier into Share.

<?xml version='1.0' encoding='UTF-8'?>
   <!-- Add Knowledge Base messages -->
   <bean id="webscripts.kb.resources" class="">
      <property name="resourceBundles">

In versions prior to Alfresco 3.3 (when some changes were made to the Share resource bundle classes) the following configuration must be used instead (note the different class name)

<?xml version='1.0' encoding='UTF-8'?>
   <!-- Add Knowledge Base messages -->
   <bean id="webscripts.kb.resources" class="org.alfresco.i18n.ResourceBundleBootstrapComponent">
      <property name="resourceBundles">

This configuration tells Share to look in the file for aspect labels, in addition to the core message bundles.
With that file added you should be able to restart Tomcat again and see the correct label in the Manage Aspects dialogue. You’ve now fully-customised Alfresco Share to support additional custom aspects.
Update: Thanks to Brian Ochs, who pointed out that the additional message aspect.kb_referencable is also required in
Update: The configuration files in this tutorial can now be downloaded in ZIP format. To use them directly extract the archive into tomcat/shared/classes and restart the server. Please do not use these files, which are now outdated.

Share Extensions Build Script

Update, 4th May 2011: The latest version of the build script and sample Eclipse project is now hosted on Share Extras. For more information please see the Sample Project page.
With Kev’s recent SpringSurf changes in the 3.3 code line, Share extensions are now much easier to deploy as shared libraries. However, it’s still up to individual developers to set up their own project structure and to package this up as a JAR.
So, to build the latest Site Tags dashlet using this method I put together an Ant build script, which hopefully will be useful to others.
As well as building a JAR it also supports the unofficial ZIP structure that we’d used previously to package up sample dashlets, in addition to the AMP format that we use for the more complex DoD extensions for Share.
The build script assumes a standard Alfresco project layout as follows

 /config - all web-tier configuration files, with a top-level 'alfresco' package
 /web - all static resources, e.g. CSS and JS files

You can use the build script with your existing projects if they fit this structure, or you can use my own zipped-up site tags dashlet project as a template for your own. This should import into a fresh Eclipse project but you could extract it elsewhere.
Once your project is set up and you’re ready to package up your extension, you can run the following command to build the JAR.

 ant package-jar

To package up a ZIP or AMP, substitute ‘jar’ in the parameters to ‘zip’ or ‘acp’. Easy, eh?

Opportunistic Alfresco

Great post from Jono at Ubuntu on making the Ubuntu platform better suited to opportunistic development, basically helping people who want to ‘scratch an itch’ but don’t have the time or commitment to write an application in the traditional sense.
This is the first time I’ve come across a term for this sort of activity, but it describes very well what Apple have done so well with their app store, and what many of us hope Google may be about to do better.
The faster development cycle afforded with open source means that such an environment is much better suited in theory to rapid application development than proprietary platforms, but it does require the necessary infrastructure to be in place.
I’ve been having thoughts recently on how we could better support this type of development within Alfresco. Like the iPhone and like Ubuntu, Alfresco is much more than just a product, it’s a solid platform for others to develop on.
In our case the building blocks are the web scripts and Surf frameworks that we recently fed back up into Spring, and the delivery mechanism could easily be provided by the Share UI.
Share already allows developers to define self-contained bits of functionality as dashlets, and also provides mechanisms to manage the configuration and display of these dashlets within the application. That’s 90% of our intrastructure already there.
The missing 10% is a mechanism by which developers can publish these extensions to make them available for others, basically a distibution channel, or if you must, an app store.
This is why I’ve started spec’ing out what I’m tentatively calling Share Components, to provide a directory of Share extensions and an easy mechanism for users to query such directories (note, plural) and install components from them onto their own Alfresco systems.
I’m making it very clear that this is a proposed feature for Share but nonetheless it’s one that I firmly believe is critical to ensuring that others – including our partners and others in the wider community – are able to join up their opportunistic dots using the Alfresco platfom.