mirror of
https://github.com/Alfresco/alfresco-content-app.git
synced 2026-09-09 18:02:54 +00:00
[ACS-12451] Add missing upgrade guides in ACA (#5345)
* [ACS-12451] Add missing upgrade guides in ACA * [ACS-12451] CR fix
This commit is contained in:
Michal Kinas
@@ -0,0 +1,190 @@
|
||||
---
|
||||
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](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade64-652.md)
|
||||
- [ADF — Upgrading from v6.5.2 to v6.6.0](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade652-66.md)
|
||||
- [ADF — Upgrading from v6.6.0 to v6.7.1](https://github.com/Alfresco/alfresco-ng2-components/blob/develop/docs/upgrade-guide/upgrade66-671.md)
|
||||
|
||||
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](#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](#library-updates)
|
||||
- [Aligning with ADF 6.5 / 6.6 / 6.7](#aligning-with-adf-65--66--67)
|
||||
- [Authentication — PKCE / code flow](#authentication--pkce--code-flow)
|
||||
- [Search — Elasticsearch, date range and highlighting](#search--elasticsearch-date-range-and-highlighting)
|
||||
- [Content metadata read-only model](#content-metadata-read-only-model)
|
||||
- [Viewer close-button position](#viewer-close-button-position)
|
||||
- [Document-list resizing, persistence and drag-drop columns](#document-list-resizing-persistence-and-drag-drop-columns)
|
||||
- [Theming](#theming)
|
||||
- [Disabling tags and categories](#disabling-tags-and-categories)
|
||||
- [Breaking changes](#breaking-changes)
|
||||
- [Configuration changes](#configuration-changes)
|
||||
- [Nx 17 workspace migration](#nx-17-workspace-migration)
|
||||
- [adf-testing dependency dropped](#adf-testing-dependency-dropped)
|
||||
- [E2E selector changes](#e2e-selector-changes)
|
||||
- [New components and features](#new-components-and-features)
|
||||
- [Behavioural changes](#behavioural-changes)
|
||||
|
||||
## Library updates
|
||||
|
||||
Update the `package.json` file with the latest library versions:
|
||||
|
||||
```json
|
||||
{
|
||||
"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](#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. |
|
||||
Reference in New Issue
Block a user