This document sums up the most important information about midPoint overlays in general.
If you want fresh midPoint SNAPSHOTs for your overlay and published SNAPSHOTs are not enough
(e.g. nightly built hasn’t run yet, or you need to check some unpublished or branch changes)
you need to get the SNAPSHOTs to the local repository under ~/.m2/repository.
# go to updated Evolveum/midpoint clone and run fast developer build, # install is crucial here for publishing to local repository: mvn clean install -DskipTests=true -P -dist # go to your overlay project and run normal build mvn package # you can try to use offline build to be sure no foreign snapshots are # downloaded after update period (but if this fails, run without -o once) mvn -o package
This table summarizes JDK and Spring Boot version changes for main midPoint versions. Overlay examples are tagged for each midPoint release.
These are intended as notes for upgrading your own overlays in the future. Only changes for upgrade to version 4.1 and newer are documented.
Changes for midPoint 4.7:
-
None.
Changes for midPoint 4.6:
-
Spring Boot version 2.7.3 is used.
-
Overlay was overhauled to support JAR packaging instead of WAR packaging, which is not available anymore.
-
See also Release notes for midPoint 4.6.
Changes for midPoint 4.5:
-
Scanning for GUI components is now more focused and overlays using custom GUI components (like those annotated
@PanelTypein this project) need to tell midPoint what other packages to scan. See Customizing classpath scanning in Admin GUI Configuration guide for more information. -
For other changes see Release notes for midPoint 4.5.
Changes for midPoint 4.4.3:
-
Upgrade to Spring Boot version 2.5.14.
Changes for midPoint 4.4.2:
-
More focused GUI component scanning was introduced in 4.4.2 as well, see the note in 4.5. This change was incorporated into support-4.4 branch of this overlay example.
Changes for midPoint 4.4:
-
Spring Boot version 2.5.2 is used.
-
Both Java 11 and 17 can be used for building and running midPoint and midPoint overlays.
-
Admin GUI configuration was changed significantly.
-
Spring Boot repackage now again uses custom
layoutFactorybased onmidpoint-boot-layout(see the POM file). This encapsulates implementation details around setting themidpoint.homeand loading custom libraries from${midpoint.home}/lib. -
See also Release notes for midPoint 4.4.
Changes for midPoint 4.3:
-
Spring Boot version 2.4.3 is used. It is recommended to use dependencies from this list with the versions stated there if it is available.
-
MidPoint module
midpoint-war-layoutis gone (it was unused in 4.2 already), simply remove any references to it. -
See also Release notes for midPoint 4.3.
Changes for midPoint 4.2:
-
Spring Boot version 2.3.3 is used. It is recommended to use dependencies from this list with the versions stated there if it is available.
-
SOAP is gone as are some CXF dependencies. It may be necessary to specify versions for CXF dependencies if used in overlay. CXF servlet must be configured in the overlay now, see Custom SOAP service for example.
-
Usage of midpoint-war-layout is obsolete now. See midpoint.sh for details how
${midpoint.home}/libis included to classpath (search for-Dloader.path). -
Various package name changes in Prism and GUI, changes in
importstatements are required. -
Custom Wicket
Formin midPoint was renamed toMidpointFormto avoid name clashes. -
See also Release notes for midPoint 4.2.
Upgrade to version 4.1:
-
Parent POM
com.evolveum.midpoint:parentwas removed and replaced bycom.evolveum.midpoint:midpoint. -
com.evolveum.midpoint:midpoint-war-layoutwas changed tocom.evolveum.midpoint.tools:midpoint-war-layout. -
See also Release notes for midPoint 4.1.
-
JDK 11 should be used for overlay building and running which is in line with midPoint.
|
|
Overlay likely contains code using various midPoint APIs or customizing GUI. All this code must be revised and regular midPoint release notes consulted. This is out of scope of these upgrade notes which are only related to overlay building and running. |
The overlay project may contain files that are copied to
MidPoint Home Directory when midPoint starts.
Just place these files in src/main/resources/initial-midpoint-home directory in the overlay project.
The whole structure will be extracted under ${midpoint.home}.
This is a good tool how to bundle schema files that contain
custom schema extension.
To include schema extensions, create initial-midpoint-home/schema under main/java/resources.
This will be extracted under ${midpoint.home}/schema and all *.xsd files will
be processed as schema extensions.
TODO: Does this work for ICF bundles? They have different classloading cycle, so it may.
It probably does not work for JDBC (under lib) though, JARs there are probably added
to the classpath before being extracted there.
Additionally, any resource (file) placed under initial-objects will be parsed as object during Midpoint startup.
These objects are meant to be read only once, during the first startup they are discovered.
Recommendations for custom initial objects are:
-
Place each object in a separate XML file.
-
The files have to be named following the
9xx-nnnnnnnn.xmlconvention, wherexxis any number andnnnnnnnnis object name (see the sample project for an example). The files will be imported in the order given by thexxnumbers. -
The prefix
9is a convention to avoid collisions with stock initial objects. -
Don’t forget the OID as it is used to avoid repeated object import on each restart.
Custom initial-objects are part of the initial object import.
This is distinct from post-initial import
of objects placed under ${midpoint.home}/post-initial-objects which occurs later and works differently.
Initial objects are loaded if there is no other object with the same OID,
but files in post-initial-objects are processed and their files renamed not to end with .xml.
Some scenarios require override of initial objects coming from midPoint. One typical example is the modification of the default security policy. This is technically possible, but extreme care must be taken during upgrades of midPoint. Alternatives to the initial objects override is initial-object task that amends objects as necessary. In many cases this is more difficult than the default initial object override.
To override default midPoint initial object:
-
First check the list of existing initial objects, e.g. in the WAR or on GitHub (don’t forget to choose the right branch).
-
Find the file with the object you want to modify, e.g.
015-security-policy.xml. -
If upgrading, check the object for any changes from previous midPoint versions.
-
Copy the file under the same name into your overlay
initial-objectsdirectory. This is essential, because the same object (with the same OID) in alphabetically later file is ignored. -
Modify the object file as necessary.
As an example of this approach you can check Custom SOAP service where default security policy is overridden.
Developing overlay in IDE is not much different from an ordinary project. If Maven project is imported properly, everything should be resolved and no compilation errors found. Occasionally, if sources are generated, the directory with them must be manually added to the project, typically just once. No special Maven profile is needed for IDE development.
To run the overlay in an IDE, just run com.evolveum.midpoint.web.boot.MidPointSpringApplication directly.
IDE should allow you to add "provided" scope to the classpath in the run configuration,
e.g. checkbox Include dependencies with "Provided" scope in IDE run configuration must be enabled.
Otherwise, some Java EE API classes will be reported as not found/undefined during the start.