alfresco-content-app/docs/upgrade-guide/upgrade43-441.md

Title

Title
Upgrading from ACA v4.3 to v4.4.1

Upgrading from ACA v4.3 to v4.4.1

This guide provides instructions on how to upgrade your Alfresco Content Application (ACA) v4.3.0 project to v4.4.1 (covering the 4.4.0 and 4.4.1 releases).

This is a large release: it moves ADF 6.4.0 → 6.7.1 (spanning several ADF releases) and @alfresco/js-api 7.1.0 → 7.6.1, so most of the work is adapting to the ADF breaking changes across 6.5.2, 6.6.0 and 6.7.x. Read those ADF guides alongside this one:

• ADF — Upgrading from v6.4 to v6.5.2
• ADF — Upgrading from v6.5.2 to v6.6.0
• ADF — Upgrading from v6.6.0 to v6.7.1

Angular, Material, TypeScript, rxjs and the Node version are all unchanged; the build tooling moves to Nx 17. ACA's published library API (@alfresco/aca-shared / @alfresco/aca-content entry points) is unchanged — no exports removed or renamed — so the consumer-facing work is mostly app.config.json / app.extensions.json configuration plus adopting new ADF capabilities. Read the breaking changes.

Before you begin

Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Node 18 is still required (unchanged). The steps below involve configuration changes — commit or back up your work first.

Contents

• Library updates
• Aligning with ADF 6.5 / 6.6 / 6.7
  • Authentication — PKCE / code flow
  • Search — Elasticsearch, date range and highlighting
  • Content metadata read-only model
  • Viewer close-button position
  • Document-list resizing, persistence and drag-drop columns
  • Theming
  • Disabling tags and categories
• Breaking changes
  • Configuration changes
  • Nx 17 workspace migration
  • adf-testing dependency dropped
  • E2E selector changes
• New components and features
• Behavioural changes

Library updates

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

{
    "dependencies": {
        "@alfresco/adf-core": "6.7.1",
        "@alfresco/adf-content-services": "6.7.1",
        "@alfresco/adf-extensions": "6.7.1",
        "@alfresco/js-api": "7.6.1"
    }
}

@alfresco/adf-cli moves to 6.7.1; @alfresco/adf-testing was removed as a dependency. (4.4.0 shipped ADF 6.7.0 / js-api 7.6.0; the 4.4.1 patch bumps them to 6.7.1 / 7.6.1.) The build tooling moved to Nx 17 (@nx/* / nx 17.x, from 16.10.0). Angular (14.1.3), TypeScript (4.7.4), rxjs (6.6.6) and Node (.nvmrc 18) are unchanged. Clean node_modules and the lockfile, then reinstall.

Aligning with ADF 6.5 / 6.6 / 6.7

Most of this release adapts ACA to the ADF breaking changes across three releases. Each item links back to the ADF guide that describes the underlying change.

Authentication — PKCE / code flow

ACA switched its default OAuth2 flow to PKCE authorization-code flow: in app.config.json, implicitFlow: true became implicitFlow: false + codeFlow: true (and a new APP_CONFIG_OAUTH2_CODE_FLOW Docker env var). If your app.config.json pins oauth2.implicitFlow, review it against the new default. (See ADF 6.6 → "Authentication and SSO renames".)

Search — Elasticsearch, date range and highlighting

• Elasticsearch query migration — the search configuration in app.extensions.json was updated for the Elasticsearch backend (e.g. -PNAME:'0/wiki' → -PATH:'//cm:wiki/*', and autocomplete options gained a query). (See ADF 6.5.2 → "Search query migration (Elasticsearch)".)
• Date-range widget — every "selector": "date-range-advanced" reverted to "date-range" (now the tabbed advanced widget), the date-format token changed DD-MMM-YY → dd-MMM-yy, and displayedLabelsByField maps were added. (See ADF 6.6 → "Search date-range widget replaced".)
• Search highlighting — ACA now renders ADF search highlight snippets (config added under the results row).

If you customised the search configuration, reconcile it against the new app.extensions.json.

Content metadata read-only model

Following ADF's content-metadata rework, ACA's metadata tab adopted the readOnly model (the previous editable input was inverted to readOnly with the opposite meaning) and re-wires the displayed aspect through the store. If you extend the metadata tab, migrate editable usage to readOnly. (See ADF 6.6 → "Content metadata property panels".)

Viewer close-button position

The viewer close button's position is now configurable via viewer.closeButtonPosition in app.config.json (default right), adopting ADF 6.6's CloseButtonPosition. (See ADF 6.6 → "Viewer close button".)

Document-list resizing, persistence and drag-drop columns

ACA adopted the ADF document-list column capabilities added across 6.5.2–6.7.x:

• Resizable lists — all document lists set [isResizingEnabled]="true" and [blurOnResize]="false".
• Per-column opt-out — columns are resizable by default in newer ADF, so ACA marks the thumbnail/icon columns "resizable": false (new resizable field in extension.schema.json).
• Persistence & drag-drop — column size / visibility / order are persisted (via ADF's setColumns* inputs and columns*Changed outputs) and columns can be reordered by drag-drop ("draggable": true). Stable id="app.*" values were added to every data-column.

Theming

• Internal Angular Material CSS classes — ACA removed most .mat-* / .cdk-* selector overrides in favour of ACA-owned aca-* / adf-* classes (preparation for ADF's Material MDC migration). If your fork overrides ACA styles via Material internals, re-audit them.
• Theme reference variables — hardcoded/removed theme references were replaced with dynamic --theme-* tokens (e.g. --theme-secondary-text, --theme-card-background-color, --theme-sidenav-active-text-color). (See ADF 6.6 → "Theme reference variables".)

Disabling tags and categories

ACA can now disable the tags and categories features via app.config.json (default true), using ADF's TagService.areTagsEnabled() / CategoryService.areCategoriesEnabled().

Config-key rename in 4.4.1: the ACA keys were introduced in 4.4.0 as plugins.tags / plugins.categories, then renamed in 4.4.1 to plugins.tagsEnabled / plugins.categoriesEnabled (ACS-6924) to avoid a naming conflict with ADF's own plugin keys. Use the new *Enabled names in a custom app.config.json (or via the APP_CONFIG_PLUGIN_TAGS / APP_CONFIG_PLUGIN_CATEGORIES env vars) — the ACA rule functions areTagsEnabled / areCategoriesEnabled read the renamed keys.

Breaking changes

ACA's published library API is unchanged in this release — the public-api.ts of every @alfresco/aca-shared and @alfresco/aca-content entry point is byte-identical between 4.3.0 and 4.4.0 (no exports removed, renamed or newly deprecated). The breaking changes are at the configuration, build and dependency level.

Configuration changes

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

• oauth2.implicitFlow: true → implicitFlow: false + codeFlow: true (PKCE).
• The date-range-advanced search selector was removed — use date-range.
• Viewer extensions are now keyed under an extensions block (by fileExtension) instead of the old content key in app.extensions.json.

Nx 17 workspace migration

The workspace moved to Nx 17 (@nx/* / nx 17.x). nx.json and the cache configuration were rewritten. If you maintain a fork with custom Nx targets, run the Nx 17 migrations.

adf-testing dependency dropped

@alfresco/adf-testing was removed from ACA's dependencies. If your tests imported it via ACA, add it to your own devDependencies.

E2E selector changes

The viewer close-button e2e locator changed from button[data-automation-id="adf-toolbar-back"] to button.adf-viewer-close-button (following ADF's adf-toolbar-back → adf-toolbar-left-back id change). Update any e2e selectors targeting the old value.

New components and features

• Search highlighting — matched terms in search results are highlighted (aca-highlight), configurable via the results row highlight settings.
• Configurable / persistent / draggable document-list columns — see Document-list resizing, persistence and drag-drop columns; the search-results list is now configurable with the same column model.
• Dynamic Tags column — the search-results tags column and its getTags call are now gated by tagsService.areTagsEnabled() and driven by app.config.json.
• Manage permissions from the viewer — the Manage permissions action can now be triggered from inside a file preview.
• AppExtensionService.updateSidebarActions() — a new (additive) public method that publishes features.sidebar.toolbar content actions; new areTagsEnabled / areCategoriesEnabled rule functions are exported from @alfresco/aca-shared/rules.

Behavioural changes

Area	Change
Smart folders	Edit aspects, Manage rules and Manage permissions are now hidden for smart folders, and Manage permissions is hidden on multi-selection.
Records	Edit Offline and Upload New Version are hidden for declared records.
Storage	The local-storage prefix is set from the current username on login (via the unified getUsername() accessor), fixing an ADW prefix issue.
Libraries	After deleting a library from the Manage Members view, the user is redirected to the libraries page.
Search input	Clicking a search input that already contains text now lets you edit the term.
Viewer	View details is active in the expanded view.