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

8.0.0-alpha3
TopLogic Release

2026-04-24

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

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.
  • Get Started
  • Github
  • Discord
  • Das Unternehmen hinter TopLogic
  • Softwareentwicklung heute
  • Kontakt

© Copyright – Business Operation Systems GmbH

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