# 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:

```java
@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`.

```java
// 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`):

```xml
<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):

```xml
<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:
  ```xml
  <inheritance-rule base="structureRoot@MyModule" ... />
  ```
  becomes
  ```xml
  <inheritance-rule ...>
    <script-step expr="`MyModule#ROOT`"/>
  </inheritance-rule>
  ```
- Steps name the attribute qualified, without `meta-element`:
  ```xml
  <step attribute="myAttr" meta-element="MyModule:MyClass" ... />
  ```
  becomes
  ```xml
  <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`):
```xml
<module name="myModule">
  <annotations>
   <roles>                           <!-- remove -->
    <role name="myModule.role1"/>
   </roles>
  </annotations>
</module>
```
Before (application configuration):
```xml
<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:
```xml
<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`:
```xml
<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:
```xml
<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).
