alfresco-content-app/docs/upgrade-guide/upgrade530-600.md

Title

Title
Upgrading from ACA v5.3 to v6.0

Upgrading from ACA v5.3 to v6.0

This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v5.3.0 project to v6.0.0.

This is a major release. The headline changes are Angular 16 → 17, Node 18 → 20, and ADF / @alfresco/js-api reaching their final 7.0.0 / 8.0.0 releases (from 7.0.0-alpha.7 / 8.0.0-alpha.7). It also moves TypeScript 5.0 → 5.3, zone.js 0.13 → 0.14, and NgRx 16 → 17. The relevant ADF change is the 7.0.0 (final) section — the Angular 17 step — of:

• ADF — Upgrading from v6.9 to v7.0 (see the 7.0.0 (final) section)

Because of the Angular 17 / Material 17 move and the Node 20 bump, budget time to rebuild your toolchain, re-audit Material styles and re-test. Read the breaking changes carefully.

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 17 / TypeScript 5.3 / zone.js 0.14 / NgRx 17 in lockstep, and update your build/CI environment to Node 20 (.nvmrc is now 20.18.1).

Contents

• Library updates
• Aligning with Angular 17 / ADF 7.0
  • Angular 17 migration
  • Node 20
  • ADF 7.0 final — what applies to ACA
• Breaking changes
  • Platform lockstep
  • Library public API
• New components and features
• Behavioural changes

Library updates

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

{
    "dependencies": {
        "@alfresco/adf-core": "7.0.0",
        "@alfresco/adf-content-services": "7.0.0",
        "@alfresco/adf-extensions": "7.0.0",
        "@alfresco/js-api": "8.0.0",
        "@angular/core": "17.1.3",
        "@angular/material": "17.1.2",
        "@ngrx/store": "17.0.1",
        "typescript": "5.3.3",
        "zone.js": "0.14.8"
    }
}

The whole @angular/* toolchain moves to 17.1.x, @ngrx/* to 17.0.1, @angular-eslint/* to 17.x, @typescript-eslint/* 5 → 6.21.0, @nx/* 17.0.2 → 17.3.2, ng-packagr 16 → 17.1.2, @mat-datetimepicker/core 12 → 13, tslib → 2.8.1, and @alfresco/adf-cli / @alfresco/eslint-plugin-eslint-angular to 7.0.0. rxjs stays 7.8.1. Node moves 18 → 20.18.1 (.nvmrc). Unlike ADF (which migrated its test runner to Jest in 7.0.0), ACA keeps Karma/Jasmine. Clean node_modules and the lockfile, then reinstall.

Aligning with Angular 17 / ADF 7.0

See the 7.0.0 (final) section of the ADF 6.9 → 7.0 guide for the underlying platform detail.

Angular 17 migration

ACA was lifted to Angular 17 / Material 17 / NgRx 17 (ACS-6849). Run the Angular 17 update (ng update @angular/core@17 @angular/cli@17 @angular/material@17) against your fork. ACA did not adopt Angular 17's new built-in control-flow syntax (the @if / @for blocks); templates still use the classic ngIf / ngFor structural directives, so you do not need to run that migration to stay aligned. Re-audit any Material style overrides against Angular 17.

Node 20

The build now requires Node 20 (.nvmrc 20.18.1, MNT-24892). Update your local toolchain, Docker base image and CI runners to Node 20; Node 18 is no longer supported.

ADF 7.0 final — what applies to ACA

Most of ADF 7.0.0's breaking removals are in areas ACA does not consume:

• MomentDatePipe / MomentDateTimePipe removed — ACA does not use them (no change needed).
• The FormModel / FullNamePipe signature changes, the new form-validator injection tokens, the service-task data-shape change and the Screens API are process/forms-cloud concerns and do not apply to ACA.

What ACA does pick up from ADF 7.0.0:

• DocumentListComponent displayDragAndDropHint input — ACA binds this to hide the drag-and-drop upload hint when files cannot be uploaded to the current location (see New components and features).
• SavedSearchesPreferencesApiService / SAVED_SEARCHES_SERVICE_PREFERENCES — ADF 7.0.0 made Saved Searches persist through the Preferences API, which ACA now adopts (see below).

Breaking changes

Platform lockstep

You must move your application to Angular 17, TypeScript 5.3, zone.js 0.14 and NgRx 17 together with ACA, and run it on Node 20. This is the dominant breaking change; there are no ACA source-API removals in this release.

Library public API

The published ACA libraries are additive only — no exports were removed or renamed (only the copyright header year changed across the barrels). @alfresco/aca-content gains two new exports:

• ContentManagementService — the content-management service is now part of the public API (previously internal), so extensions can call it directly.
• ExternalNodePermissionCommentsTabService — a new abstract service (canAddComments(node): boolean) intended as a DI override point, letting a downstream app decide whether comments can be added for a node (e.g. on retained / record documents).

New components and features

• Saved Searches persisted via the Preferences API (ACS-9166) — Saved Searches now persist through the Alfresco Preferences API (adopting ADF 7.0.0's SavedSearchesPreferencesApiService) instead of the config file. (This migration was first attempted in the 5.3.0 cycle and reverted; it lands in 6.0.0.)
• Comments extension point — the new ExternalNodePermissionCommentsTabService lets an app control comment availability; ACA uses it so comment creation is available on documents that have been retained / declared as records (ACS-9083).
• Drag-and-drop hint gating (ACS-8782) — the drag-and-drop upload hint is hidden when files cannot be uploaded to the current location (e.g. frozen files under a hold); this is what surfaced ContentManagementService as a public export.
• Accessibility — the notification and user menus are now keyboard-accessible (ACS-9266), plus a wave of a11y fixes across the sidebar, search page, breadcrumbs and Create Rule dialog (colour-contrast thresholds, supported ARIA attributes, and discernible button text — ACS-9225 / 9228 / 9229 / 9235 / 9236).

Behavioural changes

Area	Change
Node Details page	The View Details button was removed from the node Details page (ACS-9158).
Extensions	Extension visibility rules are used in array form in app.extensions.json; single-element arrays no longer log errors (ACS-9346 / ACS-9369).
Records mgmt	The permission error message shown when opening a records-management library was changed (ACS-9344).
Saved searches	The Saved Search navbar title is now translated (ACS-9119).
Login	The license displayed on the login page is updated from SSO (ACS-9213).
Search input	Search-input focus styles were fixed (ACA-4735).
Documentation	Product documentation links moved from docs.alfresco.com to support.hyland.com (ACS-9371); update any hardcoded doc links in a fork.