Customizing KFS using Maven Overlays

Maven Overlay documentation: https://maven.apache.org/plugins/maven-war-plugin/overlays.html

Maven Overlays are a double edged sword. They provide great power to work around extensibility issues, but require discipline to maintain good design and due diligence during upgrades to make sure you are not maintaining old bugs.  

Included in the KFS code base is the overlay-pom.xml file which could be used as the starting point for your overlay project.  If you find that you need to overwrite an entire file from a dependency jar, please create a JIRA and contact kfs.product.team@kuali.co so that we can make sure the code is as extensible as possible with minimal pain. 

Overview

Maven overlays are simple in concept.  They copy the files from the overlay project with the files from the original project into a single artifact.  Any file which is in the overlay project but not the original project is simply copied and treated as a brand new file.  Any file which exists in both the overlay project and the parent project ends up using only the file in the overlay project.  This gives you the power to completely write over delivered KFS classes.  In some cases, that's hard to avoid - for instance when an institution wants to override a JSP or TAG file.  But most of the time, there are other customization hooks which are going to make upgrading easier.  This is what makes Maven overlays the double-edged sword: the mechanism gives you complete customization control, but that control may hurt you as you upgrade if you're not careful.

What has worked for institutions using Maven overlays is to actually create two overlay projects (yes, multiple overlays still work). One intermediate overlay should be for code that your institution is only maintaining until the next upgrade.  This could be a backlog of contributions or bug fixes which you have cherry picked because you weren't ready for the full upgrade yet, but when you do upgrade, they will all be present in the latest version of KFS and therefore are no longer needed as "customizations".  At the upgrade, then, you would simply remove all the customizations in this layer and start over again.

The second overlay project would contain your institutional customizations and overlay your intermediate overlay project. All maven commands for the overlay should simply be run from the most overlaying project - ie, the customization overlay.

Creating the Maven Overlay file structure

Your maven overlay needs to conform to the Maven standard directory layout, so that Maven can find where everything needs to go by its own conventions.

One way you can create the file structure for your overlay project is to simply create the directories manually.  You need three high level directories: src/main/java - where Java files go, src/main/resources - where non Java files go (xml configuration, for instance), and src/main/webapp where the web application related resources (web.xml, jsps, tags) should live.  Under these directories, the traditional KFS project structure (for foundation code, org/kuali/kfs...etc, etc) directories are created; the directory tree may be pretty much duplicated between src/main/java and src/main/resources.

Alternatively, you can use maven's archetype plugin to start the overlay project:

mvn archetype:generate -DgroupId=edu.kuali.kfs 
	-DartifactId=kfs 
	-DarchetypeArtifactId=maven-archetype-webapp 
	-DinteractiveMode=false

This will create a new project as well as skeleton file structure based on the groupId and artifactId values.

In either case, you'll need to copy src/main/config/demo/overlay-pom.xml from the kfs project into the root of your new project and rename it to pom.xml.  This will form the basis of the new pom for your overlay.

Converting from an Ant-based project

If you already have a customization/contribution project based on ant, then you've probably got all the files you need for the overlay within that project.  You simply need to convert the project to follow the conventions of the Maven standard file layout.  You'll need a pom.xml for the converted project; that you can copy from src/main/config/demo/overlay-pom.xml in the kfs project to the root of your contributions/customization project, renaming the file to pom.xml.  Then you need to move the files.  When the product team did the file moving work, we used the Ruby script: src/config/scripts/maven_mover.rb.  This was left in the project as a convenience to implementers, but feel free to move the files around however is most convenient for your institution.  Just as a note, though: your git history will look much cleaner if you move files via the git mv command rather than using regular command line mv commands.

Workflow

Workflow upgrades are found in kfs-core/src/main/config/workflow-upgrades/.  Each month where workflow documents were changed or added has its own directory; files within that are identified by the JIRA which necessitated the change or addition.

The product team decided that it would never create a process to upgrade workflow changes automatically.  This is because implementing institutions should be aware of workflow changes and customize them to the needs of their own institution.  Therefore, looking through these changes should be an important part of an upgrade process.