AMP Files

[tino2000]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Back to Developer Guide

Table of Contents

• 1 Introduction


• 2 What is an AMP file?


• 3 The structure of an AMP file


• 4 Customising the structure of an AMP file
  
  
  
  • 4.1 Example
  
  


• 5 AMP Examples

Introduction

This page describes the nature and structure of an Alfresco Module Package (AMP) file, which can be installed to an Alfresco server in order to extend it in some way.

For information related to other ways of extending the repository without using AMP files, see Packaging And Deploying Extensions.

What is an AMP file?

An AMP file is a collection of code, XML, images, CSS, etc. that collectively extend the functionality or data provided by Alfresco. For more information, see Developing an Alfresco Module.

An AMP file can contain as little as a set of custom templates or a new category.  It can contain a custom model and associated UI customisations.  It could contain a complete new set of functionality, for example records management.

As a general rule of thumb, anything that is considered to be an 'installable' extension to Alfresco should be called a module and packaged as one or more AMP files (best practice is to provide one AMP for the repository tier and another for the Share UI tier).

AMP files can be installed into the Alfresco and Share WAR files using the Module Management Tool.  An AMP file has a standard structure (described below), which can be customised if required.

AMP files can also be created via Apache Maven archetypes and have their lifecycle and deployment into Alfresco managed by the Maven Alfresco AMP archetype. For a full description of Maven AMPs Alfresco support see Managing Alfresco Lifecycle with Maven.

Once the contents of the AMP file has been installed into a WAR file using the Module Management Tool, the WAR can be deployed to the application server.  When Alfresco is next started, the installed module configuration will be detected, and the repository will be bootstrapped to include the new module functionality and data.

The structure of an AMP file

An AMP file is ZIP compressed and has a default structure as shown below:

  /
  |
  |- /config
  |
  |- /lib
  |
  |- /licenses
  |
  |- /web
    |
    |- /jsp
    |
    |- /css
    |
    |- /images
    |
    |- /scripts
  |
  |- module.properties
  |
  |- file-mapping.properties

• /config
  

This directory will be mapped into the /WEB-INF/classes directory in the WAR file.  Generally your Spring and UI config will reside in the standard package structure within this directory.

Resources that are used by your extension, such as XML import files or ACP's, may also reside in here, as it can often be convenient to place such things on the classpath for loading from Spring.

As a module developer, you will be required to provide a module-context.xml (and optionally a module-disable-context.xml and module-uninstall-context.xml) in the alfresco.module.<moduleId> package (see Developing an Alfresco Module for more details).  These will reside in the /config directory.

One should place server side webscripts here. AMP -> war file mappings are:

config/alfresco/templates/webscripts -> $CATALINA_HOME/webapps/alfresco/WEB-INF/classes/alfresco/templates/webscripts

config/alfresco/extension/templates/webscripts -> $CATALINA_HOME/webapps/alfresco/WEB-INF/classes/alfresco/extension/templates/webscripts

To be more specific /config/alfresco resides in  $CATALINA_HOME/webapps/alfresco/WEB-INF/classes/alfresco/

• /lib
  

This directory will be mapped into /WEB-INF/lib.  It should contain any jar files that relate to your module.

• /licenses
  

If your module includes any 3rd party jars that require the inclusion of licences that are not currently included in the standard repository WAR, then these should be placed here.

• /web/jsp
  

This directory should contain any custom or modified JSP's that relate to your module.  The contents are mapped into the /jsp directory in the WAR file.

• /web/css
  

This directory should contain any CSS files that relate to your module.  The contents are mapped into the /css directory in the WAR file.

• /web/images
  

Any images that relate to your module should be placed here.  The contents are mapped into the /images directory in the WAR file.

• /web/scripts
  

JavaScript files that are used by the user interface should be placed here.  The contents are mapped into the /scripts directory in the WAR file.

Any folder structures found in any of these directories are mapped, as they are found, into the destination folders in the WAR.

If a file already exists it is overridden in the WAR; however, a recoverable backup is taken by the Module Management Tool.

Any of these directories can be missing or empty.

• module.properties
  

The module.properties file is required to be present in an AMP file.  It contains metadata about the module, most importantly the id and version of the module that this AMP file relates to.  See Developing an Alfresco Module for more details.

• file-mapping.properties
  

If you wish to customise the way in which your AMP file is mapped into the WAR file using the Module Management Tool, then this file should be provided in the AMP file.  If it is not provided, then the default mapping information will be used.  See Customising the structure of an AMP file for more information.

Customising the structure of an AMP file

The structure of an AMP file may be customised via the use of 'file mappings' - these are the rules that govern where the Module Management Tool copies directories in the AMP file to in the target WAR file.  By default, the Module Management Tool uses the following file mappings:

# The default AMP => WAR file mappings
/config=/WEB-INF/classes
/lib=/WEB-INF/lib
/licenses=/WEB-INF/licenses
/web/jsp=/jsp
/web/css=/css
/web/images=/images
/web/scripts=/scripts
/web/php=/php

You can customise the structure of your AMP file by providing a file-mapping.properties file in the root directory of the AMP file.  This is a file in standard Java properties format where the key of each property is the source path in the AMP (with a leading forward slash), and the value of that property is that destination path in the target WAR file (also with a leading forward slash).  The contents of each mapped path will be recursively copied to the target at the time the Module Management Tool installs the AMP into a WAR file.

You may control whether the default mappings are applied or not via the include.default setting - this setting is also provided in the file-mapping.properties.  This boolean property defaults to true (inherit default mappings), but may be set to false as follows:

include.default=false

Custom file mappings always take precedence over the defaults, so you may include the defaults and then override them on a case-by-case basis.

If the source directory does not exist in the AMP file, then the mapping will be ignored; however, the destination directory in the WAR file must exist or a runtime exception will be raised when the Module Management Tool tries to install the AMP.

Example

# 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.
#
/WEB-INF=/WEB-INF
/web=/

AMP Examples

Many of the add-ons available on the Alfresco Add-ons Site are delivered as AMP files, and their source code (where available) provides numerous examples of AMP file construction.

Administration
File Types
Deployment
Customizing and Extending
Packaging
AMP