MidPoint Customization With Maven Overlay Project

Last modified 14 Mar 2024 12:46 +01:00
Overlay project feature
This page describes configuration of Overlay project midPoint feature. Please see the feature page for more details.


There are many ways how to customize midPoint behavior. MidPoint is designed with practicality in mind and therefore the most frequent customizations can be done by configuration. But it is not possible to make everything configurable. Some customizations require extension or even modification of midPoint code.

This page describes how to set up and maintain an overlay project that contains midPoint customizations.

How Overlay Works?

MidPoint packaging was migrated from WAR to JAR in 4.6.

Previously it was based on Maven WAR Overlay mechanism combined with Spring Boot repackaging. Overlay project took the admin-gui "Spring-bootified" WAR module (renamed as midpoint.war), opened it, placed some stuff over it, packaged it as WAR and repackaged it with Spring Boot again.

With JAR packaging, only the Spring Boot repackaging is used.

The following text only covers the JAR overlay mechanism now.

Overlay projects creates a new midPoint binary distribution (midpoint.jar) with your customizations added to it. The customizations may be configuration files, web resources (HTML, CSS, images) and even Java code. The overlay can also override stock midPoint files and classes and replace them with custom versions.

The overlay project contains only the customized files. There is no need to copy stock midPoint sources and even binaries. The Maven will download everything that it needs directly from Evolveum repositories. As the overlay project only contains customizations it can easily be maintained in a version control system.

The overlay project effectively does the same stuff the internal midpoint-jar module does. It takes admin-gui and all the other midpoint modules and packages them as Spring Boot JAR. The new JAR "overlay" contains only your stuff directly in the JAR (inside its BOOT-INF/classes directory). Everything else is under WEB-INF/lib only as JAR dependencies.

There is one thing you have to take care of that the midpoint-jar module does - it provides banner.txt. This is the ASCII art at the start of the log. If you don’t need it, it’s OK, you don’t have to do anything. If you want it, either copy it from here or create your own. Name it banner.txt and place it under src/main/resources of your overlay project.

There you go, banner resurrected!

Example Overlay Projects

Following overlay examples are maintained by midPoint team for demonstration and documentation purposes:

Overlay development

Development document is now part of the basic overlay example - see midPoint overlay development. It describes how to build and run the project (including IDE), how to develop against fresh snapshots, how the MidPoint Home Directory customizations and initial-objects customizations work.

The document also includes overlay upgrade notes (starting with upgrade to midPoint 4.1).

Was this page helpful?
Thanks for your feedback