Skip to content

milestone-notes.adoc

Latest commit

 

History

History
285 lines (183 loc) · 14.3 KB

milestone-notes.adoc

File metadata and controls

285 lines (183 loc) · 14.3 KB
Raw

Milestone to Milestone upgrade instructions and notes

Table of Contents
Warning
 This page is written for internal purposes, and we don’t give any guarantee that these instructions and notes are complete, nor that it will work at all…​ but we do our best.

This page contains the upgrade instructions and incompatibility changes that could cause problems during upgrades from a milestone to a milestone, before the "in development" version is released. Useful for continuous testing of the developed features etc.

The upgrade instructions between releases are in the release notes.

4.11-RC2

2026-09-30 Smart Integration: dedicated authorization added

Task: 12091 Description:

Smart Integration suggestion operations now require the new http://midpoint.evolveum.com/xml/ns/public/security/authorization-ui-3#smartIntegration authorization. The backend service enforces it in all channels (GUI, REST, tasks). REST endpoints additionally require http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#smartIntegration. Users without the authorization don’t see the suggestion actions in the GUI.

Statistics and schema match objects (SmartIntegrationArtifactType) are now accessed through the model layer instead of the repository directly. Object-scoped authorizations (read, add, delete) therefore apply to them. Statistics do not require the #smartIntegration authorization.

SmartIntegrationService API changed: getAiInfo, statistics and schema match related methods now take Task and/or OperationResult parameters. Suggestion operation status methods, statistics and schema match related methods now declare CommonException instead of specific exceptions.

Required Upgrade Steps:

  • Grant authorization-ui-3#smartIntegration (and authorization-rest-3#smartIntegration for REST clients such as midPoint Studio) to non-superuser roles that should use Smart Integration suggestions. The owners of suggestion tasks need it as well.

  • Make sure non-superuser roles that use Smart Integration suggestions or statistics have read, add and delete authorizations for SmartIntegrationArtifactType, and add authorization for TaskType (suggestion and statistics operations are submitted as tasks via the model). This applies also to users working with statistics only, without #smartIntegration.

  • Adapt custom code (overlays, scripts) that calls SmartIntegrationService to the new method signatures.

Notes & References:

2026-09-25 Smart Integration: common "c:" namespace prefix removed from service requests

Task: 12098 Description:

Item paths and type names sent to the Smart Integration microservice no longer contain the common midPoint (c:) namespace prefix. For example, c:attributes/ri:login is now sent as attributes/ri:login, and c:UserType as UserType. Other prefixes (ri:, icfs:, extension ones) are kept. This applies to schema attribute names, schema type names, and attribute/attribute-tuple references in the statistics. Statistics stored in midPoint keep fully-qualified paths; only the copy sent to the service is simplified.

SiObjectSchemaType/name in common-smart-integration-3.xsd changed its type from xsd:QName to xsd:string.

Required Upgrade Steps:

  • Use a Smart Integration microservice version that accepts item paths without the c: prefix.

  • If you have custom tooling or prompts that parse the service requests, adapt them to the new path format.

Notes & References:

2026-09-24 Safe Velocity mode introduced

Task: 12389 Description:

As part of providing safe execution mode for midPoint, where expressions and scripts can be safely entered by untrusted users, we are introducing #safe-velocity scripting language. It is based on existing #velocity language, with some restrictions. The existing #velocity scripts should not be affected.

However, because of limitations of the Velocity engine (in particular that it requires the configuration to be global) we had to limit the execution of regular scripts in minor ways:

  1. #parse and #include directives are forbidden

  2. inline definition of Velocity macros is disabled

If you need these features, please set legacyVelocityEngine to true in the config.xml. The drawback is that you won’t be able to use new #safe-velocity language.

Required Upgrade Steps:

  • Check if you need above-mentioned features; if yes, set legacyVelocityEngine to true or migrate your templates.

  • It is recommended to gradually migrate all your scripts to #safe-velocity language, and then disable the full (unsafe) #velocity language completely via expression profiles.

Notes & References:

  • Related commits: <this one>

  • Docs: regular documentation and migration guide will be provided soon

4.11-RC1

2026-09-20 Expression profiles are now fully enforced

Task: 10948 Description:

Expression profiles are now enforced throughout the system.

The idea is that the expression profile for any expression present an object in midPoint repository is derived from the object type (with archetype and/or subtype, if present). These profiles were partially enforced in the previous versions, but now their enforcement is to the full extent.

Although the default setting is still "allow all" - in order to provide smooth migration - there may be situations where expressions were set up but not enforced. In such situations they may now start to fail. Hence, it is necessary to review and optionally adapt your existing expression profile setting to make sure the expressions are compliant with the declared expression profiles.

In rare cases when midPoint cannot determine the expression profile because of missing information about the origin of an expression, it will report them as "TrustDescriptor is required but not set in …​" exceptions. This may indicate a bug in midPoint code. Please report it using the support portal.

Required Upgrade Steps:

  • Check and test your expressions according to declared expression profiles.

  • Watch the migration guide (to be published before 4.11 release) and set up your profiles and manage your expressions accordingly.

2026-09-20 Default expression profiles for midPoint [bulk] actions were changed

Task: 10948 Description:

As part of hardening the enforcement of expression profiles, the defaults for midPoint actions were changed. Please see the documentation.

Required Upgrade Steps:

  • Set explicit expression profiles (via archetypes) on all objects that contain midPoint actions - strongly recommended.

  • Migrate now-deprecated default settings to newly introduced ones.

  • Test your deployment thoroughly.

Notes & References:

  • Related commits: cdb65600

  • Docs: XSD (DefaultExpressionProfilesConfigurationType); regular documentation and migration guide will be provided soon

2026-09-14 Classes related to script execution were renamed

Task: 10948 Description:

As part of hardening the enforcement of expression profiles, clarification of concepts and refactoring of internal classes implementing script execution were done. Specifically, the following classes were renamed:

  • ScriptExpression → Script

  • ScriptExpressionFactory → ScriptFactory

  • ScriptExpressionEvaluationContext → ScriptExecutionContext

  • ScriptEvaluator → ScriptExecutor

It should be generally invisible to a midPoint engineer. The only exceptions are if someone used these classes in scripts, in an overlay, or reference them for detailed logging.

In particular, there is a possibility that isEvaluateNew was checked in this (incorrect) way:

boolean isNew = com.evolveum.midpoint.model.common.expression.script.ScriptExpressionEvaluationContext.getThreadLocal().isEvaluateNew()

The correct way is to simply use:

boolean isNew = midpoint.isEvaluateNew()

Required Upgrade Steps:

  • Check if scripts or an overlay use the above classes, and adapt their use accordingly. In particular, adapt the logging configuration if needed.

Notes & References:

  • Related commits: <this one>

2026-09-11 Script execution in reports may behave slightly differently

Task: 10948 Description:

As part of hardening the enforcement of expression profiles, evaluation of scripts in reports was unified with the evaluation of other scripts and expressions in midPoint. This may affect deployments that depend on the subtleties of previous implementation, for example, that the order of values returned by the script is preserved, which is no longer the case. (MidPoint generally does not guarantee ordering of values.)

Required Upgrade Steps:

  • Check correctness of the reports, especially if they depend on the ordering of values provided by scripts.

Notes & References:

  • Related commits: <this one>

2026-09-03 Password hints now stored as protected string

Task: 12111 Description: Password hints now stored as ProtectedStringType instead of plain strings. See migration guide.

2026-09-03 Changed objects used by Smart integration functionality

Task: 11337 Description: We now use SmartIntegrationArtifactType for data storage, instead of GenericObjectType

Required Upgrade Steps - before upgrade:

  • Delete all tasks related to Smart integration. These tasks carry out intermediate results and are transient in nature. So they can be safely deleted. It is necessary to avoid errors when new data format is used. (If not deleted before the upgrade, it can be done also afterwards, risking some warnings and errors in the log and in GUI.)

Required Upgrade Steps:

  • Apply DB upgrade script

    • Related commits: <this one>

4.11-M6

2026-08-21 Removed obsolete xercesImpl dependency

Task: 12034 Description: Obsolete xercesImpl dependency was removed.

Required Upgrade Steps:

  • Only if you used this dependency in custom Groovy code or overlay code: please find a replacement.

Notes & References:

2026-08-17 Cleaned-up internal APIs related to caching

Task: 11992 Description:

Internal APIs for caching were cleaned-up.

  • Legacy com.evolveum.midpoint.repo.api.Cache and com.evolveum.midpoint.repo.api.CacheListener are gone.

  • They are replaced by com.evolveum.midpoint.repo.api.CacheInvalidationDispatcher and com.evolveum.midpoint.repo.api.CacheDiagnostics (usually you need both).

  • repo.api.CacheDispatcher was renamed to repo.api.ClusterwideCacheInvalidationDispatcher.

  • Cache diagnostics were changed as well, see repo.api.CacheDiagnosticsService.

Required Upgrade Steps: - If you implemented custom caching code (class that extends Cache or CacheListener interfaces): please update your code according to changes in this commit. - If you called CacheDispatcher#dispatchInvalidation method: please call it on ClusterwideCacheInvalidationDispatcher. - If you need cache diagnostics, check the repo.api.CacheDiagnosticsService.

Notes & References:

  • Related commits: <this one>

  • Docs: See CacheInvalidationListener, ClusterwideCacheInvalidationDispatcher, CacheDiagnostics, and CacheDiagnosticsService interfaces.

2026-08-18 Added useTokenOnlyOnConflict flag to iteration specification

Task ID: #11952

Description:

Iteration specification (IterationType) has a new boolean property useTokenOnlyOnConflict and a changed default value for start. By default, useTokenOnlyOnConflict is true, which means the token expression is not evaluated for the first (non conflicting) attempt. The default start value is now 0 when maxIterations is defined, and 1 when it is not. The default of 0 when maxIterations is present preserves backward compatibility for existing deployments (even when adding end), so that new records continue to be iterated starting from 0 consistently with existing records. This can break existing custom token expressions that expect to be evaluated on the first (non conflicting) attempt. In that case, set useTokenOnlyOnConflict to false explicitly.

Required Upgrade Steps:

  • If you use a custom token expression that must be evaluated on the first (non conflicting) attempt, explicitly set useTokenOnlyOnConflict to false in the iteration specification.

  • Review existing iteration configurations to ensure the new default start values (0 when maxIterations is defined, 1 otherwise) still produce the expected token sequence.

  • If necessary, explicitly set start and end to the desired values.

Rollback Procedure (If Upgrade Fails):

  • If unexpected token values appear, explicitly set useTokenOnlyOnConflict to false and review iteration specification according to this description.

Notes & References:

  • Related commits: f9685dbabce0320e622b0deea147eff6ff4a3d82

  • Docs: See unique-account-username.adoc and unique-midpoint-user-name.adoc

  • Affected configs: Object template / Iteration specification

4.11-M5