Maven + Alfresco : Creating AMP

Hello everyone,

Recently I just finished the excellent Maven book written by A.Heritier and N.De Loof.
This is the kind of book I love because it is not just a catalog of functions but a big use case with idea and thinkings! So if you have not yet, I suggest you buy it at this address or any other good bookstore that has Technology / Computers shelf. Sadly it's only in French... It's a good ocasion to start learning french :)

I digress ... what I would like to share today is the integration between Maven and Alfresco. I think it's time to have a little reflection on this topic during several posts.

If you use a little bit Maven and Alfresco, you know there's something on the subject.
In fact when we go to this address, we can found all information to build Alfresco via Maven. Documentation is not necessarily clear at the first glance but after a while, you begin to understand all the ins and outs.

Let's start an example

I want to create an AMP to add my custom data model and my custom web client config.

In my toolbox, I have one maven plugin : maven-amp-plugin and one maven archetype maven-alfresco-amp-archetype.

For now I will only use the plugin. I want to start a little bit "From scratch". It's more shaping.

In pre-requisite, I installed Eclipse 3.5 and Maven 2.2.
I set the environment variables MAVEN_HOME and I configured my Eclipse workspace with this command in my eclipse workspace folder.

mvn archetype:create -DgroupId=fr.opensourceecm -DartifactId=alf-amp-osecm -Dpackagename=fr.opensourceecm.alf.amp.osecm

How to Create my AMP ?

1. Create Maven 2 project
Via a command line in my Eclipse Workspace Folder :

mvn archetype:create -DgroupId=fr.opensourceecm -DartifactId=alf-amp-osecm -Dpackagename=fr.opensourceecm.alf.amp.osecm

I create a complete folder tree of Maven 2 project (type jar).

2. Clean generated sample
I delete the subfolders of src/main/java and src/test/java to remove default class generated.

3. Add my custom model
In the src/main/config/model, I add my data model: openSourceEcmModele.xml

NOTES If you have no model, you can take "customExample.xml" from an Alfresco extension folder ( tomcat\shared\classes\alfresco\extension)

4. Add my web-client-config
In the src/main/config/ui, add the client configuration web openSourceEcm-web-client-config.xml

NOTES
If you have no model, you can take "web-client-config-custom.xml.sample" from an Alfresco extension folder ( tomcat\shared\classes\alfresco\extension)
NOTES
Previously, we have verified that the two above files are well-formatted and valid using the principles of dynamic models: http://wiki.alfresco.com/wiki/Dynamic_Models

5. Add module-context.xml
In the src/main/config, I created the file module-context.xml. Through this file, I defined spring beans to identify my model and web client configuration.

   
       
           
               alfresco/module/${groupId}.${artifactId}/model/openSourceEcmModele.xml
           
       
   

   
       
           
               classpath:alfresco/module/${groupId}.${artifactId}/ui/openSourceEcm-web-client-config.xml
           
       
   

6. Add module.properties
This file is needed to identify the module and its details when it was installed by the ModuleService. It incorporates the values defined in the pom.xml of the project.

module.id=${pom.groupId}.${pom.artifactId}
module.title=${pom.name}
module.description=${pom.description}
module.version=${pom.version}
module.repo.version.min=3.3

7. Change pom.xml
This file is the unit of work for Maven. This is an XML file that contains information and configuration of your project. Maven used it to configure, generate and build what you may except of your project. It also contains the default values of the projects.

4.0.0
fr.opensourceecm
alf-amp-osecm
amp
0.0.1
alf-amp-osecm
Open Source ECM - Extension



alfresco-public-snapshots
http://maven.alfresco.com/nexus/content/groups/public-snapshots

true
daily



alfresco-public
http://maven.alfresco.com/nexus/content/groups/public




alfresco-public
http://maven.alfresco.com/nexus/content/groups/public


alfresco-public-snapshots
http://repository.sourcesense.com/nexus/content/groups/public-snapshots

true
daily







true
src/main/resources


true
src/main/config
alfresco/module/${groupId}.${artifactId}





org.alfresco.maven.plugin
maven-amp-plugin
3.0.1-SNAPSHOT
true


false

We notice the presence of maven-amp-plugin as dependency. It allows the packaging of the project to AMP (see tags <packaging> amp </packaging>)

To find this dependency, we add the tag <>. It authorize Maven to search and get various dependencies from this place.

We also note the presence of tags <resource> & <filtering> for updating ${...} values by the values defined in the pom.xml.
For example, in our case the value of = $ (pom.version module.version) in the module.properties will be replaced by the value <version> 0.0.1 </version> in the pom.xml. Useful for defining a single variable values.

8. Compilation
Now we have everything to create our module. We just have to execute one command line in our module folder :


Now you can find in the target directory of our project, the file alf-amp-osecm-0.0.1.amp. It's now possible to integrate it in an Alfresco.war.

9. Integration
Copy/paste the file alf-amp-osecm-0.0.1.amp to the amps directory in your Alfresco installation. Then run the installation script : apply_amps.bat in your root Alfresco installation folder. Follow instructions, wait few seconds and after that you have a new alfresco.war in tomcat/webapps folder.

For more information : http://wiki.alfresco.com/wiki/AMP_Files

10. Starting Alfresco
Now you can run Alfresco and verify the integration of your custom module.

Good Job !

For me, this is the simplest example of creating an AMP into Alfresco.

In the next post, we will explore how to manage dependencies and inheritance.

PS : Sources of this project, called alf-amp-osecm, can be downloaded at:
http://www.box.net/shared/tvkc3olink