Breaking Changes

This page lists changes that may break backward compatibility when upgrading the Citeck platform. When upgrading to a new version, it is recommended to review the relevant section and perform the necessary migration steps before updating the production environment.

Release 2025.8

The default permissions calculation logic for system artifacts in ecos-data (ecos-webapp-common:3.18.23) has been changed. If an artifact is a system artifact, all users have read access, while only administrators have write access.

If user-defined data types are marked as system, the new logic will be applied to them. To allow editing access, set system=false — then everyone will be able to edit, or set up a permissions matrix.

Release 2024.8

As part of the 2024.8 release, all out-of-the-box microservices and libraries have been updated.

Version Updates

Updated Java version to 21 (latest LTS at the time of migration);
Updated Spring Boot to 3.3.2 (latest stable at the time of migration);
Updated Spring to 6.1.11 (pulled in with Spring Boot update);
Updated Kotlin version to 2.0.0;
Updated Camunda to 7.21.0;
Updated all other dependencies to the latest stable versions.

Technology Updates

The Nashorn script engine has been replaced with GraalVM JS. GraalVM JS is a modern alternative to the outdated Nashorn. The update allows using the functionality of new JS versions.

More details about engine migration and compatibility.

Improvements

ecos-gateway has been completely rewritten based on spring-cloud-gateway using reactive technologies and virtual threads. This will allow processing a large number of concurrent requests without hitting thread limits.
Contexts like AuthContext, I18nContext, etc. have been improved so that they don’t fill the request stack trace at the HTTP filter level (all stack traces for incoming HTTP requests have been reduced by 4-5 lines).
Microservices no longer register in ecos-registry. Service Discovery works based on the application registry in Zookeeper.
Fixed an issue that prevented an application with a new Hazelcast version from starting if an application with the old version was still running (rolling update when upgrading versions - Hazelcast Enterprise feature).
Added json_logs spring profile. If enabled, logs will be written as JSON objects.

Removal of Deprecated Code

Removed the old RecordsService and all old RecordsDao interfaces. The RecordsServiceFactory.recordsServiceV1 method has been renamed to RecordsServiceFactory.recordsService.
Removed RecordRef.
RecordEvaluatorService and its related classes have been moved from ecos-records to ecos-uiserv, as this functionality is only used there.
All microservices use standard jackson/snakeyaml/guava libraries.
REST controller for RecordsAPI has been removed from ecos-webapp-commons and placed only in ecos-gateway. Microservices should communicate with each other via ECOS WebAPI, REST is only needed for external requests.
Facade logic has been removed from ecos-history and its dependency on mongo has been removed.

Compatibility

Records API compatibility between any new and old microservices is complete. Microservices with updated parent stop registering in ecos-registry and as a result - the old version of ecos-gateway cannot proxy regular REST requests to them (e.g., /gateway/uiserv/api/ui-cache?types=theme). If you first update the gateway to 3.0.0+, then any other microservices can be updated individually.

Potential Script Issues

The new engine, unlike the old one, uses a “secure by default” approach. This means many functions that were available in Nashorn “out of the box” are disabled.

In our solution, we have enabled some of these functions by default:

val defaultHostAccess: HostAccess = HostAccess.newBuilder(HostAccess.SCOPED)
        .allowMapAccess(true)
        .allowListAccess(true)
        .allowArrayAccess(true)
        .allowBigIntegerNumberAccess(true)
        .allowIterableAccess(true)
        .allowIteratorAccess(true)
        .allowAccessInheritance(true)
        .build()

But some parts still require migration (the Nashorn compatibility flag should preferably not be enabled for security reasons):

The functionality of accessing getters by simply specifying the property name (i.e., the ability to write abc.name instead of abc.getName()) is disabled “out of the box” in the new engine.
The functionality of accessing Java classes “out of the box” is disabled.
Java classes that are worked with inside JS must have the @Export annotation on methods and fields that should be accessible from the script.

If there are global issues in BPMN process scripts or calculated attributes or calculated roles, you can always enable compatibility mode with the old JS engine through Spring properties:

ecos.webapp.scripts.graaljs.camunda.nashornCompat: true # задается в ecos-process для скриптов в процессах
ecos.webapp.scripts.graaljs.records.nashornCompat: true # задается в любом микросервисе где хранятся данные (как правило ecos-model)

This mode should preferably be enabled only as a temporary solution, during which you should start migrating scripts to a GraalVM-compatible form.

More details about engine migration and compatibility.

Library Changes

All library versions that are built on Java 8 and intended for old versions of microservices and Alfresco are marked with the _j8 suffix in the version name, and their master branch is named master-j8.

These versions will be maintained independently of the main numbering in the future. The exception is ecos-commons, which for Java 21 has version 3.4+, and for Java 8 has version 2.* and master branch master-2.

Class and Method Changes

Before	After
mu.KotlinLogging	io.github.oshai.kotlinlogging.KotlinLogging
ecos.guava30.com.google.*	com.google.*
ru.citeck.ecos.records2.RecordRef	ru.citeck.ecos.webapp.api.entity.EntityRef
org.apache.commons.collections.*	org.apache.commons.collections4.*
ecos.com.fasterxml.jackson210.*	com.fasterxml.jackson.*
javax.*	jakarta.* (not for all classes, but if javax.* is unavailable after version upgrade, then jakarta should be used)
ecos.org.snakeyaml.engine21.*	org.snakeyaml.engine.*
ru.citeck.ecos.commons.utils.func.*	ru.citeck.ecos.webapp.api.func.*
ru.citeck.ecos.commons.promise.Promises	ru.citeck.ecos.webapp.api.promise.Promises
ru.citeck.ecos.records2.rest.RemoteRecordsUtils.runAsSystem	ru.citeck.ecos.context.lib.auth.AuthContext.runAsSystem(J)

Migrated Microservices

ecos-model	2.28.0+
ecos-notifications	2.20.0+
ecos-content	1.2.0+
ecos-uiserv	2.26.0+
ecos-edi	1.2.0+
ecos-service-desk	1.11.0+
ecos-gateway	3.0.0+
ecos-process	2.21.0+
ecos-integrations	2.21.0+
ecos-ecom	1.8.0+
ecos-transformations	1.11.0+
ecos-history	2.20.0+
ecos-apps	2.20.0+

Migrated version of ecos-community-core — 4.25.0.