Migrating a TopLogic application from 8.0.0-alpha5 to 8.0.0-alpha6
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-alpha6/ and the
TopLogic Trac tickets of milestone TL_8.0.0-alpha6 (ticket numbers are given as #NNNNN; the
per-ticket page is https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha6/NNNNN/).
8.0.0-alpha6 is a stabilization release. Besides the version bump it has two migration topics, both relevant only where the application uses the affected feature:
- access rights in the model-based search and the flex reporting details dialog (#28685, section 3.1),
- the default scope of undo/redo buttons (#29322, section 5.1).
Section 7 lists behavior changes and fixes for information only.
How to use this document
- Do the version bump (section 1.1). 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.
- Neither change shows up as a compile or configuration error. They show up only at runtime: as disabled or missing commands for non-root users (section 3.1) and as undo/redo buttons that no longer find changes of other users or older changes (section 5.1).
- Section 7 lists behavior changes and fixes for information only; they need no change in the application.
- For background on an engine feature, read the developer articles shipped with the engine
(tl-mcp
list_docs/read_doc). - Finish with the verification checklist (section 8).
- Ticket descriptions on Trac are partly German; this document translates the relevant content.
Search commands below assume the project root as working directory and GNU grep.
1. Build and platform
1.1 Version bump — mandatory
Set the TopLogic version to 8.0.0-alpha6 (parent tl-parent-app / tl-parent-core version, or
the tl.version property).
Detect:
grep -rn --include=pom.xml -e '8.0.0-alpha5' .
3. Security / access checks
3.1 Model-based search: saving needs ownerWrite, details dialog needs Read (#28685) — mandatory where applicable
-
Saving a model-based search. The save command
saveModelSearchis no longer a system command. It now belongs to the command groupownerWrite. Before, every user could change any stored search, including searches other users had published.A non-root user can now save a search only if two things hold:
- their role has the command group
ownerWriteon the search view (andpublishto publish a search); - a role rule gives the owner of the stored search this role.
The rights are checked on the stored search object, not on the security root.
- their role has the command group
-
Flex reporting details dialog. The details dialog
displaySearchResultDetailsnow belongs to the command groupRead(was a system command). The details link in a chart appears only if the user has this right.
What to do:
- Grant
ownerWriteandpublishto the owner role on the search views the application uses:com.top_logic.model.search/search/modelSearch.layout.xml#modelSearchcom.top_logic.element/search/searchInput.layout.xml#searchInput- the application's own views that embed them
- Make sure a role rule assigns this role to the owner of a stored search.
- Check that the roles that should open the flex reporting details dialog have
Readon it. - Grant the rights in the role profile administration of the running application. Use
WEB-INF/conf/security.xmlinstead only if the application already ships one. Never create a newsecurity.xml.
Example from the TopLogic demo (security.xml, profile of the owner role):
<profile name="SecurityStructure.OwnerRole">
<view name="com.top_logic.model.search/search/modelSearch.layout.xml#modelSearch">
<commandGroup name="ownerWrite"/>
<commandGroup name="publish"/>
</view>
<view name="com.top_logic.element/search/searchInput.layout.xml#searchInput">
<commandGroup name="ownerWrite"/>
<commandGroup name="publish"/>
</view>
</profile>
Rights configured in-app (role profiles stored in the database) are not found by the search. Ask the user whether the model-based search or flex reporting is used by non-root users.
Detect:
grep -rn -e 'modelSearch.layout.xml' -e 'searchInput.layout.xml' -e 'displaySearchResultDetails' --include=*.xml .
5. Classic UI
5.1 Undo/redo buttons consider only the current user's changes of the last 7 days (#29322) — mandatory where applicable
The undo and redo buttons now share the change log options of the change overview table. Affected classes:
com.top_logic.element.changelog.UndoCommandHandlercom.top_logic.element.changelog.RedoCommandHandler
The defaults restrict them: all-users="false" and max-time="7d". So by default a button only
undoes or redoes changes of the logged-in user made within the last 7 days. Before, it considered
changes of all users without a time limit. The other shared options are
include-technical-changes and excluded-modules.
Where a button should keep the previous behavior, set all-users="true" and max-time="0"
(0 = unlimited). Buttons configured in-app have the same options in the layout editor. Adjust them
the same way, and ask the user whether such buttons exist.
Before:
<button id="undo"
class="com.top_logic.element.changelog.UndoCommandHandler"
group="Write"
/>
After (previous behavior):
<button id="undo"
all-users="true"
max-time="0"
class="com.top_logic.element.changelog.UndoCommandHandler"
group="Write"
/>
Detect:
grep -rn -e 'changelog.UndoCommandHandler' -e 'changelog.RedoCommandHandler' --include=*.xml .
7. Further notes (no action required)
7.1 Fixed: optimized queries with transient objects (#29340)
The known issue of 8.0.0-alpha5 is fixed: a TL-Script expression that the engine turns into a
database query (e.g. all(...).filter(...) with a parameter) no longer fails when a transient
object is passed as a parameter. The engine now passes a synthetic ID for the transient object to
the database. No workaround is needed; if the application added one for alpha5, it can be removed.
7.2 Trees reveal a new selection (#29009, #29330)
- Trees and tree tables now have the option
revealSelection(defaulttrue), separate from "expand on selection": a node that becomes selected (e.g. from another component or after creating an object) is made visible by expanding its ancestors, even if "expand on selection" is switched off. SetrevealSelection="false"only if this is unwanted (e.g. for bulk selection). - There is a new in-app UI action "Show object in component" that expands a tree up to an object and scrolls it into view.
TreeComponentandTreeTableComponentkeep the expansion state of their nodes when the component is invalidated for the same model (as the grid already did).
7.3 Flow chart keeps its zoom level (#29331, #29372)
A flow chart (tl-graphic-blocks-server/flowChart.template.xml) that is redrawn for the same
model (a model change, not a model switch) keeps the current zoom level instead of falling back to
the initial zoom. The compact tree layout no longer produces overlaps in combination with the
zig-zag display, and the start column of sub-grids is honored.
7.4 Buttons react to programmatic clicks (#29373)
Buttons react to programmatically triggered DOM clicks (e.g. Playwright locator.click()), the
wait pane no longer swallows a click in progress, and anchor-based buttons carry the ARIA role
button and can be activated with the space key.
7.5 Commands on dialogs can be granted (#29223)
Commands configured directly on a dialog (not on a child component of the dialog) now appear in the role profile view and can be granted to roles; before, only root users could execute them.
7.6 Fixed migration tools (#29338, #29339)
CreateTLSingletonProcessor(<create-singleton>in a data migration) no longer adds the singleton annotation to the module a second time. Before, the migration suggested for a new singleton (<add-annotations>+<create-singleton>) left a model that failed at startup withMultiple entries with key: <singleton name>.- The layout transformation of #28305 (
UpgradeDownloadNames.xslt, export download names) now converts adynamic-download-nameelement todownloadNameProvider(was wronglydownloadName) and also handlesexportNameKey/downloadNameKeygiven as elements.
7.7 New options
- External REST APIs (#29334): in the service editor (TL-Script functions for external APIs) the response handling can take "status code of the response" as an additional argument.
- Generated JSON schema of layout templates (#29325): a non-nullable item property whose default
is incomplete (e.g.
titleofcom.top_logic/dialog.template.xml) is now marked as required and no longer offersnull.
7.8 Bug fixes
- TL-Script (#29367): an HTML literal as the first expression in a block (e.g.
{ $x.set(..., {{{{$description}}}}) }) no longer causes a syntax error. - Macro attributes (#29371): the values of macro attributes (computed HTML with model access) are displayed again.
- Kafka (#29269): a message with value
nullno longer causes aNullPointerExceptionthat blocked further consumption of the topic. - Help editor (#29272): importing a help page from a previously exported ZIP works again.
- Script recorder (#29379): after moving the selected action by drag and drop, its details remain editable.
8. Verification checklist
mvn clean installof the application (with tests if possible).- Start the application and read the startup log for configuration and migration errors.
- Log in and open every view of the application.
- Log in as a non-root user. Where the application uses the model-based search, check that the user can save and publish their own searches but not change searches of others (section 3.1).
- Where the application has undo/redo buttons, check that they find the intended changes (section 5.1).
- Report to the user every step that was skipped or needed a decision. Also report every right granted for section 3.1 and every undo/redo button changed for section 5.1.