Migrating a TopLogic application from 7.10.0 to 8.0.0-alpha1
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-alpha1/ and the
TopLogic Trac tickets flagged RequiresMigration for milestone TL_8.0.0-alpha1 (ticket numbers
are given as #NNNNN; the per-ticket page is https://dev.top-logic.com/tl/content/releases/TL_8.0.0-alpha1/NNNNN/).
How to use this document
- Work through the sections in order. Section 1 must be done first (the project does not build otherwise); the rest can be done in any 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.
- Many changes are reported as configuration errors at application start or when a layout is
loaded (not at compile time), e.g. unknown configuration properties. After migrating, start the
application, log in, and open every view; read the log for
ConfigurationException/ configuration errors. - Several automatic data migrations run at the first start on the new version (named in the steps). Back up the database before the first start. Some steps below must be done before that start, because the automatic migration drops data.
- Ticket descriptions on Trac are partly German; this document translates the instructions.
Search commands below assume the project root as working directory and GNU grep.
1. Build and platform
1.1 Version bump
Set the TopLogic version to 8.0.0-alpha1 (parent tl-parent-app / tl-parent-core version, or
the tl.version property).
1.2 Custom resource keys in I18NConstants (#29111) — Java
ResKey fields in I18NConstants classes that get a custom resource key through legacyKey(),
legacyKey1(), legacyKey2(), … must use the new annotation @CustomKey
(com.top_logic.basic.i18n.CustomKey) instead. The field must not be initialized —
initConstants() assigns it from the annotation. The same applies to fields initialized with
ResKey.internalCreate("...").
Before:
public static ResKey MY_KEY = legacyKey("my.custom.key");
public static ResKey1 MY_KEY_1 = legacyKey1("my.custom.key");
After:
@CustomKey("my.custom.key")
public static ResKey MY_KEY;
@CustomKey("my.custom.key")
public static ResKey1 MY_KEY_1;
Reason: only then do the runtime (I18NConstantsBase) and the build-time doclet (TLDoclet) use
the same key, so @en JavaDoc translations are written to messages_en.properties under the custom
key. Note: in 8.0.0-alpha1 the legacyKey*() methods still exist (deprecated), so unconverted code
still compiles — but @en JavaDoc translations of such fields end up under the wrong key.
Optional tool (only if asked): com.top_logic.layout.tools.cleanup.MigrateResourcesToJavaDoc moves
English translations from WEB-INF/conf/resources/*_en.properties into @en JavaDoc tags of the
matching ResKey fields (respecting @CustomKey) and removes the moved entries from the properties
files.
Detect:
grep -rn -e 'legacyKey[0-9]*(' -e 'ResKey.internalCreate(' --include=*.java .
2. Server configuration and login (*.config.xml, web.xml, layouts)
2.1 Login page replaced by an in-app dialog (#29092) — mandatory if referenced
The new module tl-security-selfservice (password reset, second-factor reset, invitations) is an
optional dependency and needs no action. The core login, however, was rewritten for a two-step
flow (multi-factor authentication):
LoginPageServlet (mapping /servlet/login), login.jsp, login.banner.inc, doOnload.inc,
jsp/main/loginError.jsp, jsp/util/administration/changePwd.jsp and script/tl/loginError.js are
deleted. A request without a session now gets an anonymous session, and the layout offers the
LoginViewDialog through the new <login-hooks> of MainLayout$GlobalConfig (framework default:
OpenLoginDialogHook).
- Delete application overlays of the removed JSPs and includes, and
web.xmlentries forLoginPageServlet. Bookmarks and monitoring probes pointing to/login.jspor/servlet/loginmust use/servlet/LayoutServlet. - Remove
login,loginRetryPage,loginErrorPageandchangePasswordfrom anApplicationPages$Configoverride; these properties no longer exist (unknown property = startup error).loginPage,logoutPageandloginRetrySSOdefault to/servlet/LayoutServlet. - Login-messages addon:
LoginMessagesMainLayoutand itsGlobalConfigare replaced by the login hookLoginMessagesHook. Remove aMAIN_LAYOUT_CLASStheme setting naming the old class and theLoginMessagesMainLayout$GlobalConfigblock; the addon'sloginMessagesConf.config.xmlregisters the hook itself:<config config:interface="com.top_logic.mig.html.layout.MainLayout$GlobalConfig"> <login-hooks> <login-hook class="com.top_logic.addons.loginmessages.layout.LoginMessagesHook" showLoginMessages="true"/> </login-hooks> </config> - Resource keys:
tl.logoutis nowclass.com.top_logic.layout.component.configuration.I18NConstants.LOGOUT;layouts.admin.persons.changePassword.*moved toclass.com.top_logic.knowledge.gui.layout.person.I18NConstants.CHANGE_PASSWORD_FORM.*;MAX_USERS_EXCEEDEDis gone. Update own references to and own translations of these keys. - A session may now belong to the
anonymousaccount (PersonManager.getAnonymous(),TLContext.isAnonymous()), andPerson.all()contains that account. Check own code that iterates all persons or assumes a logged-in user. - Application copies of engine layout files must be adapted to the anonymous session:
- In a copy of
toolrow/homeButton.xml, wrap the user menu (PopupViewConfiguration) in aConditionalViewConfigurationwithcondition="com.top_logic.util.IsAnonymousUser"andinvert="true"; otherwise anonymous users see the user menu. - In a copy of
themes/core/templates/navigationComponent.xml, addlogin-image="theme:IMAGE_BUTTONS_LOGIN"to thelogoutView(icon of the login action while no user is logged in). ThecoreSidebarvariant no longer contains alogoutView.
- In a copy of
Detect:
grep -rn -e 'LoginPageServlet' -e 'servlet/login' -e 'login.jsp' -e 'login.banner.inc' -e 'doOnload.inc' \
-e 'loginError' -e 'changePwd.jsp' -e 'ApplicationPages' -e 'loginRetryPage' -e 'loginErrorPage' \
-e '<changePassword>' -e 'LoginMessagesMainLayout' -e 'MAIN_LAYOUT_CLASS' -e 'tl\.logout' \
-e 'layouts.admin.persons.changePassword' -e 'MAX_USERS_EXCEEDED' .
find . \( -path '*WEB-INF/layouts/toolrow/homeButton.xml' -o -path '*templates/navigationComponent.xml' \) -not -path '*/target/*'
2.2 Authentication devices, module list, account form (#29092) — mandatory if configured
mfa-requirementis mandatory onDBAuthenticationAccessDevice.ConfigandLDAPAuthenticationAccessDevice.Config. The core setsoptionalfordbSecurityand%LDAP_MFA_REQUIREMENT%(defaultoptional) inldapConf.config.xml. An application declaring its own<security-device>of one of these classes (or a copiedldapConf) must addmfa-requirement="optional|required|disabled".- Applications that maintain their own
<modules>list (ModuleSystem configuration) must enablecom.top_logic.base.accesscontrol.LoginFailuresModule$Module. - Automatic data migration
Ticket_29092_multi_factor_authentication(tl-element) addsPerson#mfaSecretandPerson#mfaRequirement. Thetl-layout-formeditormigration of the same name replaces the form definition annotation oftl.accounts:Person: an in-app customisation of the account form is lost and must be re-applied after the update. If the account form was customised in-app, record it before the first start and tell the user.
Detect:
grep -rn -e 'DBAuthenticationAccessDevice' -e 'LDAPAuthenticationAccessDevice' -e '<security-device' \
-e 'ldapConf' -e '<modules>' .
2.3 SessionService / UserMonitor options (#29106) — mandatory if configured
- The options
excludeUIDsandonlyOneSessionofcom.top_logic.base.accesscontrol.SessionServiceare removed → delete them (left over → configuration error at startup). - If
excludeUIDsofcom.top_logic.knowledge.monitor.UserMonitoris configured, configure it on theSessionServiceinstead:<config service-class="com.top_logic.base.accesscontrol.SessionService"> <instance> <listeners> <listener name="storeEvent"> <impl class="com.top_logic.knowledge.monitor.StoreUserEventListener" excludeUIDs="..."/> </listener> </listeners> </instance> </config> - Java:
UserMonitor.login(...),logout(...),notifyUserEvent(...),findUserSession(...)andfindSessionOnServer(...)are removed.
Detect:
grep -rn -e 'onlyOneSession' -e 'excludeUIDs' -e 'UserMonitor' .
3. Security / access checks
3.1 Role rules navigate only over the model; hasRole / hasGlobalRole (#28710) — mandatory
3.1.1 Role rule configuration
Role rules of the AccessManager (e.g. InitialRoleRule.xml) must be converted. Security works only
over the model, i.e. a rule necessarily needs an attribute and possibly a meta-element.
<step association="…">: instead of navigating over the association table in general, find the model attribute whose values are stored in that table and navigate over it:
becomes<step association="hasStructureChild" inverse="false" /><step attribute="children" inverse="false" /><rule meta-object="…">: instead of the table type, give the TL model type:
becomes<rule meta-object="StoredQuery" ...<rule meta-element="tl.search:StoredQuery" ...- Likewise, the attribute
source-meta-objectis removed: instead of the table type, give the TL model type withsource-meta-element. - The extension points
ExternalRoleProvider(<role-provider>) andSecurityStorageCommitObserver(<commit-observer>) of theElementAccessManagerand the classFallbackAccessManagerare removed without replacement; express programmatic role assignment as a configured role rule.
Detect:
grep -rn -e '<step association=' -e 'meta-object=' -e '<role-provider' -e '<commit-observer' \
-e 'ExternalRoleProvider' -e 'SecurityStorageCommitObserver' -e 'FallbackAccessManager' .
3.1.2 Data migration — check before the first start
The migrations Ticket_28710_Removed_legacy_types, Ticket_28710_Update_application_types and
Ticket_28710_RoleAssignment_TLSearch (module tl-element) run automatically at the first start.
- Directly assigned global roles are lost. The table
hasGlobalRoleis dropped; its data is not transferred. Only applications that assigned roles programmatically viaPerson#addGlobalRole(...)are affected (the engine had no UI for it). Map such assignments to a group membership plus role rule before the update. - The application must delete its own legacy table types. The modules
tl.legacy.tabletypesandtl.tablesno longer exist; the engine migration deletes only the engine's types (tl.legacy.tabletypes:PersonTable,tl.tables:PersonTableInterface, …). If the application's database still contains own types of these modules (from the update TL 6 → TL 7 or fromTableInterface-based models), the application deletes them in its own migration and retypes attributes pointing to such types (change-part-type ... target="tl.accounts:Person"). Template in the engine:com.top_logic.demo/src/main/webapp/WEB-INF/kbase/migration/tl-demo/Ticket_28710_Removed_legacy_types.migration.xml(it depends onTicket_28710_Removed_legacy_typesof moduletl-elementand deletes the types with<delete-class name="tl.legacy.tabletypes:…" skip-model-baseline-change="true"/>). Remove configuration references such asIndexedObjectNaming<type name="tl.legacy.tabletypes:...">ordefaultFor="tl.legacy.tabletypes:...". hasRoleis no longer aKnowledgeAssociationbut anMOKnowledgeObjectof model typetl.accounts:RoleAssignment(referencessource,dest,owner);hasGlobalRoleis gone. Adapt own*Meta.xmlfiles referencing these tables.
Detect:
grep -rn -e 'addGlobalRole' -e 'hasGlobalRole' -e 'hasRole' -e 'tl.legacy.tabletypes' -e 'tl\.tables:' \
-e 'TableInterface' -e 'IndexedObjectNaming' .
Own legacy types that exist only in the database are not found by grep: check the types of the
existing database (model editor or table META_ELEMENT) for the modules tl.legacy.tabletypes and
tl.tables and report them to the user.
3.1.3 Java API
BoundedRole.HAS_ROLE_ASSOCIATIONis removed. Role assignments are written withBoundedRole.assignRole(context, person|group, role)and read withgetLocalAndGlobalRoles(context, person)and the queriesroleAssignmentsForContext(...),roleAssignmentsForRole(...)(they return aCloseableIteratorthat must be closed). Code navigatinggetOutgoingAssociations(HAS_ROLE_ASSOCIATION)must be converted.Person#getGlobalRoles(),addGlobalRole(...)andremoveGlobalRole(...)are removed.LegacyFlexWrapperandStoredFlexWrapperare removed: wrapper classes extending them (likeStoredQueryandStoredReportin the engine) extendcom.top_logic.element.meta.kbbased.AttributedWrapper;MapBasedPersistancySupport.getObjects(KnowledgeItem)andsetObjects(Collection, KnowledgeItem)replace theFlexDatavariants.AccessManager#handleSecurityUpdate(KnowledgeBase, Map, Map, Map, CommitHandler)is nowhandleSecurityUpdate(TLObjectChangeSet, CommitHandler); likewiseLogHandler#logSecurityUpdate(TLObjectChangeSet, Map, Set). An override with the old signature is silently no longer called if it lacks@Override— check every subclass.- The constructors of
RoleRuletaking aMetaObjectandPathElement(String associationType, boolean)are removed; rules navigate only over attributes.ElementAccessManager#getRules()returnsMap<TLClass, Collection<RoleProvider>>.
Detect:
grep -rn -e 'HAS_ROLE_ASSOCIATION' -e 'getGlobalRoles' -e 'removeGlobalRole' -e 'LegacyFlexWrapper' \
-e 'StoredFlexWrapper' -e 'FlexData' -e 'MapBasedPersistancySupport' -e 'handleSecurityUpdate' \
-e 'logSecurityUpdate' -e 'new RoleRule(' -e 'new PathElement(' -e 'getRules(' --include=*.java .
5. Classic UI, model and other Java APIs
5.1 Authentication and account Java API (#29092) — Java
Login.login(userName, request, response)→Login.checkUserPassword(userName, char[] password, request, response);Login.login(request, response, credentials)→Login.checkLoginCredentials(credentials, request, response). Both only check the credentials; the caller creates the session withSessionService.getInstance().loginUser(request, response, person).MaxUsersExceededExceptionis replaced byLoginHookFailedException.LoginCredentialsis no longerAutoCloseable: callclearPassword()in afinallyblock (instead of try-with-resources).ExternalAuthenticationServlet(base class of SSO servlets) extendsNoContextServletinstead ofLoginPageServlet:forwardPage(...)→forwardToPage(...),forwardToStartPage(...)→redirectToStartPage(...);checkRequest(...)andforwardToTarget(...)can no longer be overridden;forwardToSSOLoginFailed(...)declaresIOException, ServletException. Subclasses that only implementretrieveLoginCredentials(...)need no change.LoginPageServlet.appendCustomParameters(...)andPARAM_START_PAGEmoved toAbstractTopLogicServlet.forwardPage(...)is also removed fromTopLogicServletandAJAXServlet;TopLogicServletnow extendsAbstractTopLogicServlet. The classescom.top_logic.base.accesscontrol.SessionAttributeKeysandcom.top_logic.util.DispatchExceptionare deleted.TLPersonManageris deleted: configure and extendcom.top_logic.knowledge.wrap.person.PersonManager(asContactPersonManagerdoes; itsConfigis no longer generic).PersonManagerextendsKBBasedManagedClass, so subclasses callsuper(context, config). Replacement forgetAllAliveFullPersons():Person.all().stream().filter(Person.FULL_USER_FILTER).Person.create(kb, name, String deviceId)→Person.create(kb, name, AuthenticationDevice device).AuthenticationDevice.getMFARequirement()is a new abstract method: own devices implement it (e.g. returningMfaRequirement.DISABLED).FormMember.setLabel(ResKey),setTooltip(ResKey)andsetTooltipCaption(ResKey)were added next to theStringvariants; a call with a literalnullis ambiguous and must be cast (setLabel((String) null)).ListStorage.listConfig(...),SetStorage.setConfig(...)andSingletonLinkStorage.singletonLinkConfig(...)take a trailingboolean unversioned(passfalsefor the previous behaviour).- The deprecated
MetaElementUtil.getAllInstancesOf(TLClass)andgetAllDirectInstancesOf(TLClass)are removed; use the overloads with the expected class (getAllInstancesOf(type, Wrapper.class)). Base32is renamed toEncodeTypable(same static method names).
Detect:
grep -rn -e 'Login\.' -e 'MaxUsersExceededException' -e 'LoginCredentials' -e 'ExternalAuthenticationServlet' \
-e 'forwardPage(' -e 'forwardToStartPage' -e 'LoginPageServlet' -e 'SessionAttributeKeys' \
-e 'DispatchException' -e 'TLPersonManager' -e 'getAllAliveFullPersons' -e 'getAllAliveRestrictedPersons' \
-e 'Person.create(' -e 'AuthenticationDevice' -e 'setLabel(null)' -e 'setTooltip(null)' \
-e 'setTooltipCaption(null)' -e 'listConfig(' -e 'setConfig(' -e 'singletonLinkConfig(' \
-e 'getAllInstancesOf(' -e 'getAllDirectInstancesOf(' -e 'Base32' .
5.2 Table rows after changes in other sessions: supportsListElement / supportsElement (#29080)
Tables, tree tables and grids no longer add a changed or created object as a row just because the
list builder "supports" it. If object types are configured on the table, an instanceOf check is
done automatically, and only matching objects are passed to ListModelBuilder#supportsListElement.
The new constant com.top_logic.mig.html.ElementUpdate.UNKNOWN makes the table rebuild its row list
via the model builder. ListModelByExpression returns UNKNOWN if no supportsElement script is set
(new in-app tables/grids are created without supportsElement).
Steps:
- Java list builders: if it is unclear whether an object must be added to or removed from the list,
ListModelBuilder#supportsListElementmust returnElementUpdate.UNKNOWN. - In-app tables and grids must be checked: if the table/grid shows all objects of a type, the
supportsElementscript must returntrue; if the table/grid should rebuild its list when an element of the supported type is created, leavesupportsElementempty. The script may return"unknown"if it cannot decide whether an element must be added or removed (corresponds toElementUpdate.UNKNOWN). - Subclasses of
SelectableBuilderComponentthat overridereceiveModelCreatedEvent(Object, Object)overridehandleTLObjectCreations(Stream<? extends TLObject>)instead. - The classes
com.top_logic.element.layout.security.GlobalDomainandAttSecMetaElementLabelProviderare removed.
Detect:
grep -rn -e 'supportsListElement' -e 'supportsElement' -e 'receiveModelCreatedEvent' -e 'GlobalDomain' \
-e 'AttSecMetaElementLabelProvider' .
In-app layouts stored in the database are not found by grep: after the start, list the in-app tables
and grids with a supportsElement script (layout editor) and report them to the user for review.
5.3 Abstract attributes are not accessible any more (#29073) — model
Reading an abstract attribute used to return null (e.g. on transient objects). Now every access to
an abstract attribute throws an error. This affects domain models in which an inherited abstract
attribute (such as StructuredElement#parent) was not redeclared properly (usually in the root
type). A structure based on StructuredElement must be built like this:
// Top-level type of the structure - each type must extend it.
MyNode extends StructuredElement {
parent: MyContainer
}
// Abstract child type in the structure - each type with substructure must extend it.
abstract MyContainer extends MyNode, StructuredElementContainer {
}
// Concrete type with children.
NodeA extends MyContainer {
children: ...
}
NodeB extends MyContainer {
children: ...
}
// Concrete type without children.
NodeC extends MyNode {
}
Detect:
grep -rln -e 'StructuredElement' -e 'abstract="true"' --include=*.model.xml .
For each hit, check that every abstract attribute inherited by a concrete class is redeclared. Violations otherwise appear at runtime when the attribute is accessed (forms, tables, scripts).
5.4 Workflows deployed in WEB-INF/workflow (#29037) — tl-bpe only
Workflows in src/main/webapp/WEB-INF/workflow are now re-imported automatically when the content
of their file changes (a hash per file is stored). At the first start on the new version, only the
hashes of the already imported workflows are recorded — the workflows are not updated. If an
update is wanted on this occasion, add a migration that replaces the stored value loaded by a hash
that does not match the current file, using the migration processor
<update-tl-properties property="initial-workflow.<resource>" value="<wf-name>:XXX" />
<resource>: name of the resource below/WEB-INF/workflow/that defines the initial workflow, e.g.Ticketsystem.bpml.xmlfor/WEB-INF/workflow/Ticketsystem.bpml.xml.<wf-name>: name of the workflow as given in the file; if none is given, the file name up to the first.(e.g.Ticketsystem).XXXstands for the "old hash". Since the file's hash differs fromXXX, the workflow is updated.
Java: com.top_logic.bpe.modeler.upload.Updater is now com.top_logic.bpe.util.Updater (module tl-bpe).
Detect:
find . -path '*WEB-INF/workflow/*' -not -path '*/target/*'
grep -rn 'bpe.modeler.upload.Updater' --include=*.java .
7. Further notes (no action required)
- #29092: a request without a session gets an anonymous session; the login is an in-app dialog.
Accounts can set up a TOTP second factor; whether it is enforced is controlled per account by
mfaRequirement(default from themfa-requirementof the authentication device). An administrator can remove the secret of an account. - #29092: in 8.0.0-alpha1 the service configuration of the optional module
tl-security-selfservice(InvitationModule) is located in itsWEB-INF/autoconffolder; an application that wants to change it has to override that configuration completely (from a Trac comment on #29092). - #29037: existing workflows are not re-imported at the first start (an earlier version of the ticket said in-app modified workflows had to be saved because of a re-import; that no longer applies).
8. Verification checklist
mvn clean installof the application (with tests if possible).- Back up the database; start the application against a copy of the production data.
- Read the startup log: no configuration errors (removed
ApplicationPagesproperties,onlyOneSession/excludeUIDs, missingmfa-requirement,TLPersonManager, role-rule attributesassociation/meta-object,role-provider/commit-observer), and the automatic migrationsTicket_28710_*andTicket_29092_*ran successfully. - Open the application without a session: the login dialog appears; log in as a normal user and as administrator; anonymous users must not see the user menu.
- Open every view; check tables/trees/grids showing objects created or changed in another session (#29080) and forms of structure types (#29073).
- Check access: users get the roles defined by the role rules (no lost global roles).
- Report to the user every step that was skipped, needed a decision, or touches data (global roles, own legacy table types, account form customisation, workflow re-import).