# 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

1. 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.
2. 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).
3. Section 7 lists behavior changes and fixes for information only; they need no change in the
   application.
4. For background on an engine feature, read the developer articles shipped with the engine
   (tl-mcp `list_docs` / `read_doc`).
5. Finish with the verification checklist (section 8).
6. 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 `saveModelSearch` is no longer a system
  command. It now belongs to the command group `ownerWrite`. 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 `ownerWrite` on the search view (and `publish` to 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.
- **Flex reporting details dialog.** The details dialog `displaySearchResultDetails` now belongs to
  the command group `Read` (was a system command). The details link in a chart appears only if the
  user has this right.

What to do:
1. Grant `ownerWrite` and `publish` to the owner role on the search views the application uses:
   - `com.top_logic.model.search/search/modelSearch.layout.xml#modelSearch`
   - `com.top_logic.element/search/searchInput.layout.xml#searchInput`
   - the application's own views that embed them
2. Make sure a role rule assigns this role to the owner of a stored search.
3. Check that the roles that should open the flex reporting details dialog have `Read` on it.
4. Grant the rights in the role profile administration of the running application. Use
   `WEB-INF/conf/security.xml` instead **only if the application already ships one**. Never create
   a new `security.xml`.

Example from the TopLogic demo (`security.xml`, profile of the owner role):
```xml
<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.UndoCommandHandler`
- `com.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:
```xml
<button id="undo"
	class="com.top_logic.element.changelog.UndoCommandHandler"
	group="Write"
/>
```
After (previous behavior):
```xml
<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` (default `true`), 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. Set `revealSelection="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.
- `TreeComponent` and `TreeTableComponent` keep 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 with
  `Multiple entries with key: <singleton name>`.
- The layout transformation of #28305 (`UpgradeDownloadNames.xslt`, export download names) now
  converts a `dynamic-download-name` element to `downloadNameProvider` (was wrongly
  `downloadName`) and also handles `exportNameKey` / `downloadNameKey` given 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. `title` of `com.top_logic/dialog.template.xml`) is now marked as required
  and no longer offers `null`.

### 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 `null` no longer causes a `NullPointerException` that
  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

1. `mvn clean install` of the application (with tests if possible).
2. Start the application and read the startup log for configuration and migration errors.
3. Log in and open every view of the application.
4. 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).
5. Where the application has undo/redo buttons, check that they find the intended changes
   (section 5.1).
6. 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.
