As you can tell from looking through the other posts on this site, we’ve made a number of customizations (cosmetic and otherwise) to our Alfresco instance.
In order to make it easier to deploy these customizations on different servers (e.g., both our dev and production tiers), we use AMP files in order to bundle up all of our customizations into one easy package that we can deploy quickly.
The Alfresco wiki page on AMP Files gives an overview of how to create an AMP file, but there are two issues with that page. First, it’s a little non-specific on how to set up the structure of the AMP file for this sort of customization use in the first place, and second, it doesn’t give much guidance on how to actually bundle everything up into an AMP file once you’re done. This post will try to address both those issues.
Structure of an AMP file
The structure of the AMP file that we use to customize Alfresco Share is just a folder hierarchy that looks like the following:
We have an equivalent for the main Alfresco WAR, too, but it’s essentially the same idea, so it would be redundant to cover it here.
Mostly, these are just copies of files from within the share.war file, tweaked to customize one thing or another. They are arranged in folders whose names roughly correspond to the names of the directories within the share.war file where they come from (and where they’ll be put back when the AMP is deployed). The real magic of making this into an AMP file instead of just a random collection of files in folders happens in the file-mapping.properties and module.properties files.
The file-mapping.properties file tells the Alfresco Module Management Tool where to deploy all of the files in your AMP within the share.war file. As its name implies, it does the mapping between the folder names in your AMP and the directories within share.war. I believe the file is pretty self-explanatory once you see it:
# Custom AMP to WAR location mappings # The following property can be used to include the standard set of mappings. # The contents of this file will override any defaults. The default is # 'true', i.e. the default mappings will be augmented or modified by values in # this file. # include.default=false # # Custom mappings. If 'include.default' is false, then this is the complete set. # # change the default image for a user /components-images=/components/images # user home icon /components-images-header=/components/images/header # Add new images to default theme. Should probably do a real hub theme sometime. /default-theme-images=/themes/default/images # change login CSS (login.css) for new formatting of the login screen. /default-theme=/themes/default #for the changes to the login screen /global=/WEB-INF/classes/alfresco/templates/org/alfresco/global # change default dashboard presets /messages=/WEB-INF/classes/alfresco/messages /presets=/WEB-INF/classes/alfresco/site-data/presets # change default RSS feed, and disable "my workspaces" dashlet /dashlets=/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/dashlets #add the UserHome link to the header and the default dashboard /header=/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/header #Change the footer to add terms of service, etc. /footer=/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/footer #remove the ability to invite external users to sites /share-invite=/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/invite #Customize help file location, and fix link to webdav version of file /alfresco=/WEB-INF/classes/alfresco #Change the form where people enter their contact info so we disable the fields sourced from CalNet /profile=/WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/profile #for the favicon /root=/ #fixing the log file location /classes=/WEB-INF/classes
As you can see, the path on the left of each line is the path within the AMP folder, and the path on the right of each line is the directory where the files should be placed within the share.war file. Lines that begin with a ‘#’ are just comments to help me remember what each line is for.
The module.properties file is what designates your AMP as an AMP, specifies what version it is, and what version of Alfresco it is designed to work with. The Alfresco Module Management Tool does nice job of deploying newer versions of an AMP over the top of older versions.
Our module.properties file for our Share customizations AMP looks like:
# Share module properties module.id=edu.berkeley.mediahub.share.customizations module.aliases=mediahub-share-customizations module.version=2.0.6 module.title=UC Berkeley MediaHub Share Customizations module.description=A plugin to make UC Berkeley customizations to Alfresco Share. # The following optional properties can be used to prevent the module from being added # to inappropriate versions of the WAR file. module.repo.version.min=3.4.2 module.repo.version.max=3.4.2
The module.id line provides a unique identifier for your AMP. You really do want this to be globally unique, so a good method is to use your domain name, as shown above.
To be perfectly honest, I’m not really sure what the module.aliases line does, or if I need it. I haven’t had time to experiment!
The module.version line is very important—if you make a change to your AMP, be sure to increment the version number here. Otherwise the Module Management Tool won’t know it’s a new version, and won’t take any action when you try to deploy it.
The module.title and module.description lines are self-explanatory. They’re just human-readable descriptions of what this AMP is.
The module.repo.version lines restrict what version(s) of Alfresco your AMP will work with. I would strongly advise you to restrict this to just a single release of Alfresco. This is because the files in your AMP simply overwrite the original files in the WAR files when the AMPs are deployed. They are not merged. In my experience, the original versions of some of the files in my AMPs change with every dot release of Alfresco. So, it’s really important to diff each of the files in your AMP with the original version in each new Alfresco release to make sure that your customizations are still in the right place, still doing the right things, and that there haven’t been other important changes to the files you have in your AMP.
I work hard to keep my modified files as nearly identical to the originals as I possibly can so that this process is as easy as possible. It’s still a bit of a pain in the neck, but the added robustness of having everything nicely packaged in an AMP makes up for it.
Building the AMP file
Once you have your AMP files assembled, you’ll need to turn them into a zip file for deployment. Because I found this rather cumbersome, I wrote a little shell script that I run on my Mac to do this for me. I have a folder that contains my AMP-assembly folders. It looks like:
To assemble the AMP files, I simply launch Terminal and run the build_amps.sh script. That script is as follows:
#!/bin/bash MY_PATH=`dirname "$0"` cd "$MY_PATH" cp -r edu.berkeley.mediahub.alfresco.customizations edu.berkeley.mediahub.alfresco.customizations-build cd edu.berkeley.mediahub.alfresco.customizations-build find . -name "\.*" | xargs rm -rf find . -name "\.*" zip -rv ../alfresco ./* cd .. mv alfresco.zip edu.berkeley.mediahub.alfresco.customizations.amp rm -rf edu.berkeley.mediahub.alfresco.customizations-build cp -r edu.berkeley.mediahub.share.customizations edu.berkeley.mediahub.share.customizations-build cd edu.berkeley.mediahub.share.customizations-build find . -name "\.*" | xargs rm -rf find . -name "\.*" zip -rv ../share ./* cd .. mv share.zip edu.berkeley.mediahub.share.customizations.amp rm -rf edu.berkeley.mediahub.share.customizations-build
Essentially, this script just duplicates the Share AMP assembly and Alfresco AMP assembly folders, clears out any dot files from them (e.g., the Mac ._ files and .DS_Store files), compresses them into a zip file, and then renames that zip file to the correct .amp name.