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

8.0.0-alpha5
TopLogic Release

2026-06-03

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

Migrating a TopLogic application from 8.0.0-alpha4 to 8.0.0-alpha5

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

8.0.0-alpha5 has one migration topic besides the version bump: TL-Script converts numbers to text without locale-dependent formatting (#29064, section 4.1), and the Java method ToString.toString(Object) is gone (section 1.2). It is relevant only for applications that show numbers as text via TL-Script and rely on the user's locale for their formatting, or that call ToString.toString from Java.

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. The Java API change (section 1.2) shows up as a compile error. The changed number formatting (section 4.1) shows up only at runtime, as differently formatted numbers in labels, tooltips, columns and texts.
  3. Section 7 lists behavior changes 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-alpha5 (parent tl-parent-app / tl-parent-core version, or the tl.version property).

Detect:

grep -rn --include=pom.xml -e '8.0.0-alpha4' .

1.2 ToString.toString(Object) removed (#29064) — mandatory where applicable

The Java method com.top_logic.model.search.expr.ToString.toString(Object) no longer exists. Use com.top_logic.model.search.expr.SearchExpression.asString(Object) (now static) instead. Note that asString formats numbers without the user's locale (section 4.1).

Before:

String text = ToString.toString(value);

After:

String text = SearchExpression.asString(value);

Detect:

grep -rn -e 'ToString.toString' --include=*.java .

4. TL-Script in views and layouts

4.1 Number-to-text conversion no longer locale-dependent (#29064) — mandatory where applicable

The conversion of values to text in TL-Script is unified (SearchExpression.asString). Numbers are no longer formatted according to the user's language, but without thousands separators and with a decimal point; integral values are written without decimal places (1234.5 instead of 1.234,5, 2019 instead of 2.019).

Affected are:

  • the function toString(...),
  • string concatenation with +,
  • join(...),
  • label, tooltip, icon and column providers defined in TL-Script (LabelProviderByExpression, TooltipProviderByExpression, IconProviderByExpression, ComputedColumnProviderByExpression),
  • InstanceResolverByExpression.

Where a locale-dependent representation is needed, format the number explicitly.

Before (number shown as 1.234,5 for a German user):

"Total: " + $total

After:

"Total: " + numberFormat("#,##0.00").format($total)

Check every hit that converts a number to text; leave expressions that work with strings, objects or dates unchanged. Expressions configured in-app (stored in the database or in overlay files of the running application) are not found by the search; ask the user whether such configurations exist.

Detect:

grep -rn -e 'toString(' -e 'ByExpression' -e 'join(' --include=*.xml .

7. Further notes (no action required)

7.1 TL-Script: database query optimization with parameters (#29064)

A filter over all(...) that the engine turns into a database query is now also optimized when it is moved into a function and called with a parameter, e.g.

calcValue = id -> {
    all(`myModule:myType`).filter(x -> $x.get(`myModule:myType#id`) == $id)
};
$calcValue("4711")

Previously only the form with a literal value was optimized. Results are unchanged; such expressions (e.g. in REST endpoints with parameters) just run faster.

7.2 Generator errors are marked as errors in the build output (#29292)

The output of the Java binding generation (tl-maven-plugin:generate-java) now prefixes each line with [ERROR] or [INFO], so the actual cause of a failed generation can be found in the Maven log. In addition, an error while writing a messages file of the generated bindings now aborts the generation; previously it was only logged and the build reported success with a missing file.

7.3 Known issue in 8.0.0-alpha5: optimized queries with transient objects (#29340)

A TL-Script expression that is optimized into a database query (section 7.1) fails in 8.0.0-alpha5 when a transient object is passed as a parameter (follow-up of #29064). This is fixed in 8.0.0-alpha6; no workaround is required in the application.

7.4 Bug fixes

  • Attributes with a fallback value on transient objects (#29304): a value set on a transient object (e.g. in the detail dialog of a composition row) is now stored where it is read again and is taken over into the row object.
  • Configured TL-Script functions (#29305): defining a function in the service editor with a description in only one language no longer fails with a NullPointerException.
  • Undo (#29314): reverting changes whose commit message is a literal text (e.g. set by an application-specific undo button) no longer fails with UnsupportedOperationException: Must not resolve literal text as key.
  • Change log (#29318): the change set analysis no longer fails with a NullPointerException when a created object belongs to a non-versioned type.

8. Verification checklist

  1. mvn clean install of the application (with tests if possible). If the Java binding generation fails, search the build log for [ERROR] lines of the generator (section 7.2).
  2. Start the application and read the startup log for configuration and migration errors.
  3. Log in and open every view of the application; check that numbers in labels, tooltips, table columns and generated texts are formatted as intended (section 4.1).
  4. Report to the user every step that was skipped or needed a decision, and every TL-Script expression changed for section 4.1.
  • 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