Alfresco Module Packages can be a boon, but reverting to a previous version can be pesky. Help is here.
Your Alfresco had been hummingly happily for a while. The sun shines, birds sing, and life is good. However, this morning you installed the new version 2.0 of that shiny AMP add-on that you love, and now Alfresco is refusing to work. With a sigh, you decide to uninstall it and go back to version 1.0.
Confidently, you Google a little bit, and end up following the documentation to uninstall the AMP and reinstall the old and trusty version 1.0. You clear the tomcat/webapps/alfresco and tomcat/webapps/share folders, and restart Alfresco. To your surprise, Alfresco will spit back to you the following message in the logs:
Downgrading of modules is not supported. Module 'org_alfresco_mm_repo' version 2.0
Even worse: Alfresco may not restart at all! You get that funny feeling in your stomach, you breath in and out to dispel the panic attack, and start Googling again. You try all sorts of things, but you can’t revert that AMP and get your Alfresco back.
What’s going on?
Why did that happen? Alfresco keeps track of the installed AMPs, including the version. When you want to attempt to downgrade a module, Alfresco rejects it because it could be potentially dangerous for your repo. For instance, what if your older module has a content model that is missing a type, a property or an aspect?
The problem
Alfresco’s documentation defines the Alfresco Module Package as “… the recommended way of packaging customizations and extensions for deployment, where those extensions depend on third-party libraries, as such dependencies are not yet supported by Simple JAR Modules.”
It is easy to use Alfresco’s Module Management Tool (MMT) utility to add or remove an AMP from a WAR file. After all, MMT just opens the WAR file, which is simply a zip file, and copies the content of the AMP, which is also a zip file, into the WAR — to be precise, it’s usually not a direct copy, as there is some mapping involved, but that’s the basic idea. To uninstall the AMP, MMT would just perform the opposite operation, and that would be it. Simple, right?
Alfresco was hesitant for some time to allow uninstalling AMPs. If the AMP included a content model, removing it could break the repository. The old version of the AMP may not support changes that the new one could have made, such as applying a patch to the DB (unlikely) or making other changes to structure, permissions, etc.
As a safety feature, Alfresco decided that it should not be possible to rollback an AMP to a previous version. Alfresco assumed that new add-ons would be developed in the community, and Alfrescians might install them without knowing anything about internal details. The downgrading restriction is a nice way to protect us from crashing Alfresco or wreaking major havoc. However, few AMP updates include such drastic changes, and sometimes it is just necessary to provide the ability to remove an AMP and allow the developer or administrator to decide.
If it’s so risky, why would anyone do it?
However, in some cases it may be perfectly safe to rollback an AMP, as many of them do not include content models, nor add new properties. In many cases it’s perfectly fine to rollback an AMP, but Alfresco will not budge. Does that mean that we are stuck forever with version 2.0? No way!
How to solve the problem
This problem is not new, and several solutions have been tried before. Some worked well in the past (Alfresco 5.1 and earlier), while others involved a somewhat risky manipulation of the database, and others didn’t quite work. If the Alfresco server can start, consider updating or deleting the module definition in the system store. However, if your server is stuck and unable to start, keep reading.
Our approach is rather simple: patch the file module.properties in the old AMP (and relevant JARs within) to fool ACS into thinking that it is loading a “valid” version, not a previous one. NOTE: This approach is useful on earlier versions, but it is probably the best option for ACS 5.2 to 6.2.2. It may work on future versions as well.
| Alfresco doesn’t want you to rollback AMPs, and with good reason! But sometimes you just know that it would not harm anything, right? Right?? If you are not 100% sure that rolling back that AMP is not going to mess up anything, we advise you to take a backup of your database and the repo (“Safety first!”). |
Step 1: Remove the old Alfresco AMP from the WAR
It is better to start with a brand spanking new Alfresco WAR, because uninstalling AMPs is an error-prone task that can get messy very easily. Another reason to start with a new WAR is having under control the order of the installation of the AMPs, rather than just apply them all in random order. It is always better to have a predictable build process.
In a pinch, it is possible to uninstall the Alfresco AMP using the MMT tool (see “Uninstalling an AMP file”,) or recover the backup of the WARs, but we frown on that.
Regardless of your approach, don’t forget to clear the content of the directories tomcat/temp, tomcat/work, and delete the directories tomcat/webapp/alfresco.
NOTE: These instructions are required only for Alfresco AMPs, not for Share AMPs. At the moment of writing this article, Share does not validate the AMP’s version, which is something that may change in the future.
Step 2: Expand the old AMP file
AMP files are in ZIP format, so you will have to decompress them into a temporary directory.
Step 3: Find module.properties
Go to the temporary directory. Find file module.properties with the version that Alfresco is requesting. The file is located at the directory
<alfresco>/tomcat/webapps/alfresco/WEB-INF/classes/alfresco/module/name_of_your_module/module.properties
Step 4: Update the version number
Update the property module.version in the file module.properties with the higher version (in our example, that would be 2.0,) so we make Alfresco “think” that it is loading the latest AMP.
Step 5: Expand the JAR files within the AMP
It is possible that your AMP may contain JAR files with the same name of the module. Those JAR files may also have a module.properties file, which could override the changes that you just completed. In consequence, we need to update them as well.
Look for JAR files within the temporary folder, where you expanded the AMP, that may contain Alfresco modules. Just like AMPs, Java Archives (aka, JAR files) are also compressed zip files containing classes, directories, and other files (okay, we know you know that, but not everyone is a Java whiz kid like you!) We will have to repeat what we did with the AMP, but this time with the JARs:
- Create a temporary directory and expand the JAR file into that directory.
- Search for module.properties for the JAR file.
- Update property module.version as needed.
- Zip again the temporary directory to re-create the JAR
- Replace the JAR within the AMP.
| Check that the repackaged JAR files have the same structure (folders and files) as the originals! And don’t leave the expanded JAR inside the expanded AMP. |
Step 6: Repack the AMP file
Time to rebuild the AMP file. Zip again the temporary directory into a zip file, and then change the extension to “amp”
Step 7: Deploy the updated AMP
Use your preferred method to deploy again your AMP file, and start Alfresco.
Success!
What? No success? Still seeing the same error? The previous steps should fix the issue, but if they didn’t, no worries! There are three possibilities:
- The new AMP that you created has a different folder structure. Use a zip utility to review and compare the folders and files of the original and the new AMP.
- The AMP module contains a JAR module with the original version (in our example, that would be 1.0.) Review the Step 5 above.
- The JAR module mentioned above may have the correct version, but it was not rebuilt correctly. Use a zip utility to review and compare the folders and files of the original and updated JARs.
Let’s wrap up
Alfresco doesn’t want you to rollback AMPs, and they have good reasons. However, if you are familiar enough with the AMP or you have no alternative, the method described in this article is safer than manipulating the database. To be safe, take a backup of the Alfresco WAR and AMP before proceeding. If you are unfamiliar with the AMP, you may even want to consider getting a backup of the database and the repo before proceeding.
We hope that you found this article helpful. If you need something a bit more complicated, please consider using our support and consulting services. Thanks!
References
- “Module properties files,” Alfresco Content Services 6.2, https://docs.alfresco.com/6.2/concepts/dev-extensions-modules-module-properties.html
- “Uninstalling an AMP file,” https://docs.alfresco.com/6.2/tasks/uninstall-amp.html
- “Undeploy AMP files from Alfresco,” https://blog.arvixe.com/undeploy-amp-file-from-alfresco/. This article shows how to uninstall an AMP by recovering the backup created automatically when you apply an AMP.
- “Downgrading AMP version in Alfresco,” Sujay Pillai, https://sujayopillai.com/2016/08/04/update-amp-version.html. It shows two methods to revert an AMP. The first one modifies the module version in the repository, but you should be able to start the server. The second method manipulates the database, which is inherently risky, and does not work with ACS 5.2 and later.