TopLogic - the automated application engine
  • Releases
  • Dokumentation
  • Github
  • Discord
  1. Home
  2. Releases
  3. TL_8.0.0-alpha7
  4. Migration guide

8.0.0-alpha7
TopLogic Release

2026-07-30

Markdown version, e.g. for an LLM updating an application.

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

  1. 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.
  2. 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.
  3. 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.
  4. 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 tag TL_8.0.0-alpha7). The developer articles on access rights are only shipped with later releases.
  5. 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=true by -Dtl_operation_mode=development in every Eclipse .launch, .mvn/jvm.config, start script and CI job that runs the application from the workspace. Values: development, test, production (default; test is derived under the test container).
  • Optional: set tl_operation_mode=production explicitly in deployment descriptors (the archetype's Dockerfile_template does).
  • Application code that decides on Environment.isDeployed() should ask com.top_logic.base.operation.OperationModeService.getInstance().getMode() (OperationMode.DEVELOPMENT, TEST, PRODUCTION), as the executability rule IDEOnly does. Note from a Trac comment on #29400: in automated tests (scripted tests, unit tests), isDeployed() is now true (mode TEST), so development-only functions gated by isDeployed() are not available in tests any more; gate them by getMode() != 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=true to the VM arguments. Developers without a log receiver need to change nothing. The appender runs with ignoreExceptions="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.xml or debug.xml (changed in com.top_logic and com.top_logic.kafka) must transfer the change to their copy by hand (gate the SOCKET_APPENDER on the system property tl_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 / Properties constructors of DataManager, FileSystemCache, FlexDataManagerFactory, EncryptedFlexDataManagerFactory, InitialDataSetupService and CommandApprovalService are replaced by (InstantiationContext, Config) constructors; subclasses must offer them.
  • BoundChecker#getRolesForCommandGroup(...) must return a non-null collection (Collections.emptySet() instead of null); the default allow(...) no longer tolerates null.
  • RoleComputation(StorageAccessManager) became RoleComputation(Person, StorageAccessManager); ElementAccessManager gained the hooks getSecurityParents(BoundObject) and canHaveRole(TLClass, BoundedRole) for application access managers.
  • AbstractCssClassUpdate.writeCssClassContent(...) is public abstract (a protected override 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 QueryExecutor applies security by default. Internal queries that must see all objects regardless of the current user have to call QueryExecutor.disableSecurity() explicitly.
  • Custom TL-Script functions implemented in Java that read or write the model should extend GenericMethodWithSecurity / SearchExpressionWithSecurity and evaluate usesSecurity() (checking with ModelAccessRights.getInstance()), so that they can be switched off together with the surrounding expression. Plain GenericMethod implementations keep compiling, but they bypass model security.
  • Programmatic access checks: service ModelAccessRights (isAllowed, isReadAllowed, isAllowedCreate, getAllowedRoles, getAccessibleTypes); TL-Script functions canRead, 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

  • RoleRule is abstract (implementations DefaultRoleRule, SingletonRule); PathElement is an interface (implementation PathNavigation); RoleRule#matches(...) takes a TLObject.
  • Roles are global: BoundedRole.DEFINES_ROLE_ASSOCIATION is removed, and so is the table definesRole; own *Meta.xml files referencing it must be adapted.
  • BoundedRole.getDefinedRole(TLModule, String), getDefinedRoles(TLModule), getScope(), bind(...), unbind(), getAllGlobalRoles() and getAllScopedRoles() are removed; look roles up with BoundedRole.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.ExplicitGraph moved to com.top_logic.basic.shared.graph.ExplicitGraph (module tl-basic-shared, a dependency of tl-basic): change the import.
  • TechnicalNamesLabelProvider, DefaultNodePortCoordinateAssigner, DefaultNodeSizer, JSONDefaultLayoutGraphExporter, DiagramTextRenderingConstants, DiagramTextRenderingUtil keep their package com.top_logic.graph.layouter... but moved from module tl-graph-layouter to tl-graph-diagramjs-server. An application reaching them only through a direct dependency on tl-graph-layouter must add tl-graph-diagramjs-server.
  • ModeSelector.traceDependencies(...) and ConstraintCheck.traceDependencies(...) take an OverlayLookup instead of a FormContext as last parameter (an AttributeUpdateContainer is an OverlayLookup); ScriptTracer.execute(...) likewise.
  • ModeSelector.getMode(TLObject, TLStructuredTypePart) has an additional boolean editMode parameter; implementations must accept it. TL-Script functions configured via mode-by-expression are 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 an MOAlternative) 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.xml with 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(...) and Util.updateTLStructuredTypePart(...) (com.top_logic.model.migration) have an additional parameter DeletionPolicy after the HistoryType (null keeps the value). Own migration processors calling them must be adapted.
  • The automatic migrations Ticket_29361_Made_Tag_taggedObj_polymorphic and Ticket_29361_Move_taggedObj_to_Tag_table (module tl-element) convert Tag:Tag#taggedObject. Nothing to do unless the application extends the Tag schema 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:

  • operation is a BoundCommandGroup: the built-in groups Read, 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 (hasRole records, 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. PersBoundComp itself 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 PersonalProfile is declared (InitialRolesManager) together with a role rule that grants it to every user on their own account, plus read/write grants for tl.accounts:Person and the matching contact configuration in com.top_logic.contact. Applications that already define a role of that name must rename theirs.
  • Writing tl.accounts:Person#admin is 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 ModelBasedSearch configuration property disable-optimizations is removed (the optimizer is always on); delete it from the application's ModelBasedSearch service 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:

  • base attribute of a role rule:
    <inheritance-rule base="structureRoot@MyModule" ... />
    
    becomes
    <inheritance-rule ...>
      <script-step expr="`MyModule#ROOT`"/>
    </inheritance-rule>
    
  • Steps name the attribute qualified, without meta-element:
    <step attribute="myAttr" meta-element="MyModule:MyClass" ... />
    
    becomes
    <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 navigation and selection exist in the framework (InitialRolesManager) and can replace application-defined roles of the same meaning (formerly duplicated per security structure). The engine role mandatorStructure.navigation is 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 a TopLogicException when the right is missing.
  • TL-Script based model builders filter their result by read access: ListModelByExpression, ModelProviderByExpression, TreeModelByExpression, SelectionUpdaterByExpression, TableContentProvider, ForeignObjectsTemplateProvider and 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() and kbQuery() deliberately return unfiltered results; the caller filters (in TL-Script with filterSecurity(), in Java with SearchExpression.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 securityDomain from layout files).
  • Where the security object provider model is 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.xml only 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.xml and securityStructure.xml; likewise the components EditRolesProfileComponent, ExportingEditRolesProfileComponent, StructureSelectorComponent, GlobalEditRoleComponent, ScopedEditRoleComponent, EditPersonOrGroupRolesMultiComponent and the security object providers slave, rootForCreate and securityStrRoot (FlexibleSecurityObjectProvider). Remove or replace references to them in the application's layouts and configuration.
  • The role mandatorStructure.navigation is removed: switch role profiles and role rules that use it to the role navigation.

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 Text in 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 textSize of toSvg now 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 as ResKey; stored descriptions (also those of ScriptParameter) load unchanged.
  • #29384 Sequence names are unified to <base><context>_SequenceId (shared by SequenceDefaultProvider, SequenceIdGenerator/NumberHandlerDefaultProvider and the generateSequenceId/resetSequence TL-Script functions). The automatic data migration Ticket_29384_unify_sequence_names (module tl-element) rewrites existing rows on first startup; on a name collision the higher counter is kept. No manual steps.
  • #29361 The Tag reference 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 the Tag table.
  • #29221 Layouts stored in the database (in-app layouts) are updated automatically on startup (security domain removed).
  • #29108 ExternalAuthenticationServlet no 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 StructuredText value now counts as empty (isEmpty(), equal to null and ""), and a plain string assigned to an HTML attribute is accepted and interpreted as CommonMark.
  • #29383 Without -Dtl_logReceiver=true the socket appender is no longer part of the logging configuration at all; a dead receiver can no longer stall logging.

8. Verification checklist

  1. mvn clean install of the application, with tests if possible (compile errors point to sections 1.3–1.10).
  2. Start the application with tl_operation_mode=development (or via the Bootstrap start launch); read the startup log for configuration errors (unknown properties, unresolvable role names in the security configuration, schema errors) and for migration errors.
  3. Log in as administrator and open every view.
  4. 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 TopLogicException on save mean missing grants.
  5. 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).
  6. Run background tasks once and check that they still see and change data (section 3.1).
  7. 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).
  • Get Started
  • Github
  • Discord
  • Das Unternehmen hinter TopLogic
  • Softwareentwicklung heute
  • Kontakt

© Copyright – Business Operation Systems GmbH

  • top-logic.com
  • Nutzungsbedingungen
  • Impressum
  • Rechtlicher Hinweis
  • Datenschutz
  • EN
  • Login