You are here

Creating a Repository extension project (AMP)

The Alfresco Repository AMP maven archetype can be used to create a new Alfresco Module extension project for the alfresco.war. For more information about this project type see Repository AMP Archetype
This task assumes that you have completed all instructions in Installing and configuring software.
This task shows how you can use the Repo AMP archetype of the Alfresco SDK to generate a repository extension module containing a simple example web script.
  1. Create a suitable directory in which to store all your Maven projects (if you have not already done so), such as alfresco-extensions.
  2. Change into your alfresco-extensions directory.
  3. Run the following command:

    mvn archetype:generate -Dfilter=org.alfresco:
    Important: As the archetypes are available via Maven Central you do not need to specify a catalog.

    You will be prompted to choose an archetype:

    Choose archetype:
    1: remote -> org.alfresco.maven.archetype:alfresco-allinone-archetype (Sample multi-module project for All-in-One development on the Alfresco plaftorm. Includes modules for: Repository WAR overlay, Repository AMP, Share WAR overlay, Solr configuration, and embedded Tomcat runner)
    2: remote -> org.alfresco.maven.archetype:alfresco-amp-archetype (Sample project with full support for lifecycle and rapid development of Repository AMPs (Alfresco Module Packages))
    3: remote -> org.alfresco.maven.archetype:share-amp-archetype (Share project with full support for lifecycle and rapid development of AMPs (Alfresco Module Packages))
    Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 
  4. Enter 2 to have Maven generate an Alfresco Repository Module Package (AMP) project.
  5. You will be prompted to choose an archetype version:

    Choose org.alfresco.maven.archetype:alfresco-amp-archetype version: 
    1: 2.0.0-beta-1
    2: 2.0.0-beta-2
    3: 2.0.0-beta-3
    4: 2.0.0-beta-4
    5: 2.0.0
    6: 2.1.0
    7: 2.1.1
    8: 2.2.0
    Choose a number: 8: 

    Press Enter to select the default (the most recent version).

  6. You will then be prompted to enter a value for the property groupId:

    Define value for property 'groupId': : com.acme

    Here we have specified com.acme representing the domain for a fictional company Specify a groupId matching your company domain.

  7. You will then be prompted to enter a value for the property artifactId:

    Define value for property 'artifactId': : componentX-repo

    Here we have specified componentX-repo representing an X component with a specific extension for the Alfresco Repository. Try and name the Repository extensions in a way so it is easy to see what kind of extension it is for the alfresco.war application. Here are some example names for repo extensions so you get the idea: zip-and-download-action-repo, digital-signature-repo, business-reporting-repo, these repository extensions would typically have corresponding Share extensions if they also include user interface functionality. It is good practice to use the following naming convention for repository extensions: {name}-repo, where -repo indicates that this is an Alfresco Repository extension. Note, hyphens are typically used in artifact IDs.

  8. You will then be prompted to enter a value for the property package:

    Define value for property 'package':  com.acme: : com.acme.componentX

    Here we have specified com.acme.componentX representing an X component Java package. This package will be used for any example Java code generated by the archetype. It is good practice to keep all Java code you write under this package so it does not clash with other components/extensions. Any Spring beans generated by this archetype will use this package in the ID.

    Important: Java packages cannot have hyphens in them.
  9. You will then be prompted to enter Y to accept the values you have entered, or n to reject and change. Press Enter to accept the values.

    A new project directory containing a number of sub-directories and support files for the AMP will be created in the directory componentX-repo.

  10. Change into the freshly created componentX-repo directory and browse the various files and directories to see what has been created.

    The following directory structure has been created for you:

    ├── pom.xml (Maven project file)
    ├──  (Mac/Linux script to have this AMP applied to the Alfresco WAR and run in Tomcat)
    ├── run.bat (Windows script to have this AMP applied to the Alfresco WAR and run in Tomcat)
    ├── src
    │   ├── main
    │   │   ├── amp (For more information about the AMP structure see:
    │   │   │   ├── config
    │   │   │   │   └── alfresco
    │   │   │   │       ├── extension
    │   │   │   │       │   └── templates
    │   │   │   │       │       └── webscripts (Your Web Scripts should go under this directory)
    │   │   │   │       │           ├── webscript.get.desc.xml   (Sample Web Script that you can try out)
    │   │   │   │       │           ├── webscript.get.html.ftl
    │   │   │   │       │           └── webscript.get.js
    │   │   │   │       └── module
    │   │   │   │           └── componentX-repo (AMP Module ID)
    │   │   │   │               ├── (Put default values for properties specific to this extension here) 
    │   │   │   │               ├── context
    │   │   │   │               │   ├── bootstrap-context.xml (Bootstrapping of content models, content, i18n files etc)
    │   │   │   │               │   └── service-context.xml (Your service beans go here)
    │   │   │   │               │   └── webscript-context.xml (Your Web Script Java controller beans)
    │   │   │   │               ├──
    │   │   │   │               ├── model
    │   │   │   │               │   ├── content-model.xml (Content model for your files)
    │   │   │   │               │   └── workflow-model.xml (Content model for workflow implementations)
    │   │   │   │               └── module-context.xml (Spring context file that is picked up by Alfresco)
    │   │   │   ├── (AMP module ID, Version etc)
    │   │   │   └── web (If your AMP has some UI the files would go here, unlikely now when the Alfresco Explorer UI is gone)
    │   │   │       ├── css
    │   │   │       │   └── demoamp.css
    │   │   │       ├── jsp
    │   │   │       │   └── demoamp.jsp
    │   │   │       ├── licenses
    │   │   │       │   └── README-licenses.txt
    │   │   │       └── scripts
    │   │   │           └── demoamp.js
    │   │   └── java (Your Java classes go here, this is where most of the module extension implementation code would go, you can remove the demo component)
    │   │       └── com
    │   │           └── acme
    │   │               └── componentX
    │   │                   └── demoamp  (Demo module component and demo web script controller, can be removed)
    │   │                       ├──
    │   │                       └──
    │   │                       └──
    │   └── test
    │       ├── java
    │       │   └── com
    │       │       └── acme
    │       │           └── componentX
    │       │               └── demoamp
    │       │                   └── test  (Example test of the demo component, can be removed)
    │       │                       └── 
    │       ├── properties
    │       │   └── local
    │       │       └── (environment specific configuration, the local env is active by default)
    │       └── resources
    │           ├── alfresco
    │           │   └── extension
    │           │       └── disable-webscript-caching-context.xml (file to disable server side JavaScript compilation to Java code)
    │           └── 
    └── tomcat
        └── context.xml  (Virtual Webapp context for RAD development)
  11. At this point, before you have made any changes, you can build the project by typing:

    mvn clean install                                
    Attention: Maven will ensure that all requirements are downloaded. This may take some time.

    The project will return with the message BUILD SUCCESS. You should see the AMP artifact installed in your local repository .m2/repository/com/acme/componentX-repo/1.0-SNAPSHOT/componentX-repo-1.0-SNAPSHOT.amp

  12. Run and Test the sample Web Script

    To test the Web Script you will need to start an embedded Tomcat and deploy the Alfresco WAR with the componentX-repo AMP applied. This can be done in two ways:
    1. With mvn clean install -Pamp-to-war
    2. Via the script (or run.bat on Windows), which does the same thing, plus making sure Spring Loaded library is available.
    Important: This will only run the customized Alfresco Repository application (alfresco.war), Alfresco Share UI (share.war) and Search (solr4.war) is not available. If you need those too then use the All-in-One project instead.

    Let's start Tomcat via the script as follows (use run.bat on Windows):

    INFO: WSSERVLET12: JAX-WS context listener initializing
    Apr 30, 2015 10:04:39 AM <init>
    INFO: WSSERVLET14: JAX-WS servlet initializing
    2015-04-30 10:04:39,152  WARN  [shared_impl.util.LocaleUtils] [localhost-startStop-1] Locale name in faces-config.xml null or empty, setting locale to default locale : en_GB
     Apr 30, 2015 10:04:39 AM org.apache.coyote.AbstractProtocol start
    INFO: Starting ProtocolHandler ["http-bio-8080"]
    2015-04-30 10:05:24,545  INFO  [management.subsystems.ChildApplicationContextFactory] [SearchScheduler_Worker-1] Starting 'Transformers' subsystem, ID: [Transformers, default]
     2015-04-30 10:05:24,741  INFO  [management.subsystems.ChildApplicationContextFactory] [SearchScheduler_Worker-1] Startup of 'Transformers' subsystem, ID: [Transformers, default] complete
    Important: You may first need to make the shell script executable using the command chmod +x
  13. Once the web application has started (it may take a little while), point your browser at http://localhost:8080/alfresco/service/sample/helloworld to test the web script. The web script should return the following text: Message: Hello World from JS! HelloFromJava
  14. If you are prompted to login, then use username admin and a password admin.
  15. Configure Enterprise Edition (Optional)

    So far we have used the project with its default configuration, which is using Alfresco Community Edition 5.1.e. If you are going to work with the Enterprise edition then you need to do the following:

    1. Decide what Enterprise version you will be using, if you are going to use version 5.1.0 then you are set as that is the default Enterprise version. If you want to use another version then open up the componentX-repo/pom.xml file and uncomment the <alfresco.version>5.1.e</alfresco.version> property and set the new version number you want to use.
    2. Update the and run.bat scripts to use the Enterprise edition, this is done by using the enterprise profile in the maven command line: mvn clean install -Pamp-to-war,enterprise. Note. this automatically sets the version to 5.1.0 if you have not explicitly set it.
    3. And as you might have guessed, if you are not using the run script, you will have to remember to always activate the Enterprise profile when running: mvn clean install -Pamp-to-war,enterprise
    4. Install an enterprise license, otherwise the server will be in read-only mode, it goes into the following directory:
      ├── src
      │   ├── main
      │   │   ├── amp 
      │   │   │   ├── config
      │   │   │   │   └── alfresco
      │   │   │   │       ├── extension
      │   │   │   │       │   └── license
      │   │   │   │       │       └── acme-5.1.0-enterprise.lic
  16. Stopping the Embedded Tomcat Server

    To stop the Alfresco Tomcat server that was started with the mvn clean install -Pamp-to-war command (either directly or indirectly via the run script), do Ctrl+C in the terminal that was used.

    The Maven embedded tomcat process will terminate after a short wait.

In this tutorial you have learned how to generate, deploy, and run a project using the Repository AMP archetype.

Sending feedback to the Alfresco documentation team

You don't appear to have JavaScript enabled in your browser. With JavaScript enabled, you can provide feedback to us using our simple form. Here are some instructions on how to enable JavaScript in your web browser.