MidPoint Customization With Maven Overlay Project

Last modified 03 May 2022 16:36 +02:00


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?

Overlay projects takes midPoint binary distribution (midpoint.war), extracts it, adds your customization to it and then repackages it again. 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 is build using Apache Maven. As midPoint itself is built using Maven and midPoint development binaries are also distributed in Maven repositories this is a natural choice.

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.

Overlay project is combination of Maven WAR Overlay with Spring Boot repackaging. Before Spring Boot adoption it was only the first, and in the future, we hope it will be mainly (and only) Spring Boot packaging - in the meantime, both parts are important.

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).