alfresco-content-app/docs/upgrade-guide/upgrade511-520.md

Title

Title
Upgrading from ACA v5.1 to v5.2

Upgrading from ACA v5.1 to v5.2

This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v5.1.1 project to v5.2.0.

This release is another platform lift: Angular 15 → 16, TypeScript 4.9 → 5.0, rxjs 6 → 7 and zone.js 0.11 → 0.13, on ADF 7.0.0-alpha.3 → 7.0.0-alpha.6 (@alfresco/js-api 8.0.0-alpha.3 → alpha.6). The big new feature is Saved Searches. The relevant ADF changes are the 7.0.0-alpha.4 (Angular 15 → 16) and 7.0.0-alpha.6 sections of:

• ADF — Upgrading from v6.9 to v7.0 (see the 7.0.0-alpha.4 and 7.0.0-alpha.6 sections)

Nx (17.3.1), @ngx-translate/core and Node (.nvmrc 18) are unchanged. Because of the Angular 16 / Material 16 move, budget time to re-audit Material styles and re-test. Read the breaking changes.

Before you begin

Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Move your application to Angular 16 / TypeScript 5.0 / rxjs 7 / zone.js 0.13 in lockstep. Node 18 (.nvmrc) is unchanged.

Contents

• Library updates
• Aligning with Angular 16 / ADF 7.0-alpha
  • Angular 16 migration
  • rxjs 7
  • TypeScript 5 class-field initialization
  • Version manager inputs
• Breaking changes
  • Platform lockstep
  • Context-menu action injection
• New components and features
• Behavioural changes

Library updates

Update the package.json file with the latest library versions:

{
    "dependencies": {
        "@angular/core": "16.2.9",
        "@angular/material": "16.2.9",
        "typescript": "5.0.4",
        "rxjs": "7.5.7",
        "zone.js": "0.13.3",
        "@ngrx/store": "16.3.0",
        "@alfresco/adf-core": "7.0.0-alpha.6",
        "@alfresco/adf-content-services": "7.0.0-alpha.6",
        "@alfresco/adf-extensions": "7.0.0-alpha.6",
        "@alfresco/js-api": "8.0.0-alpha.6"
    }
}

@alfresco/adf-cli, the @angular/* toolchain, @angular-eslint/*, ng-packagr and @ngrx/* all move to their Angular-16 lines. nx (17.3.1), @ngx-translate/core and Node (.nvmrc 18) are unchanged. Clean node_modules and the lockfile, then reinstall.

Aligning with Angular 16 / ADF 7.0-alpha

See the 7.0.0-alpha.4 / 7.0.0-alpha.6 sections of the ADF 6.9 → 7.0 guide for the underlying changes.

Angular 16 migration

The Angular 16 lift (ACS-6693 / the NG16 migration) rewrote a large amount of ACA to Angular 16 / Material 16 / ngrx 16, with the dominant pattern being constructor DI → inject() across components, effects and services. A batch of Material-16 visual fixes was folded in (checkbox focus colour, create-rule dialog, input fill, sidenav/menu colours). If your fork styles Material internals or overrides ACA component styles, re-audit them. (Some NG16 fixes in that squashed migration were provisional — re-test the areas you customise.)

rxjs 7

rxjs moved 6 → 7. The main source change was tightening empty subjects to Subject<void>. Note ACA deliberately kept toPromise() (still present in a handful of services) rather than migrating to firstValueFrom / lastValueFrom; if you do the migration in your own code, be aware toPromise is deprecated in rxjs 7.

TypeScript 5 class-field initialization

TypeScript 5 / Angular 16 enforce stricter class-field semantics (useDefineForClassFields): a class-field initializer that references a constructor-injected dependency now runs before the constructor assigns it. ACA hit this in FolderRuleSetsService (selectedRuleSet$ referenced an injected service in a field initializer and threw on the Manage Rules page); the fix moved the observable construction into the constructor. Audit your own field initializers that use injected dependencies and move them into the constructor (or use inject()).

Version manager inputs

Adopting ADF alpha.4's VersionManagerComponent inputs, ACA's versions tab now binds [allowViewVersions], [allowVersionDelete] and [showActions], driven by new app.config.json keys under adf-version-manager (allowViewVersions / allowVersionDelete / showActions, default true) exposed through AppSettingsService.

The process-services-cloud changes in ADF alpha.4/alpha.6 (counters$ → counters, RUNNING_STATUS → DEPLOYED_STATUS, ContainerModel getters, the process/task search tokens) do not apply to ACA — they are process-cloud only.

Breaking changes

ACA's published library API is additive only this release — no exports were removed, renamed or deprecated (the barrels gain NavigationHistoryService in @alfresco/aca-shared and aca-search-utils in @alfresco/aca-content; the store gains a CustomContextMenu action). The breaking work is the platform move.

Platform lockstep

You must move your application to Angular 16, TypeScript 5.0, rxjs 7 and zone.js 0.13 together with ACA. Run the Angular 16 update (ng update @angular/core@16 @angular/cli@16 @angular/material@16), address the TypeScript-5 class-field caveat above, and re-audit Material 16 styles. A new @angular-eslint/template/prefer-self-closing-tags lint rule was enabled (cosmetic template churn).

Context-menu action injection

The context menu was split so custom actions can be injected. A new base directive [acaContextActions] (with a customActions @Input()), a CustomContextMenuComponent, and a new injection token CONTEXT_MENU_CUSTOM_ACTIONS were added, alongside a store CustomContextMenu action. There are now two population modes: the default acaContextActions (loads from app.extensions.json) or injecting an array of rule-formatted actions via customActions / the token. This is additive, but if you customised the context menu, see docs/features/context-menu-actions.md for the new model.

New components and features

• Saved Searches — save the current search, manage saved searches, and edit / save-as-new. Adds a save-search dialog and an [acaSaveSearch] directive, a full-page Manage Searches list at the new saved-searches route (SavedSearchesSmartListComponent, guarded by AuthGuard), and a sidenav entry registered as the app.search.navbar extension component (under a new app.navbar.secondary group in app.extensions.json). It is backed by ADF's SavedSearchesService / SavedSearch (ADF 7.0-alpha.4).
• Context-menu custom-action injection — see Context-menu action injection.
• NavigationHistoryService (@alfresco/aca-shared) — tracks router history so views can restore the last selection (used by the Knowledge Retrieval "keep selection on back-navigation" behaviour).

Behavioural changes

Area	Change
Knowledge Retrieval	Agent avatars are loaded from the backend (previously mocked); the query/question is removed from the input on the results page; selections and the question are kept when navigating back to the previous page.
Pagination	The items-per-page selector button is now visible.
Version manager	Whether versions can be viewed/deleted and whether actions show is now configurable via app.config.json (adf-version-manager.*).