Setting up a build project for Alfresco Explorer, Share, and WQS extensions When I wrote my book I setup a build project that I used to build both Alfresco Explorer/Repository extensions (AMPs) and Alfresco Share extensions (JARs). Since then I have been using this build project quite a lot in several projects, making minor updates and additions to it. I have also added support for building Alfresco Web Quick Start (WQS) extensions.

What it still lacks though is the possibility to support changes to /WEB-INF/web.xml so I usually do those manually. I plan to eventually move to a maven project structure, overloading WARs, but for now I have to copy a changed web.xml file manually into the deployed web application structure (as the Module Management tool will not update web.xml either). Usually this is necessary when you have SSO requirements, so you would configure it in the production environment but not really in the development environment.

In this blog I will present the build project and go through the structure of it and explain how you build the three different types of Alfresco extension projects. Sometimes you might actually need to build extensions to all three Alfresco WARs (i.e. alfresco.war, share.war, and wcmqs.war). For example, in a recent Alfresco WQS project that I was involved in we had to extend the alfresco.war with a new content model, the share.war with new form definitions, and the wcmqs.war with new website styling, new pages, templates etc.

Note. you might want to download the build project from my download site before reading on so you can have a look at it when reading about it. A link to the download site is available to the right.

The build project structure

The top level build project structure basically has three directories corresponding to the different extension projects that can be built, plus a build project file with accompanying properties file:

The _alfresco directory contains the folder structure and files used to build extensions for the alfresco.war web application. The _share directory contains all files used to build extensions for the share.war web application. And finally the _wcmqs contains all files used to build extensions to the wcmqs.war web application (Web Quick Start).

The build.xml file contains the Apache Ant build script used to build all three Alfresco extensions. The build.properties file is used to configure environment specific application paths, project name, and version.

The _alfresco directory structure (for alfresco.war extensions)

This directory structure will contain files used to extend the Alfresco Explorer and Repository with new custom functionality. The alfresco.war file contains both the Alfresco Explorer UI and the content repository.

Typically you would extend the alfresco.war file when you want to:

• add custom content models
• add custom workflows
• add custom Alfresco Web Scripts
• add custom behaviours

These days most organizations customize the Alfresco Share UI so not much extensions are usually needed for the Alfresco Explorer UI.

The directory structure under the _alfresco directory looks as follows:

There are five top directories under _alfresco and they contain extensions described as follows:

• config – AMP module configuration such as Spring context configuration, bootstrapping configuration, new content models, UI property sheets, workflow definitions
• lib – libraries that are used by the AMP and that does not exist in the tomcat/webapps/alfresco/WEB-INF/lib (i.e. these libs does not exist in the SDK)
• source – Java source code that are used to extend the alfresco.war application and also JavaScript files that are part of the custom solution (JavaScript files are usually installed manually into Data Dictionary/Scripts)
• test – Java source code used to test the Java extensions
• web – custom stylesheets, extra images, new and overridden JSPs, scripts etc

Note. If you change the module.id property value in the build.properties file you would have to update the corresponding module directory name com_mycompany_module_cms. You also need to update the paths in the _alfresco\config\alfresco\module\com_mycompany_module_cms\module-context.xml configuration file, and the paths in the _alfresco\config\alfresco\module\com_mycompany_module_cms\context\bootstrap-context.xml configuration file.

Adding a new custom content model for documents

To add a new custom content model open up the content-model.xml file located in the _alfresco\config\alfresco\module\com_mycompany_module_cms\model directory and start adding your new types and aspects.

To add support for this content model in the Alfresco Explorer UI add property sheet definitions in the web-client-config-custom.xml configuration file located in the _alfresco\config\alfresco\module\com_mycompany_module_cms\ui directory and add UI labels to the webclient.properties file, also located in the _alfresco\config\alfresco\module\com_mycompany_module_cms\ui directory.

Adding a new custom workflow

To add a new advanced workflow, create a new workflow directory under the _alfresco\config\alfresco\module\com_mycompany_module_cms\workflows directory and then add the processdefinition.xml file there. You then deploy the workflow definition via the workflow console: http://localhost:8080/alfresco/faces/jsp/admin/workflow-console.jsp

Refer to the directory with the process definition when deploying:

deploy alfresco/module/com_mycompany_module_cms/workflows/ /processdefinition.xml

Adding a new content model for workflow task types

To add a new custom content model for task types open up the workflow-model.xml file located in the _alfresco\config\alfresco\module\com_mycompany_module_cms\model directory and start adding your task types.

To add support for these workflow task types in the Alfresco Explorer UI add property sheet definitions in the web-client-config-custom.xml configuration file located in the _alfresco\config\alfresco\module\com_mycompany_module_cms\ui directory and add UI labels to the webclient.properties file located in the _alfresco\config\alfresco\module\com_mycompany_module_cms\ui directory.

Adding a new Alfresco Web Script

To add a new Alfresco Web Script put the descriptor, controller, and template for it into the _alfresco\config\alfresco\extension\templates\webscripts\com directory, preferable is to create a subdirectory structure under the webscripts/com directory.

The _share directory structure (for share.war extensions)

This directory structure will contain files used to extend the Alfresco Share collaboration environment. When you build Alfresco Share extensions the share.war web application is extended with new custom functionality.

The share.war file contains the UI referred to as Share and it contains a sharing and collaboration application implemented as so called sites. Recently it is also providing most of the document management functionality that was previously only available in Alfresco Explorer. So you are likely to do almost all of your UI extensions within the Alfresco Share UI.

Typically you would extend the share.war file when you want to:

• customize the site UI with new pages
• customize the site UI with new actions
• customize the user or site dashboards with new dashlets
• configure forms for custom metadata
• configure forms for custom workflows
• creating new Spring Web Scripts
• override existing Spring Surf Web Scripts

The directory structure under the _share directory looks as follows:

There are three top directories under _share and they contain extensions described as follows:

• config – Alfresco Share custom configuration such as UI forms, Surf pages and templates, Surf Web Scripts etc
• lib – libraries that are used by the Java source code extensions but that are not available in the tomcat/webapps/share/WEB-INF/lib directory
• source – Java source code that are used to extend the share.war application

Adding forms for custom metadata or new workflow tasks

To define new forms for custom metadata open up the share-config-custom.xml file located in the _share\config\alfresco\web-extension directory and add them at the end of the file.

Adding support for new types and aspects in the Share UI

Open up the share-config-custom.xml file located in the _share\config\alfresco\web-extension directory and add configuration to the following section:

<config evaluator="string-compare" condition="DocumentLibrary" replace="true">

Adding a new Surf page

To add a new Spring Surf page put the Page XML file into the _share\config\alfresco\site-data\pages directory.

Adding a new Surf template

To add a new Spring Surf template put its Template FreeMarker file into the _share\config\alfresco\templates directory. Preferable is to create a subdirectory structure under the templates directory and put the template there.

Adding a custom CSS file or JavaScript file

To add a custom CSS file or JavaScript file, used by for example a Spring Surf Web Scirpt, add it to the _share\config\META-INF\components directory structure. This means it will be available outside the WEB-INF structure.

Adding Surf Web Scripts

To add a new Surf Web Script put the descriptor, controller, and template in the _share\config\alfresco\site-webscripts\com\mycompany\cms directory structure. You probably want to update the mycompany directory name.

Overriding Surf Web Scripts

To override for example a controller of an already existing Surf Web Script you can do that by putting the custom version of the file under the _share\config\alfresco\web-extension\site-webscripts\org\alfresco\components directory structure. It will then be picked up after the original files and override them.

The _wcmqs directory structure (for wcmqs.war extensions)

The _wcmqs directory structure is used to hold all files needed by your web application. When you build Alfresco Web Quick Start extensions the wcmqs.war web application is extended with new custom functionality. The out-of-the-box WAR file contains the example web application built on top of Spring Surf and OpenCMIS.

Typically you would extend the wcmqs.war file to:

• add new Spring Surf page layouts (i.e. templates)
• add new Spring Surf pages
• add new Spring Surf Web Scripts
• add new styling for the website
• update existing Surf pages and templates

Remember that the complete structure of the web application as well as all the content for the web application is usually served via CMIS from the Alfresco repository. This is setup in Alfresco Share via a site’s document library.

The directory structure under the _wcmqs directory looks as follows:

And this structure pretty much mirrors the wcmqs.war structure that you can see in the tomcat/webapps/wcmqs directory when the WAR has been deployed. The _wcmqs directory structure is meant to only contain files that have been added and original files that have been updated. So it is quite empty when you start.

When you work with the Web Quick Start application you will find that from time to time you will have to copy files from tomcat/webapps/wcmqs to trunk/_wcmqs to be able to update them to your liking.

Here is a list of _wcmqs sub-directories and there meanings:

• css – keeps all new CSS files and any updated existing CSS files
• images - keeps all new images and any updated image files
• js – contains new client side JavaScript files used by the Surf pages
• swf – contains new Flash movies
• WEB-INF
  • chrome – contains borders around regions and components (Surf)
  • classes – any custom Java code
  • lib – extra libs needed by custom Java code
  • pages – Surf page definitions
  • templates – Surf template instances and templates
  • webscripts – Surf Web Scripts

Adding a new Surf page

To add a new Spring Surf page put the Page XML file into the _wcmqs\WEB-INF\pages directory.

Overriding an existing Surf page

To update an existing Spring Surf page copy the Page XML file from the tomcat/webapps/wcmqs/ WEB-INF/pages directory into the _wcmqs\WEB-INF\pages directory. Then start updating it.

Adding a new Surf template

To add a new Spring Surf template put its Template FreeMarker file and template instance file into the _wcmqs\WEB-INF\templates directory.

Updating the root/base template

To do this copy the page.ftl template file from the tomcat\webapps\wcmqs\WEB-INF\webscripts\common directory into the _wcmqs\WEB-INF\webscripts\common directory. Then start updating it.

Adding a custom CSS file or JavaScript file

To add a custom CSS file or JavaScript file, used by for example a Spring Surf Web Scirpt, add it to the _wcmqs\css or _wcmqs\js directory respectively.

Adding Surf Web Scripts

To add a new Surf Web Script put the descriptor, controller, and template in the _wcmqs\WEB-INF\webscripts directory structure. You probably want to add a directory structure under the webscripts directory.

Overriding Surf Web Scripts

To override for example a controller of an already existing Surf Web Script you can do that by copying the original file from the tomcat/webapps/wcmqs/WEB-INF/webscripts to the _wcmqs\WEB-INF\webscripts directory. Then start updating it.

Configuring the build project for your environment

The build.properties file is the one stop place for configuring the build project for your environment. It contains the following properties that should be setup to match your local installations of Alfresco, SDK etc:

• alfresco.dir – should point to the Alfresco installation where the extensions should be deployed (e.g. c:/Alfresco, /opt/alfresco3.4, \\\\server\\sharedfolder)
• alfresco.sdk.dir – should point to where the Alfresco SDK has been installed (e.g. X:/tools/alfresco-community-sdk-3.4.b, C:/AlfrescoSDK)
• jdk.dir – should point to where you have the Java Development Kit installed; only used by one of the ant targets to restart Alfresco from the development environment. Not strictly needed to build the extension artefacts

The properties file also has a couple of properties to set organization name, project name, and version etc:

• org.name – set this property to the company name or the name of your organization (do not use spaces)
• project.name – set this property to the name of the project
• project.version – set this to the current version of the project (do not use version names like RC2 as only digits and dots (.) are allowed in AMP module versions)
• module.id – this property is used when you build alfresco.war AMP extensions. The AMP module id should include your company domain (e.g. com_mycompany_module_cms). When you set this property you also need to update the name of a directory under the _alfresco/ folder structure, we will see later where.

The produced artefacts

When the build.properties file has been updated with your local application paths and project name etc, and you build the different extensions, the following artefacts are produced:

• MyCompany_MyProj_Alfresco_Code_1.0.amp – this is an AMP that can be deployed by running the Module Management tool to extend the alfresco.war (Alfresco Explorer/Repository)
• MyCompany_MyProj_Share_Code_1.0.jar – this is JAR extension for Alfresco Share and can be dropped straight into tomcat/webapps/share/WEB-INF/lib
• MyCompany_MyProj_WebQS_Code_1.0.zip – this is an extension to the Web Quick Start web application in the form of a ZIP file that can be extracted over the tomcat/webapps/wcmqs directory

You get the above filenames if you use the following settings for the organization and project properties:

• org.name=MyCompany
• project.name=MyProj
• project.version=1.0

The ant build file has targets that can be used to deploy these artefacts automatically into the correct places without having to do it manually.

Building Alfresco Explorer/Repository extensions

The relevant ant targets for building alfresco.war extensions are:

• package-alfresco-amp – this target builds the alfresco.war extension AMP and places it in trunk/build/dist (e.g. MyCompany_MyProj_Alfresco_Code_1.0.amp)
• deploy-alfresco-amp – this ant targets builds the extension AMP and then deploys it by using the Module Management Tool (MMT). This is the ant target you will most likely use on a regular basis when building Alfresco Explorer/Repository extensions. Alfresco needs to be stopped before using it and it will also require you to have made a copy of the alfresco.war file called alfresco.war.bak

Running the deploy-alfresco-amp target typically looks like this (stop Alfresco first):

X:\work\blogging\trunk>x:\tools\apache-ant-1.7.1\bin\ant -f build.xml deploy-alfresco-amp
Buildfile: build.xml

clean-reset-war:
     [echo] Deleting X:/Alfresco3.4dBlogg/tomcat/webapps/alfresco dir and copying back original alfresco.war from alfresco.war.bak
     [echo]
   [delete] Deleting: X:\Alfresco3.4dBlogg\tomcat\webapps\alfresco.war
   [delete] Deleting directory X:\Alfresco3.4dBlogg\tomcat\webapps\alfresco
     [copy] Copying 1 file to X:\Alfresco3.4dBlogg\tomcat\webapps

clean:

mkdirs:
    [mkdir] Created dir: X:\work\blogging\trunk\build\dist
    [mkdir] Created dir: X:\work\blogging\trunk\build\lib
    [mkdir] Created dir: X:\work\blogging\trunk\build\classes
    [mkdir] Created dir: X:\work\blogging\trunk\build\classes_share

compile:

package-alfresco-jar:
     [echo] Packaging extension JAR for AMP
      [jar] Building MANIFEST-only jar: X:\work\blogging\trunk\build\lib\MyCompany_MyProj_Alfresco_Code_1.0.jar

package-alfresco-amp:
     [echo] Packaging extension AMP file for alfresco.war
      [zip] Building zip: X:\work\blogging\trunk\build\dist\MyCompany_MyProj_Alfresco_Code_1.0.amp

deploy-alfresco-amp:
     [echo] Merges extension AMP file into build/webapps/alfresco.war
     [java] Installing AMP './build/dist/MyCompany_MyProj_Alfresco_Code_1.0.amp' into WAR 'X:/Alfresco3.4dBlogg/tomcat/webapps/alfresco.war'
     [java] Adding files relating to version '1.0' of module 'uk_co_hrwallingford_module_cms'
     [java]    - File '/WEB-INF/lib/MyCompany_MyProj_Alfresco_Code_1.0.jar' added to war from amp
     [java]    - File '/WEB-INF/classes/alfresco/extension/alfresco-global.properties' added to war from amp
     [java]    - File '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/ui/web-client-config-custom.xml' added to war from amp
     [java]    - File '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/ui/webclient.properties' added to war from amp
     [java]    - Directory '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/ui' added to war
     [java]    - File '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/model/content-model.xml' added to war from amp
     [java]    - File '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/model/workflow-model.xml' added to war from amp
     [java]    - Directory '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/model' added to war
     [java]    - File '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/log4j.properties' added to war from amp
     [java]    - File '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/context/services-context.xml' added to war from amp
     [java]    - File '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/context/bootstrap-context.xml' added to war from amp
     [java]    - Directory '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/context' added to war
     [java]    - File '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/module-context.xml' added to war from amp
     [java]    - File '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/messages/patch-messages.properties' added to war from amp
     [java]    - File '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/messages/model-messages.properties' added to war from amp
     [java]    - Directory '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms/messages' added to war
     [java]    - Directory '/WEB-INF/classes/alfresco/module/com_mycompany_module_cms' added to war
     [java]    - File '/WEB-INF/classes/META-INF/faces-config.xml' added to war from amp
     [java]    - Directory '/WEB-INF/classes/META-INF' added to war

BUILD SUCCESSFUL
Total time: 1 minute 3 seconds

Building Alfresco Share extensions

The relevant ant targets for building share.war extensions are:

• package-share-jar – this target builds the share.war extension JAR and places it in trunk/build/lib (e.g. MyCompany_MyProj_Share_Code_1.0.jar)
• deploy-share-jar – this ant targets builds the extension JAR and then deploys it by copying it to tomcat/webapps/share/WEB-INF/lib. You will most likely use this ant target on a daily basis when working with Share extensions

When working with Share extensions you can setup Apache Tomcat to monitor the extension JAR, and when it is updated, automatically redeploy the share web application context. To do this open up the tomcat/conf/context.xml file and add a line as in the following example:

<Context>
    <WatchedResource>WEB-INF/web.xml</WatchedResource>
    <WatchedResource>WEB-INF/lib/MyCompany_MyProj_Share_Code_1.0.jar</WatchedResource>

This means that you just have to execute the deploy-share-jar target and the share web application is automatically updated with the customizations without you having to restart Alfresco.

Sometimes it is necessary to also refresh Spring Surf Web Scripts if you have made changes to those or added new once. This is done via the http://localhost:8080/share/service/index URL and clicking on the "Refresh Web Scripts" button.

Running the deploy-share-jar target typically looks like this:

clean:
   [delete] Deleting directory X:\work\blogging\trunk\build

mkdirs:
    [mkdir] Created dir: X:\work\blogging\trunk\build\dist
    [mkdir] Created dir: X:\work\blogging\trunk\build\lib
    [mkdir] Created dir: X:\work\blogging\trunk\build\classes
    [mkdir] Created dir: X:\work\blogging\trunk\build\classes_share

compile-share:

package-share-jar:
     [echo] Packaging extension JAR file for share.war
      [jar] Building jar: X:\work\blogging\trunk\build\lib\MyCompany_MyProj_Share_Code_1.0.jar

deploy-share-jar:
     [echo] Copies extension JAR file to share.war WEB-INF lib
     [copy] Copying 1 file to X:\Alfresco3.4dBlogg\tomcat\webapps\share\WEB-INF\lib

BUILD SUCCESSFUL
Total time: 0 seconds

Building Alfresco Web Quick Start extensions

The relevant ant targets for building wcmqs.war extensions are:

• package-wcmqs-zip – this target builds the wcmqs.war extension ZIP and places it in trunk/build/lib (e.g. MyCompany_MyProj_WebQS_Code_1.0.zip)
• deploy-wcmqs-zip – this ant targets builds the extension ZIP and then deploys it by unzipping the file over the tomcat/webapps/wcmqs directory. You will most likely use this ant target on a daily basis when working with Web Quick start extensions

Running the deploy-wcmqs-zip target typically looks like this:

X:\work\blogging\trunk>x:\tools\apache-ant-1.7.1\bin\ant -f build.xml deploy-wcmqs-zip
Buildfile: build.xml

clean:
   [delete] Deleting directory X:\work\blogging\trunk\build

mkdirs:
    [mkdir] Created dir: X:\work\blogging\trunk\build\dist
    [mkdir] Created dir: X:\work\blogging\trunk\build\lib
    [mkdir] Created dir: X:\work\blogging\trunk\build\classes
    [mkdir] Created dir: X:\work\blogging\trunk\build\classes_share

package-wcmqs-zip:
     [echo] Creates a zip file called ${package.file.zip}, which can be unzipped on top of an exploded WQS Surf web app
      [zip] Building zip: X:\work\blogging\trunk\build\lib\MyCompany_MyProj_WebQS_Code_1.0.zip

deploy-wcmqs-zip:
     [echo] Unzips the ./build/lib/MyCompany_MyProj_WebQS_Code_1.0.zip file into X:/Alfresco3.4dBlogg/tomcat/webapps/wcmqs
    [unzip] Expanding: X:\work\blogging\trunk\build\lib\MyCompany_MyProj_WebQS_Code_1.0.zip into X:\Alfresco3.4dBlogg\tomcat\webapps\wcmqs

BUILD SUCCESSFUL
Total time: 0 seconds