alfresco-content-app/docs/upgrade-guide/upgrade441-501.md

Title

Title
Upgrading from ACA v4.4.1 to v5.0.1

Upgrading from ACA v4.4.1 to v5.0.1

This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.4.1 project to v5.0.1 (covering the 5.0.0 and 5.0.1 releases).

This is a major release. The headline change is Angular 14 → 15, which brings the Angular Material MDC migration — the single biggest source of visual breakage. It moves ADF 6.7.1 → 7.0.0-alpha.2 and @alfresco/js-api 7.6.1 → 8.0.0-alpha.2, and TypeScript 4.7 → 4.9. The ADF span crosses three ADF guides (most relevant is the 7.0.0-alpha.2 section of the 6.9 → 7.0 guide, which is the Angular-15 + MDC step):

• ADF — Upgrading from v6.7.1 to v6.8.0
• ADF — Upgrading from v6.8 to v6.9
• ADF — Upgrading from v6.9 to v7.0 (see the 7.0.0-alpha.2 section)

Because of the MDC migration, budget time to re-audit any Material CSS overrides in your fork. Read the breaking changes carefully.

rxjs / Nx note: although ADF's 7.0.0-alpha.2 itself moved to rxjs 7.8 and a newer Nx, ACA's root manifest at 5.0.1 still pins rxjs 6.6.6 and Nx 17.3.1 (and zone.js 0.11.8), so those ADF implications do not apply to your ACA app at this version.

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 15 / TypeScript 4.9 in lockstep. Node 18 (.nvmrc) is unchanged. Budget time to build, re-theme (Material MDC) and re-test after upgrading.

Contents

• Library updates
• Aligning with Angular 15 / ADF 7.0-alpha
  • Angular Material MDC migration
  • ADF standalone components and MaterialModule
  • ADF Notification Service
  • ADF document-list reload
  • js-api v8
• Breaking changes
  • Library public API
  • Services and state rework
  • Extension schema and configuration
• New components and features
• Behavioural changes

Library updates

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

{
    "dependencies": {
        "@angular/core": "15.2.10",
        "@angular/material": "15.2.9",
        "typescript": "4.9.5",
        "@alfresco/adf-core": "7.0.0-alpha.2",
        "@alfresco/adf-content-services": "7.0.0-alpha.2",
        "@alfresco/adf-extensions": "7.0.0-alpha.2",
        "@alfresco/js-api": "8.0.0-alpha.2"
    }
}

@alfresco/adf-cli moves to 7.0.0-alpha.2 too. rxjs (6.6.6), nx (17.3.1), zone.js (0.11.8) and Node (.nvmrc 18) are unchanged. Clean node_modules and the lockfile, then reinstall.

Aligning with Angular 15 / ADF 7.0-alpha

Most of this release is the Angular 15 platform move and adapting to ADF's 7.0.0-alpha.2 changes. See the ADF 6.9 → 7.0 guide (7.0.0-alpha.2 section) for the underlying detail.

Angular Material MDC migration

Angular 15's Material components were rewritten onto MDC, changing their internal DOM and CSS class names (.mat-* → .mat-mdc-*). ACA's NG15 migration (ACS-6693) was followed by a wave of MDC-driven restyling and layout fixes (toolbar buttons, create/upload buttons, mat-tabs, dialog paddings, search input, bulk-action dropdown, badges, folder-rules dialogs). If your fork styles Material internals — directly or by overriding ACA component styles — you must re-audit those styles. This is the biggest source of visual breakage in this upgrade.

ADF standalone components and MaterialModule

ADF 7.0-alpha.2 makes most components standalone and deprecates the shared MaterialModule. ACA:

• updated document-list / column / context-menu / sidenav imports to the standalone ADF symbols (e.g. importing DynamicColumnComponent / DocumentListPresetRef directly instead of ExtensionsModule);
• removed the deprecated shared MaterialModule from its imports.

If your fork imports ADF via NgModules or MaterialModule, import the standalone components / specific @angular/material/* modules directly.

ADF Notification Service

ACA now calls ADF's NotificationService directly for snackbars instead of dispatching NgRx snackbar actions (reworked across the content-management / node-template services, search input, toggle-edit-offline, toggle-join-library, and the library/template/upload/router effects). If you dispatched those ACA snackbar actions, call the ADF service instead.

ADF document-list reload

ACA switched its list-refresh plumbing to ADF's DocumentListService.reload() / reload$ (a 7.0.0-alpha.2 addition), removing its own reload logic from app-hook.service and related effects/actions.

js-api v8

@alfresco/js-api moved to 8.0.0-alpha.2. ACA wired the linked js-api path into tsconfig.adf.json and raised the ACA libraries' peer ranges accordingly. Update any pins to allow js-api 8.

Breaking changes

Library public API

The published ACA libraries changed their public surface:

@alfresco/aca-shared:

• Renamed: aca-file-auto-download.service → auto-download.service (AcaFileAutoDownloadService reworked into AutoDownloadService).
• Moved: the modal-configuration model moved out of @alfresco/aca-shared to @alfresco/aca-shared/store.
• Added: constants, the plugin-enabled.guard (route guard), and the new app-settings.service / user-profile.service (see Services and state rework).

@alfresco/aca-shared/store:

• Removed StoreModule (store.module) — effect registration was simplified; register effects via the app's app-store.module.ts instead of importing the old module.
• Removed dialog.effects (dialog effects were removed) and the unused logout action.
• Added the relocated modal-configuration model.

@alfresco/aca-content/viewer: now also exports PreviewComponent.

Services and state rework

Several concerns moved out of the NgRx store into root-provided services (migrate direct store/config reads):

• UserProfileService — holds the current user profile (userProfile$, loadUserProfile() via PeopleApi + groups); replaces the profile slice of the app reducer.
• AppSettingsService — typed getters over AppConfigService (appName, appVersion, appCopyright, landingPage, aosHost, mimeTypes, appLogoUrl, …). Roughly 800 lines were removed from app.config.json and the corresponding store state; components now read settings from this service.
• AutoDownloadService — the renamed auto-download service now reads its size threshold from AppSettingsService.

Extension schema and configuration

Update your app.config.json / app.extensions.json and any custom extensions:

• aca:fields → app:fields — the custom search-form field property was renamed (in DEFAULT_SEARCH, DUBLIN_CORE, EFFECTIVITY). Rename it in any custom search configuration.
• extension.schema.json review — the userActions and mainAction feature definitions (and a duplicate top-level badges) were removed / relocated. Extensions relying on those schema keys must be updated.
• Blank-page route removed — the blank route was removed from app.routes.ts and app.config.json.
• Plugin routing guard — routes for optional plugins are now gated by a new plugin-enabled.guard (exported from @alfresco/aca-shared).

New components and features

• Manage Holds / bulk Legal Hold — a new Manage Holds dialog with Apply-New-Hold / Manage-Existing-Holds tabs for bulk operations, backed by new bulk-actions-dropdown and datatable-cell-badges components and new bulk-actions / badge-tooltip entries in extension.schema.json (aligns with ADF 7.0's Legal Hold area).
• Security marks for Folder Rules — rule actions can set security marks.
• HxI connector availability — a new store selector reports whether the HxI connector is available.

Behavioural changes

Area	Change
Multi-select	Multi-selection is now on by default across the document lists (files, favorites, libraries, recent-files, shared-files, search-results, trashcan).
Search results	Delete and move actions are now available on the search-results page.
Folder rules	Rule-action node selection changed from multiple to single.
Checkboxes	Selection checkboxes use the Hyland-blue checked state.
Testing (fork note)	Protractor e2e was removed (migration to Playwright is complete); if your fork extends ACA's Protractor harness, move to Playwright.