Migrating a TopLogic application from 8.0.0-alpha6 to 8.0.0-alpha7
Audience: an AI coding agent (or developer) upgrading a TopLogic application project.
Sources: release notes https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha7/ and the
TopLogic Trac tickets flagged RequiresMigration for milestone TL_8.0.0-alpha7 (ticket numbers
are given as #NNNNN; the per-ticket page is https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha7/NNNNN/).
This release is a large one: it introduces model-based access rights that are active and deny-by-default (#29088) and reworks the role/security-structure system (#29221). Every application has mandatory steps in sections 2 and 3, even if it does not change a single line of Java code.
How to use this document
- Work through the sections in order. Section 1 must be done first (the project does not build otherwise); sections 2 and 3 are mandatory for every application; the rest can be done in any order.
- Every step has a Detect line: run the search in the application's source tree. If it finds nothing, the step does not apply — skip it. Do not invent changes for steps that do not apply.
- Many changes are reported as configuration errors at application start or when a view is
loaded (not at compile time). After migrating, start the application, log in — as an
administrator and as a regular (non-admin) user — and open every view; read the log for
ConfigurationException/ configuration errors. - The complete reference for the new access configuration of this release is the demo
application's configuration
com.top_logic.demo/src/main/webapp/WEB-INF/conf/com.top_logic.model.security.SecurityConfigurationService.config.xml(engine tagTL_8.0.0-alpha7). The developer articles on access rights are only shipped with later releases. - Ticket descriptions on Trac are partly German; this document translates the instructions.
Search commands below assume the project root as working directory and GNU grep.
1. Build and platform
1.1 Version bump
Set the TopLogic version to 8.0.0-alpha7 (parent tl-parent-app / tl-parent-core version, or
the tl.version property).
Detect: grep -rn --include=pom.xml -e '8.0.0-alpha6' .
1.2 Operation mode replaces developer mode (#29400, #29383) — mandatory where set
Environment.isDeployed() no longer guesses a developer workspace from the class-path layout
(isJarFile() combined with tl_developerMode). It returns true unless the system property or
environment variable tl_operation_mode is development. tl_developerMode and
Environment.isJarFile() are deprecated and have no effect any more. A run that does not set the
operation mode is treated as a production deployment (deployed theme and script handling, no
modular resource path, IDEOnly commands hidden).
Note: starting through com.top_logic.ide.jetty.Bootstrap (the archetype's Start <App> launch)
sets tl_operation_mode=development itself. The archetype launch configurations Setup and
Test set the parameter explicitly.
- Replace
-Dtl_developerMode=trueby-Dtl_operation_mode=developmentin every Eclipse.launch,.mvn/jvm.config, start script and CI job that runs the application from the workspace. Values:development,test,production(default;testis derived under the test container). - Optional: set
tl_operation_mode=productionexplicitly in deployment descriptors (the archetype'sDockerfile_templatedoes). - Application code that decides on
Environment.isDeployed()should askcom.top_logic.base.operation.OperationModeService.getInstance().getMode()(OperationMode.DEVELOPMENT,TEST,PRODUCTION), as the executability ruleIDEOnlydoes. Note from a Trac comment on #29400: in automated tests (scripted tests, unit tests),isDeployed()is nowtrue(modeTEST), so development-only functions gated byisDeployed()are not available in tests any more; gate them bygetMode() != PRODUCTION. - The Chainsaw
SOCKET_APPENDER(localhost:4445) of the default logging configuration is no longer enabled by developer mode. Developers who forward log events to an external log viewer add-Dtl_logReceiver=trueto the VM arguments. Developers without a log receiver need to change nothing. The appender runs withignoreExceptions="true": without a reachable receiver, socket events are dropped silently; file and console logging are unaffected. - Applications that ship their own copy of the logging configuration
WEB-INF/conf/logging/default.xmlordebug.xml(changed incom.top_logicandcom.top_logic.kafka) must transfer the change to their copy by hand (gate theSOCKET_APPENDERon the system propertytl_logReceiver,ignoreExceptions="true").
Detect:
grep -rn -e 'tl_developerMode' -e 'isJarFile' -e 'isDeployed' --include=*.launch --include=jvm.config --include=*.sh --include=*.bat --include=Dockerfile* --include=Jenkinsfile* --include=*.yml --include=*.java .
find . -path '*WEB-INF/conf/logging/*.xml' -not -path '*/target/*'
1.3 Legacy service module system removed (#29088) — mandatory if used (Java)
The legacy, properties-based service module family of com.top_logic.basic.module is removed:
RuntimeModule, ConfiguredRuntimeModule, MultiRuntimeModule, RuntimeModuleProxy,
ServiceManager, DefaultServiceManager and the constructors ManagedClass(Properties) /
ManagedClass(IterableConfiguration). Convert such a service to typed configuration:
@ServiceDependencies({ OtherService.Module.class }) // replaces getDependencies()
public class MyService extends ConfiguredManagedClass<MyService.Config> {
public interface Config extends ConfiguredManagedClass.Config<MyService> {
@Name("some-option") String getSomeOption(); // one typed getter per former property
}
@CalledByReflection
public MyService(InstantiationContext context, Config config) { super(context, config); }
public static final class Module extends TypedRuntimeModule<MyService> {
public static final Module INSTANCE = new Module();
@Override public Class<MyService> getImplementation() { return MyService.class; }
}
}
The former properties <section> becomes a
<config service-class="..."><instance class="..." some-option="..."/></config> entry; a
configurable implementation class (ConfiguredRuntimeModule class property,
RuntimeModuleProxy) is the class attribute of <instance>.
Detect:
grep -rn -e 'RuntimeModuleProxy' -e 'ConfiguredRuntimeModule' -e 'MultiRuntimeModule' -e 'DefaultServiceManager' -e '\bServiceManager\b' -e 'extends RuntimeModule\b' -e 'import com.top_logic.basic.module.RuntimeModule;' --include=*.java .
grep -rn -e 'super(.*[Pp]roperties' -e 'IterableConfiguration' --include=*.java src
1.4 Further Java API changes of the access-rights rework (#29088) — mandatory if used
- The no-argument /
Propertiesconstructors ofDataManager,FileSystemCache,FlexDataManagerFactory,EncryptedFlexDataManagerFactory,InitialDataSetupServiceandCommandApprovalServiceare replaced by(InstantiationContext, Config)constructors; subclasses must offer them. BoundChecker#getRolesForCommandGroup(...)must return a non-null collection (Collections.emptySet()instead ofnull); the defaultallow(...)no longer toleratesnull.RoleComputation(StorageAccessManager)becameRoleComputation(Person, StorageAccessManager);ElementAccessManagergained the hooksgetSecurityParents(BoundObject)andcanHaveRole(TLClass, BoundedRole)for application access managers.AbstractCssClassUpdate.writeCssClassContent(...)ispublic abstract(aprotectedoverride no longer compiles).
Detect:
grep -rn -e 'extends \(DataManager\|FileSystemCache\|FlexDataManagerFactory\|EncryptedFlexDataManagerFactory\|InitialDataSetupService\|CommandApprovalService\)\b' -e 'getRolesForCommandGroup' -e 'RoleComputation' -e 'extends ElementAccessManager' -e 'writeCssClassContent' --include=*.java .
1.5 Security parents in Java: getSecurityParent() is replaced (#29088) — mandatory if overridden
AbstractBoundWrapper.getSecurityParent() is final now and throws an
UnsupportedOperationException. Either override BoundObject.getSecurityParents() (returning a
collection — the security hierarchy is a DAG now), or — preferred — configure the parents
declaratively (step 2.3).
Detect: grep -rn -e 'getSecurityParent()' --include=*.java .
1.6 Custom TL-Script functions and queries in Java (#29088) — mandatory review
- A
QueryExecutorapplies security by default. Internal queries that must see all objects regardless of the current user have to callQueryExecutor.disableSecurity()explicitly. - Custom TL-Script functions implemented in Java that read or write the model should extend
GenericMethodWithSecurity/SearchExpressionWithSecurityand evaluateusesSecurity()(checking withModelAccessRights.getInstance()), so that they can be switched off together with the surrounding expression. PlainGenericMethodimplementations keep compiling, but they bypass model security. - Programmatic access checks: service
ModelAccessRights(isAllowed,isReadAllowed,isAllowedCreate,getAllowedRoles,getAccessibleTypes); TL-Script functionscanRead,canWrite,canDelete,canCreate,canReadAttribute,canWriteAttribute,canExecute,filterSecurity.
Detect: grep -rn -e 'QueryExecutor' -e 'extends GenericMethod\b' -e 'extends SearchExpression\b' --include=*.java .
1.7 Role and role-rule Java API (#29221) — mandatory if used
RoleRuleis abstract (implementationsDefaultRoleRule,SingletonRule);PathElementis an interface (implementationPathNavigation);RoleRule#matches(...)takes aTLObject.- Roles are global:
BoundedRole.DEFINES_ROLE_ASSOCIATIONis removed, and so is the tabledefinesRole; own*Meta.xmlfiles referencing it must be adapted. BoundedRole.getDefinedRole(TLModule, String),getDefinedRoles(TLModule),getScope(),bind(...),unbind(),getAllGlobalRoles()andgetAllScopedRoles()are removed; look roles up withBoundedRole.getRoleByName(name).
Detect:
grep -rn -e 'RoleRule' -e 'PathElement' -e 'DEFINES_ROLE_ASSOCIATION' -e 'definesRole' --include=*.java --include=*Meta.xml .
grep -rn -e 'getDefinedRole' -e 'getAllGlobalRoles' -e 'getAllScopedRoles' -e 'BoundedRole' --include=*.java .
1.8 Model part descriptions are HtmlResKey (#28694) — mandatory if used (Java)
InternationalizedDescription.getDescription() / setDescription() work with HtmlResKey
instead of ResKey, also the overriding declarations in Internationalized and ScriptParameter.
// Set: wrap the ResKey in an HtmlResKey.
config.setDescription(new DefaultHtmlResKey(descriptionKey));
// Read the underlying ResKey.
HtmlResKey description = config.getDescription();
ResKey descriptionKey = description == null ? null : ((DefaultHtmlResKey) description).content();
// Display as HTML.
HTMLFragment tooltip = description.getHtml();
The content of a description set this way must be valid HTML: escape plain text containing <,
>, & first (TagUtil.encodeXML); nobody else does it for programmatically set values.
Detect: grep -rn -e 'setDescription(' -e 'getDescription()' --include=*.java src
1.9 Moved classes and changed signatures (#29108, #29396) — mandatory if used (Java)
com.top_logic.basic.graph.ExplicitGraphmoved tocom.top_logic.basic.shared.graph.ExplicitGraph(moduletl-basic-shared, a dependency oftl-basic): change the import.TechnicalNamesLabelProvider,DefaultNodePortCoordinateAssigner,DefaultNodeSizer,JSONDefaultLayoutGraphExporter,DiagramTextRenderingConstants,DiagramTextRenderingUtilkeep their packagecom.top_logic.graph.layouter...but moved from moduletl-graph-layoutertotl-graph-diagramjs-server. An application reaching them only through a direct dependency ontl-graph-layoutermust addtl-graph-diagramjs-server.ModeSelector.traceDependencies(...)andConstraintCheck.traceDependencies(...)take anOverlayLookupinstead of aFormContextas last parameter (anAttributeUpdateContaineris anOverlayLookup);ScriptTracer.execute(...)likewise.ModeSelector.getMode(TLObject, TLStructuredTypePart)has an additionalboolean editModeparameter; implementations must accept it. TL-Script functions configured viamode-by-expressionare unaffected (a function declaring only the object parameter ignores the additional argument).
Detect:
grep -rn -e 'basic.graph.ExplicitGraph' -e 'TechnicalNamesLabelProvider' -e 'DefaultNodePortCoordinateAssigner' -e 'DefaultNodeSizer' -e 'JSONDefaultLayoutGraphExporter' -e 'DiagramTextRendering' -e 'traceDependencies' -e 'ScriptTracer' -e 'ModeSelector' --include=*.java .
grep -rn 'tl-graph-layouter' --include=pom.xml .
1.10 Database schema and migration API (#29361) — mandatory if used
- Stricter schema check: a monomorphic reference whose target type is an abstract
MOClass(or anMOAlternative) is rejected when the schema is resolved (DataObjectException"... cannot be an abstract class, since there is no column in which the concrete target type can be stored."), instead of failing only when a value is stored. Own*Meta.xmlwith such a reference must declare it polymorphic or point to a concrete type; otherwise the application does not start. - Migration API:
Util.updateTLReference(...),Util.updateInverseReference(...)andUtil.updateTLStructuredTypePart(...)(com.top_logic.model.migration) have an additional parameterDeletionPolicyafter theHistoryType(nullkeeps the value). Own migration processors calling them must be adapted. - The automatic migrations
Ticket_29361_Made_Tag_taggedObj_polymorphicandTicket_29361_Move_taggedObj_to_Tag_table(moduletl-element) convertTag:Tag#taggedObject. Nothing to do unless the application extends theTagschema itself.
Detect:
grep -rln -e 'MOReference' -e '<reference' --include=*Meta.xml .
grep -rn -e 'updateTLReference' -e 'updateInverseReference' -e 'updateTLStructuredTypePart' --include=*.java .
grep -rn -e '"Tag"' -e 'Tag:Tag' -e 'taggedObj' --include=*.xml --include=*.java src
2. Server configuration (*.config.xml, metaConf.txt, model files)
2.1 Configure the access rights of the application model (#29088) — mandatory
Model-based access rights are active by default: the new SecurityConfigurationService is
started by the framework and all model access through TL-Script (and the Java API on top of it)
is checked against its configuration. The configuration is deny-by-default: a type without a
grant for a command group is not accessible for any role-based user (administrators and code
running in a system context bypass the checks). Without action the application keeps working
for administrators, but regular users no longer see model data in TL-Script based views, and
TL-Script based modifications fail.
Add a service configuration (e.g. an own *.config.xml registered in the application's
metaConf.txt):
<config service-class="com.top_logic.model.security.SecurityConfigurationService">
<instance>
<security-config>
<!-- Baseline for all types of a module. -->
<module name="myapp">
<grant operation="Read" roles="Viewer, Editor, Manager" inherit="true"/>
<grant operation="Write" roles="Editor, Manager" inherit="true"/>
<grant operation="Create" roles="Editor, Manager" inherit="true"/>
<grant operation="Delete" roles="Manager" inherit="true"/>
</module>
<!-- Refinement for a single type, e.g. a custom command group. -->
<class name="myapp:Order">
<grant operation="Approve" roles="Manager, Approver"/>
</class>
<!-- Attribute-level restriction: narrows the type-level grant. -->
<part name="myapp:Customer#salary">
<grant operation="Read" roles="Manager"/>
<grant operation="Write" roles="Manager"/>
</part>
<!-- A grant without roles denies the operation for everybody. -->
<part name="myapp:Contract#secret">
<grant operation="Read"/>
</part>
<!-- Views without a domain type: use a module singleton as security object. -->
<singleton name="myapp:AdminPanel">
<grant operation="Read" roles="Admin"/>
<grant operation="Write" roles="Admin"/>
</singleton>
</security-config>
</instance>
</config>
Rules:
operationis aBoundCommandGroup: the built-in groupsRead,Write,Create,Delete, plus any custom command group of the application.- Type, module and inherited grants are additive (union of the roles). Attribute grants
(
<part>) restrict: the user needs the type-level right and one of the roles of the attribute grant. Singleton grants are standalone. inherit="true"propagates a grant to sub-types (for a module grant: also to sub-types defined in other modules).- The referenced roles must exist in the database (e.g. declared via
InitialRolesManager, see step 2.5); roles are still assigned per instance as before (hasRolerecords, role rules, security parent chain). A role name that cannot be resolved is a configuration error at startup. - Starting point: the existing role profile of the views (
PersBoundComp). The roles configured there for a command group become the roles of the corresponding grant on the displayed type.PersBoundCompitself is unchanged and still governs the classic layout security. - Also cover the types of modules the application uses from the engine (e.g. contacts) if non-admin users work with them in TL-Script based views.
Detect (the step applies to every application with a model of its own; this lists the model modules and whether a configuration exists already):
find . -name '*.model.xml' -path '*/src/main/*' | grep -v target
grep -rln 'SecurityConfigurationService' --include=*.xml --include=metaConf.txt src
2.2 Account and profile defaults of the framework (#29088) — mandatory review
- A new role
PersonalProfileis declared (InitialRolesManager) together with a role rule that grants it to every user on their own account, plus read/write grants fortl.accounts:Personand the matching contact configuration incom.top_logic.contact. Applications that already define a role of that name must rename theirs. - Writing
tl.accounts:Person#adminis denied for everybody (grant without roles): the flag can no longer be set through model access (TL-Script, REST); it is changed through the account administration only. - The
ModelBasedSearchconfiguration propertydisable-optimizationsis removed (the optimizer is always on); delete it from the application'sModelBasedSearchservice configuration, otherwise the configuration fails with an unknown property.
Detect:
grep -rn -e 'PersonalProfile' -e 'Person#admin' -e "'admin'" -e 'disable-optimizations' --include=*.xml --include=*.java --include=*.properties src
2.3 Security parents: declarative configuration, root only as fallback (#29088) — mandatory review
Configure security parents declaratively at the AccessManager (preferred over overriding Java
methods, see step 1.5):
<config service-class="com.top_logic.tool.boundsec.manager.AccessManager">
<instance>
<security-parents>
<rule id="ProjectForMilestone"
inherit="true"
meta-element="myapp:Milestone"
>
<step attribute="myapp:Milestone#project"/>
</rule>
<rule id="SecRootForProject"
inherit="true"
meta-element="myapp:Project"
>
<singleton module="SecurityStructure"/>
</rule>
</security-parents>
</instance>
</config>
Behavior change: the global security root is only a fallback now. As soon as security
parents are configured for a type, the root is no longer added automatically. A type that needs
the root in its parent chain must name it with the <singleton> path element (as above);
otherwise roles granted on the security root are no longer inherited to those objects.
Detect: grep -rn -e 'security-parents' -e 'getSecurityParent' --include=*.xml --include=*.java src
2.4 Role rules: new syntax and mandatory ids (#29221, #29088) — mandatory if role rules exist
Run the combined migration once in the application project (it removes securityDomain from
layout files and adds an id to role rules that have none; layouts stored in the database are
updated automatically on startup):
mvn exec:java@migrate-ticket29221
Then convert the remaining old syntax by hand:
baseattribute of a role rule:
becomes<inheritance-rule base="structureRoot@MyModule" ... /><inheritance-rule ...> <script-step expr="`MyModule#ROOT`"/> </inheritance-rule>- Steps name the attribute qualified, without
meta-element:
becomes<step attribute="myAttr" meta-element="MyModule:MyClass" ... /><step attribute="MyModule:MyClass#myAttr" ... /> - Role rules and security parent rules require an
id; rules added after running the migration need an id of their own. - The base roles
navigationandselectionexist in the framework (InitialRolesManager) and can replace application-defined roles of the same meaning (formerly duplicated per security structure). The engine rolemandatorStructure.navigationis removed (step 3.3).
Detect:
grep -rn -e 'base="' -e 'meta-element=' -e '<step ' -e '<rule' -e 'inheritance-rule' --include=*.config.xml --include=*.xml src/main/webapp/WEB-INF/conf
grep -rn 'securityDomain' --include=*.xml src/main/webapp/WEB-INF/layouts
2.5 Roles are defined centrally, not per module (#29221) — mandatory if roles are declared
Remove the <roles> declaration from model files and from the ModelService module settings
and declare the roles at the InitialRolesManager. Keep the role name as it is (including a
module prefix such as myModule.role1), otherwise the existing roles in the database are not
recognized. New roles need no module prefix.
Before (myModule.model.xml):
<module name="myModule">
<annotations>
<roles> <!-- remove -->
<role name="myModule.role1"/>
</roles>
</annotations>
</module>
Before (application configuration):
<config service-class="com.top_logic.util.model.ModelService">
<instance><settings>
<module name="myModule">
<roles> <!-- remove -->
<role name="myModule.role1"/>
</roles>
</module>
</settings></instance>
</config>
After:
<config service-class="com.top_logic.base.services.InitialRolesManager">
<instance>
<roles>
<role name="myModule.role1"/>
</roles>
</instance>
</config>
Detect: grep -rn -e '<roles>' -e '<role ' --include=*.model.xml --include=*.config.xml src
2.6 Role assignments of singletons to groups become role rules (#29221) — mandatory if used
Remove <role-assignments> (with content) from the singleton configuration of the
ModelService:
<config service-class="com.top_logic.util.model.ModelService">
<instance><settings>
<module name="MyModule">
<singletons>
<singleton type="Root">
<role-assignments>
<role-assignment role="MyModule.role" group="MyGroup"/>
...
and add a role rule instead:
<singleton-rule
target="MyModule#ROOT"
role="MyModule.role"
>
<group-with-name name="MyGroup"/>
</singleton-rule>
Detect: grep -rn -e 'role-assignments' -e 'role-assignment ' --include=*.xml src
2.7 Orientation values are lower case (#29108) — mandatory if used
OrientationAware.Orientation is ExternallyNamed: configuration properties of that type are
written and read as horizontal / vertical; XML using HORIZONTAL / VERTICAL no longer parses.
Detect: grep -rn -e '"HORIZONTAL"' -e '"VERTICAL"' --include=*.xml src
2.8 OpenAPI server: non-2xx responses roll back the transaction (#29392) — mandatory review
If an OpenAPI server operation returns a response with a status outside 2xx (e.g.
response(400, ...)), the transaction of the operation is now rolled back. Operations that
deliberately store changes along with an error response (e.g. error log objects) must perform
these changes in a transaction of their own or return a 2xx status.
Detect: grep -rln -e 'OpenApiServer' -e 'response(' --include=*.xml .
3. Security / access checks
3.1 Where the new model checks apply (#29088) — mandatory review
- Reading an attribute in TL-Script (
$obj.get(...)) returns the empty value when the user must not read the attribute on that object. - Modifying (
set,add,remove), creating (new) and deleting (delete) fail with aTopLogicExceptionwhen the right is missing. - TL-Script based model builders filter their result by read access:
ListModelByExpression,ModelProviderByExpression,TreeModelByExpression,SelectionUpdaterByExpression,TableContentProvider,ForeignObjectsTemplateProviderand the script console. copy()and the BPE process instantiation check the CREATE right.- Not checked: computed (derived) attributes (evaluated with definer's rights), constraints, internal framework scripts, code in a system context, administrators.
all()andkbQuery()deliberately return unfiltered results; the caller filters (in TL-Script withfilterSecurity(), in Java withSearchExpression.filterSecurity(...)).- A script executed without a logged-in user has no rights at all. Background jobs (tasks, batch
processing) must run in a system context (
ThreadContext.inSystemContext(...)) or use a query executor with disabled security (QueryExecutor.disableSecurity(), step 1.6).
Action: check views that list objects with all(...) / kbQuery(...) (add filterSecurity()
where users must only see accessible objects) and background tasks that run TL-Script.
Detect:
grep -rn -e 'all(' -e 'kbQuery(' --include=*.xml src/main/webapp/WEB-INF
grep -rn -e 'extends .*Task\b' -e 'TaskImpl' -e 'Scheduler' --include=*.java src
3.2 Layout security after the removal of security structures (#29221) — mandatory review
- Security domains are gone (step 2.4 removes
securityDomainfrom layout files). - Where the security object provider
modelis used, narrow it to the possible types so that the role profile offers only relevant roles:securityObject="model"→securityObject="model(myModule:type1,myModule:type2)". - The default for showing a button bar (e.g. in dialogs) changed — check dialogs.
- Whether a layout is treated as security master (e.g. a dialog with exactly one layout) changed — check, and better mark the component explicitly as security master.
- Role profiles must be updated: grant the rights again through the role profile administration
(edit
WEB-INF/conf/security.xmlonly if the application already ships one; never create one).
Detect:
grep -rn -e 'securityObject="model"' -e 'securityObject=' -e 'buttonbar' -e 'securityMaster' -e 'security-master' --include=*.xml src/main/webapp/WEB-INF/layouts
find . -name security.xml -path '*/WEB-INF/conf/*' | grep -v target
3.3 Legacy security views, providers and scoped roles removed (#29221) — mandatory if referenced
- The legacy views of the rights administration are removed:
com.top_logic.element/admin/security/indexLegacy.layout.xml,profilesLegacy/*,groupRoles/adminGroupRolesView.layout.xml,groupRoles/editGroupRightsMulti.xml,roleAssignment/adminPersonsRolesView.layout.xml,roleAssignment/editPersonRights.xmlandsecurityStructure.xml; likewise the componentsEditRolesProfileComponent,ExportingEditRolesProfileComponent,StructureSelectorComponent,GlobalEditRoleComponent,ScopedEditRoleComponent,EditPersonOrGroupRolesMultiComponentand the security object providersslave,rootForCreateandsecurityStrRoot(FlexibleSecurityObjectProvider). Remove or replace references to them in the application's layouts and configuration. - The role
mandatorStructure.navigationis removed: switch role profiles and role rules that use it to the rolenavigation.
Detect:
grep -rn -e 'Legacy.layout' -e 'profilesLegacy' -e 'adminGroupRolesView' -e 'adminPersonsRolesView' -e 'securityStructure.xml' -e 'EditRolesProfileComponent' -e 'StructureSelectorComponent' -e 'EditRoleComponent' -e 'securityObject="slave"' -e 'rootForCreate' -e 'securityStrRoot' -e 'mandatorStructure.navigation' --include=*.xml .
5. Classic UI, TL-Script and data
5.1 Dangling references in multi-valued references fail now (#28816) — mandatory where data is affected
Resolving a multi-valued reference attribute now throws a KnowledgeBaseRuntimeException
(InvalidLinkException, "Dangling references to no longer existing objects") for every reference
to an object that no longer exists. Before, such entries were skipped silently as long as another
referenced object existed. Data in which objects were deleted without cleaning up incoming
references (e.g. by an earlier migration) must be cleaned up before the update; otherwise reading
the attribute fails at runtime. Own migrations that delete objects must remove the references to
these objects, too.
Detect (own migrations deleting objects):
grep -rln -e 'delete' -e 'DELETE' src/main/webapp/WEB-INF/kbase/migration 2>/dev/null
plus: after startup, read the log for Dangling references to no longer existing objects.
5.2 dateFormat() uses the user's time zone by default (#29306) — review
The default time zone of TL-Script dateFormat() changed from the JVM default to the current
user's time zone (ThreadContext.getTimeZone()). Scripts that format instants without an
explicit timeZone argument now render them in the user's time zone. Scripts that need a
specific time zone pass it explicitly (a zone id, "system", "user", or a calendar's
timeZone()).
Detect: grep -rn 'dateFormat(' --include=*.xml --include=*.script --include=*.java src
5.3 Existing model descriptions with special characters (#28694) — optional data fix
Old descriptions are not converted automatically: a description stored as plain text containing
<, > or & stays invalid HTML and its tooltip stays broken until it is edited again. Open
such descriptions once in the model editor and save them; the editor converts them. Manual
escaping (the former workaround) stays valid but is no longer needed.
Detect: grep -rn -E '<description>[^<]*[&<>]' --include=*.model.xml src
5.4 Scripted tests filling the description field (#28694) — mandatory if used
Scripted tests that fill or check the description field of a model part now address the
structured HTML editor instead of a plain text field (see the engine's adapted
TestAttributeI18N and TestResourceAttribute).
Detect: grep -rln -i 'description' --include=*.script.xml src/test
5.5 React flow diagrams: text size (#29420) — review
- A
Textin a React flow diagram without an own font size now follows the render context instead of the former fixed 14 pixels. Set the size on the text where a fixed size is wanted. - The parameter
textSizeoftoSvgnow takes effect in the React branch; exports that set it to a non-default value change their size.
Detect: grep -rn -e 'toSvg' -e 'fontSize' -e 'flowChart' -e 'text(' --include=*.xml --include=*.java src | grep -i -e flow -e svg -e text
6. Stylesheets
6.1 Font Awesome stylesheet path (#29108) — mandatory if referenced
The stylesheet moved from /style/fontawesome/css/all.css (all.min.css) to
/style/fontawesome.css (fontawesome.min.css); the core theme lists the new path. Application
themes that do not extend core and list the sheet themselves, and JSPs linking the old path,
must be updated. Icon class names are unchanged.
Detect: grep -rn -e 'fontawesome/css' -e 'all.min.css' -e 'all.css' --include=*.xml --include=*.jsp --include=*.css --include=*.html src
6.2 Default font rules for exported SVG diagrams (#29420) — optional
An exported SVG carries the font at the root element instead of an embedded CSS rule.
Application stylesheets no longer need text:not([font-family]) / text:not([font-size])
default rules; existing ones can be removed.
Detect: grep -rn -e 'text:not(\[font-family\])' -e 'text:not(\[font-size\])' --include=*.css src
7. Further notes (no action required)
- #28694 No data migration: the configuration binding of
HtmlResKey(DefaultHtmlResKey.ValueBinding) uses the same storage format asResKey; stored descriptions (also those ofScriptParameter) load unchanged. - #29384 Sequence names are unified to
<base><context>_SequenceId(shared bySequenceDefaultProvider,SequenceIdGenerator/NumberHandlerDefaultProviderand thegenerateSequenceId/resetSequenceTL-Script functions). The automatic data migrationTicket_29384_unify_sequence_names(moduletl-element) rewrites existing rows on first startup; on a name collision the higher counter is kept. No manual steps. - #29361 The
Tagreference is converted automatically (see step 1.10); per a Trac comment the migration moves the values that "historic-storage" kept in the flex data into theTagtable. - #29221 Layouts stored in the database (in-app layouts) are updated automatically on startup (security domain removed).
- #29108
ExternalAuthenticationServletno longer reuses an existing anonymous session, only an authenticated one. The new TL Views layer (React UI) itself is additive. - #29195 HTML attributes in TL-Script: an empty
StructuredTextvalue now counts as empty (isEmpty(), equal tonulland""), and a plain string assigned to an HTML attribute is accepted and interpreted as CommonMark. - #29383 Without
-Dtl_logReceiver=truethe socket appender is no longer part of the logging configuration at all; a dead receiver can no longer stall logging.
8. Verification checklist
mvn clean installof the application, with tests if possible (compile errors point to sections 1.3–1.10).- Start the application with
tl_operation_mode=development(or via theBootstrapstart launch); read the startup log for configuration errors (unknown properties, unresolvable role names in the security configuration, schema errors) and for migration errors. - Log in as administrator and open every view.
- Log in as a regular user of each role and open every view: lists, trees and forms must
show the expected objects and attributes, and create/edit/delete must work as before
(sections 2.1, 2.3, 3.1). Empty views or
TopLogicExceptionon save mean missing grants. - Check the role profile administration: roles and rights per view are as intended (sections 3.2, 3.3). Call OpenAPI operations that return error responses and check what is persisted (section 2.8).
- Run background tasks once and check that they still see and change data (section 3.1).
- Report every step that was skipped, every grant that was added, every role that was renamed or moved, and every data cleanup (sections 2.1, 2.5, 3.3, 5.1, 5.3).