# Migrating a TopLogic application from 8.0.0-alpha2 to 8.0.0-alpha3

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-alpha3/ and the
TopLogic Trac tickets of milestone `TL_8.0.0-alpha3` (ticket numbers are given as `#NNNNN`; the
per-ticket page is `https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha3/NNNNN/`).

8.0.0-alpha3 is a small release. Besides the version bump it has one migration step: the changed
content type of OpenAPI server responses (#29234, section 2.1), relevant only for applications that
provide OpenAPI server endpoints.

Ticket #29092 (multi-factor authentication) is also flagged `RequiresMigration`, but it shipped its
incompatible changes with 8.0.0-alpha1; its migration steps are part of the guide
`migration-7.10.0-to-8.0.0-alpha1.md`
(https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha1/migration-7.10.0-to-8.0.0-alpha1.md)
and were already done by an application running on 8.0.0-alpha2. The follow-up changes of #29092 in
alpha3 need no action (see section 3).

## How to use this document

1. Work through the sections in 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.
2. Section 3 lists behavior changes for information only; they need no change in the application.
3. Finish with the verification checklist (section 4).
4. 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-alpha3` (parent `tl-parent-app` / `tl-parent-core` version, or
the `tl.version` property).

Detect:
```
grep -rn --include=pom.xml -e '8.0.0-alpha2' .
```

---

## 2. Server configuration

### 2.1 OpenAPI server: content type of endpoint responses (#29234) — mandatory where applicable
The response handling of OpenAPI server endpoints (`ServiceMethodByExpression`) has changed. Before,
**every** endpoint result was serialized as JSON (`application/json`). Now the content type is
determined by the result type:

| Result type | Before | After |
|---|---|---|
| `Map`, `Collection` | `application/json` | `application/json` (unchanged) |
| `BinaryData`, `byte[]`, `InputStream` | `application/json` (broken) | binary stream with the correct content type |
| `String`, other primitives | `application/json` (quoted JSON string) | `text/plain` (raw string, no JSON quoting) |

Affected:
- endpoints whose TL-Script expression returns a string (or another non-map, non-collection,
  non-binary value) **and** whose clients parse the response as JSON;
- endpoints using `response(statusCode, content)` without the `contentType` argument: its former
  default `application/json` is gone, the content type is now derived from `content` as in the
  table above.

Endpoints returning a `Map` or `Collection` are not affected.

For each affected endpoint choose one option (ask the user if the clients are not part of the
application):
1. **Keep the old behavior on the server:** return the result via `response()` with an explicit
   JSON content type:
   ```
   response(200, $result, "application/json")
   ```
   For `response(statusCode, content)` calls, add `"application/json"` as third argument.
2. **Return structured data** instead of a string, e.g. a sorted list instead of a concatenated
   string — replace
   ```
   .sort()
   .reduce("", subresult -> element -> $subresult == "" ? $element : ($subresult + ", " + $element))
   ```
   by
   ```
   .sort()
   ```
   The list is serialized as a JSON array (`["A1", "A3"]`); adapt the clients (and test assertions)
   accordingly.
3. **Change the client to text:** in a TopLogic OpenAPI client configuration (service editor
   "TL-Script-Funktionen für externe APIs" → "Funktionsdefinitionen" → *method* →
   "Antwort-Bearbeitung" → "Format"), switch the format from **JSON** to **Text**; the client then
   receives the raw string without JSON parsing.

New, no action needed: an endpoint can now deliver files — a `BinaryData`, `byte[]` or
`InputStream` result is streamed with the content type of the data (else
`application/octet-stream`).

Detect:
```
grep -rln -e 'OpenApiServer' -e 'response(' --include=*.xml .
```

---

## 3. Further notes (no action required)

### 3.1 Stricter `TLObject#tUpdate` / `tAdd` / `tRemove` (#29240)
Setting, adding or removing a value via a `TLStructuredTypePart` now uses that attribute itself
instead of looking up an attribute of the same name in the object's type. Writing an attribute that
does not belong to the object's type but merely shares a name with one of its attributes (e.g.
setting `Medicine#code` on a `Door`) is no longer possible. Application code that relied on that
by-name lookup fails at runtime. Note: 8.0.0-alpha4 loosens
the check again for an overriding attribute of a subclass (Trac comment of 2026-04-30 on #29240).

### 3.2 Self-service invitation configuration (#29092)
The configuration of `com.top_logic.security.selfservice.invitation.InvitationModule` (optional
module `tl-security-selfservice`) moved from the module's `WEB-INF/autoconf` folder to its regular
configuration file `WEB-INF/conf/tl-security-selfservice.conf.config.xml`. An application can now
override single properties of this service in its own configuration instead of copying the whole
configuration (Trac comment of 2026-04-23 on #29092). A complete copy made for alpha1/alpha2 keeps
working; it may be reduced to the changed properties.

Detect:
```
grep -rln 'InvitationModule' --include=*.xml .
```

### 3.3 Size of the login dialog (#29092)
The size of the login dialog (`LoginViewDialog`) is now taken from the theme variables
`com.top_logic.layout.component.configuration.Icons.LOGIN_DIALOG_WIDTH` / `LOGIN_DIALOG_HEIGHT`
(theme `core`: 450px, condensed themes: 390px). An application theme can override them in its
`theme-settings.xml`.

---

## 4. Verification checklist

1. `mvn clean install` of the application (with tests if possible).
2. Start the application and read the startup log for configuration errors.
3. Log in via the login dialog and open the application's views.
4. If the application provides OpenAPI server endpoints: call each endpoint that returns a string
   or other non-collection value and check that its clients still accept the response (section 2.1).
5. Report to the user every step that was skipped or needed a decision, and every step that changed
   the behavior of an OpenAPI endpoint.
