inteligr8/alfresco-ng2-components
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-ng2-components.git synced 2026-09-09 18:03:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

[ACS-12451] Add missing ADF upgrade guides (#12138)

Browse Source 
* [ACS-12451] Add missing ADF upgrade guides

* [ACS-12451] CR fix

* [ACS-12451] CR fixes
This commit is contained in:
Michal Kinas
2026-08-11 11:49:30 +02:00
committed by GitHub
parent 84e247c85f
commit 5712f2742c
21 changed files with 4103 additions and 502 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/upgrade-guide/README.md
+17
View File
@@ -6,6 +6,23 @@ Title: Upgrade guides
Below are links to the upgrade guides notes for all released versions of ADF back to v2.6.0
- [Upgrading from ADF v8.5 to v9.0](upgrade850-900.md)
- [Upgrading from ADF v8.4 to v8.5](upgrade841-850.md)
- [Upgrading from ADF v8.3.1 to v8.4.1](upgrade831-841.md)
- [Upgrading from ADF v8.2.1 to v8.3.1](upgrade821-831.md)
- [Upgrading from ADF v8.1.1 to v8.2.1](upgrade811-821.md)
- [Upgrading from ADF v8.0 to v8.1.1](upgrade80-811.md)
- [Upgrading from ADF v7.0 to v8.0](upgrade70-80.md)
- [Upgrading from ADF v6.9 to v7.0](upgrade69-70.md)
- [Upgrading from ADF v6.8 to v6.9](upgrade68-69.md)
- [Upgrading from ADF v6.7.1 to v6.8.0](upgrade671-68.md)
- [Upgrading from ADF v6.6.0 to v6.7.1](upgrade66-671.md)
- [Upgrading from ADF v6.5.2 to v6.6.0](upgrade652-66.md)
- [Upgrading from ADF v6.4 to v6.5.2](upgrade64-652.md)
- [Upgrading from ADF v6.3 to v6.4](upgrade63-64.md)
- [Upgrading from ADF v6.2 to v6.3](upgrade62-63.md)
- [Upgrading from ADF v6.1 to v6.2](upgrade61-62.md)
- [Upgrading from ADF v6.0 to v6.1](upgrade60-61.md)
- [Upgrading from ADF v5.0 to v6.0](upgrade50-60.md)
- [Upgrading from ADF v4.11 to v5.0](upgrade411-50.md)
- [Upgrading from ADF v4.6 to v4.7](upgrade46-47.md)
docs/upgrade-guide/upgrade-6.0.0-6.9.0.md
-155
View File
@@ -1,155 +0,0 @@
---
Title: Upgrading from ADF v5.0 to v6.0
---
# Upgrading from ADF v6.0 to v6.9
This guide provides instructions on how to upgrade your v6.0.0 ADF projects to v6.9.0.
## Before you begin
Always perform upgrades on "clean" project state, backup your changes or make a project backup.
```shell
# Recommended clean up
nx reset && rm -rf .angular .nx dist node_modules nxcache tmp
```
## .env file
If you are using .env file, make sure to update it with the latest configuration:
```yaml
APP_CONFIG_OAUTH2_HOST="<oauth2_host>"
APP_CONFIG_ENABLE_MOBILE_APP_SWITCH=false
APP_CONFIG_PLUGIN_AOS=true
APP_CONFIG_PLUGIN_CONTENT_SERVICE=true
APP_CONFIG_PLUGIN_FOLDER_RULES=true
APP_CONFIG_ENABLE_DOWNLOAD_PROMPT=false
APP_CONFIG_ENABLE_DOWNLOAD_PROMPT_REMINDERS=false
APP_CONFIG_DOWNLOAD_PROMPT_DELAY=30
APP_CONFIG_DOWNLOAD_PROMPT_REMINDER_DELAY=30
APP_CONFIG_ENABLE_FILE_AUTO_DOWNLOAD=false
APP_CONFIG_FILE_AUTO_DOWNLOAD_SIZE_THRESHOLD_IN_MB=10
```
> [!IMPORTANT]
> The configuration values are for migration purposes only.
> Please refer to the documentation for more details on the configuration settings and values.
## Library versions
Update the `package.json` file with the latest library versions:
- Angular: 14.1.3
- Alfresco Component Libraries: 6.9.0
- Alfresco JS-API: 7.6.1
```json
{
"dependencies": {
"@alfresco/adf-core": "6.9.0",
"@alfresco/adf-content-services": "6.9.0",
"@alfresco/adf-process-services-cloud": "6.9.0",
"@alfresco/adf-insights": "6.9.0",
"@alfresco/js-api": "7.6.1"
}
}
```
> [!NOTE]
> You can also refer to the Alfresco Content Application [4.4.1 release](https://github.com/Alfresco/alfresco-content-app/blob/4.4.1/package.json) for the latest version of the libraries.
### Remove old dependencies
```json
{
"dependencies": {
"@angular/material-moment-adapter": "14.1.3",
"@mat-datetimepicker/moment": "^9.0.68",
"moment": "^2.29.4",
"moment-es6": "1.0.0",
"@angular/flex-layout": "^14.0.0-beta.40"
}
}
```
### Add extra dependencies
```json
{
"dependencies": {
"@angular/material-date-fns-adapter": "14.1.3",
"date-fns": "^2.30.0"
}
}
```
Reinstall your dependencies and make initial build
```sh
npm i --legacy-peer-deps
npm run build
```
### Update code
If you are using the `@alfresco/js-api` library, make sure to update the code according to the latest version:
| Before | After |
|------------------------|--------------------|
| MinimalNodeEntity | NodeEntry |
| SiteBody | SiteBodyCreate |
| MinimalNodeEntryEntity | Node |
| MinimalNode | Node |
| PathInfoEntity | PathInfo |
| SiteBody | SiteBodyCreate |
| FavoriteBody | FavoriteBodyCreate |
| PathElementEntity | PathElement |
#### NullInjectorError: No provider for RedirectAuthService!
If you are facing the `NullInjectorError: No provider for RedirectAuthService!` error, make sure to add the `AuthModule` to the `AppModule`:
```typescript
import { AuthModule } from '@alfresco/adf-core';
@NgModule({
imports: [
// other imports
AuthModule.forRoot({ useHash: true })
]
})
export class AppModule {}
```
For the development purposes, you may want to update the `app.config.json`:
```json5
{
"oauth2": {
// other configurations
"skipIssuerCheck": true,
"strictDiscoveryDocumentValidation": false
}
}
```
### Document List component
For document list components, remove the `display` property if used:
```html
[display]="documentDisplayMode$ | async"
```
## Final steps
After you have updated the code, make sure to test your application thoroughly to ensure that everything is working as expected.
You can build and run your application using the following commands:
```sh
npm run build
npm start content-ce
```
docs/upgrade-guide/upgrade-6.9.0-7.0.0.md
-183
View File
@@ -1,183 +0,0 @@
---
Title: Upgrading from ADF v6.9 to v7.0
---
# Upgrading from ADF v6.9 to v7.0
This guide provides instructions on how to upgrade your v6.9.0 ADF projects to v7.0.0.
## Before you begin
Always perform upgrades on "clean" project state, backup your changes or make a project backup.
```shell
# Recommended clean up
nx reset && rm -rf .angular .nx dist node_modules nxcache tmp
```
## Libraries updates
Node version used is now 20.18.1.
### Breaking changes with libraries:
- Angular: 17.1.3
- Angular Material: 17.1.2
- Typescript: 5.3.3
- RXJS: 7.8.1
- NX: 20.0.0
Angular updates can be done with "Update Guide" from Angular documentation.
### Added libraries:
- eslint-plugin-storybook
- jasmine-marbles
- @editorjs/paragraph
- editorjs-text-alignment-blocktune
- graphql-ws
### Deleted libraries:
- protractor
- selenium-webdriver
- webdriver-manager
- shx
- monaco-editor
- ngx-monaco-editor-v2
- @types/selenium-webdriver
- protractor-retry-angular-cli
- protractor-screenshoter-plugin
- protractor-smartrunner
Reinstall your dependencies and make initial build:
```shell
npm i
npm run build
```
Review your applications as some styles and classes of Angular Material components might have changed.
## Demo-Shell and e2e
Demo shell and its e2e tests have been deleted.
## Material module
Material module is deprecated and will be removed in a future release. Please import components and modules independently.
## Standalone components
Most components have been changed to "standalone" and their modules have been deleted. Please import components directly.
| Deleted modules |
|--------------------------------|
| AttachmentModule |
| AppsListModule |
| TaskListModule |
| ProcessListModule |
| ProcessUserInfoModule |
| TaskCommentsModule |
| ProcessCommentsModule |
| PeopleModule |
| DynamicTableModule |
| ContentWidgetModule |
| AnalyticsProcessModule |
| DiagramsModule |
| ButtonsMenuModule |
| SitesDropdownModule |
| DataColumnModule |
| ContentUserInfoModule |
| AppCardViewModule |
| AppCloudSharedModule |
| FileViewModule |
| AppProcessListModule |
| FolderDirectiveModule |
| ContentTypeModule |
| SortingPickerModule |
| ProcessServicesCloudPipeModule |
| StartTaskCloudModule |
| ProcessDirectiveModule |
| StartProcessCloudModule |
| TaskDirectiveModule |
## Removed components, directives and pipes
| Deleted components, directives and pipes |
|------------------------------------------|
| IsIncludedPipe |
| TabLabelsPipe |
| BooleanPipe |
| FilterOutArrayObjectsByPropPipe |
| LocalizedRolePipe |
| MimeTypeIconPipe |
| FilterStringPipe |
| ProcessNameCloudPipe |
| FormStylePipe |
| CancelProcessDirective |
| MomentDateTimePipe |
| MomentDatePipe |
## A11y changes
Components have been reviewed and changed to fix most important issues with accessibility. Please test your application thoroughly to ensure that everything is working as expected, as some components have changed their structure, html roles or attributes.
| Components changed | Description of changes |
|--------------------------------|----------------------------------------------------------------------|
| Tooltips | Tooltips have been changed from Angular Material to standard tooltip |
| Search Page and Search Filters | mat-chip-option replaced with mat-chip |
| Columns Selector | role attribute changes |
| DataTable | role attribute changes |
| Aspect List | structure of html changed |
## Guards
All guards have been converted to functional guards (using the new Angular functional route guard pattern). Please review any custom guards in your application and adapt them to the functional pattern as needed.
Example of converting a class-based guard to a functional guard:
```typescript
// Before (class-based)
@Injectable({
providedIn: 'root'
})
export class AuthGuard implements CanActivate {
constructor(private authService: AuthService, private router: Router) {}
canActivate() {
if (this.authService.isLoggedIn()) {
return true;
}
this.router.navigate(['/login']);
return false;
}
}
// After (functional)
export const authGuard = () => {
const authService = inject(AuthService);
const router = inject(Router);
if (authService.isLoggedIn()) {
return true;
}
return router.parseUrl('/login');
};
```
## Model and interface changes
Some models and interfaces have changed:
| Before | After | Notes |
|-------------------------------|-----------------------|------------------------------|
| TaskDetailsModel | TaskRepresentation | Rename all instances |
| IdentityUserFilterInterface | Removed | Use type definitions instead |
| IdentityUserServiceInterface | Removed | Use type definitions instead |
| TaskCloudServiceInterface | Removed | Use type definitions instead |
## Final steps
After you have updated the code, make sure to test your application thoroughly to ensure that everything is working as expected. Pay special attention to areas that use the renamed models or interfaces, and make sure all components are properly imported as standalone components.
If you encounter any issues during the upgrade process, refer to the Angular update guide or the ADF community for assistance.
docs/upgrade-guide/upgrade-7.0.0-8.0.0.md
-164
View File
@@ -1,164 +0,0 @@
---
Title: Upgrading from ADF v7.0 to v8.0
---
# Upgrading from ADF v7.0 to v8.0
This guide provides instructions for upgrading your v7.0.0 ADF projects to v8.0.0.
## Before you begin
Always perform upgrades on a "clean" project state. Back up your changes or create a full project backup before proceeding.
```shell
# Recommended clean up
nx reset && rm -rf .angular .nx dist node_modules nxcache tmp
```
## Libraries
Update your dependencies to the versions introduced in the 8.0.0 release:
```json
{
"dependencies": {
"@alfresco/adf-core": "8.0.0",
"@alfresco/adf-content-services": "8.0.0",
"@alfresco/adf-process-services-cloud": "8.0.0",
"@alfresco/adf-insights": "8.0.0",
"@alfresco/adf-extensions": "8.0.0",
"@alfresco/adf-cli": "8.0.0",
"@alfresco/eslint-plugin-eslint-angular": "8.0.0",
"@alfresco/adf-testing": "8.0.0",
"@alfresco/js-api": "9.0.0"
}
}
```
Currently used Node version: 22.14.0.
### Breaking changes
Major version updates have been applied to the following core libraries:
- Angular: 19.2.6
- Angular Material: 19.2.9
- Typescript: 5.8.2
> Details on Angular update can be found in *Update Guide* from Angular documentation.
### Added libraries
```json
{
"dependencies": {
"node-fetch": "^3.3.2"
},
"devDependencies": {
"resize-observer-polyfill": "^1.5.1",
"webdriver-manager": "12.1.9"
}
}
```
### Deleted libraries
```json
{
"devDependencies": {
"mini-css-extract-plugin": "X.X.X",
"css-loader": "X.X.X"
}
}
```
Reinstall your dependencies and perform an initial build:
```shell
npm i
npm run build
```
Review your applications as some styles and classes of Angular Material components might have changed.
## Deprecations
The following table lists deprecated features and modules that will be removed in upcoming releases. Consider replacing them as soon as you update ADF to minimize future technical debt.
| Name | Notes |
|-------------------------------|-----------------------------------------------------------------------------------------------|
| Custom Theme | Refer to [Custom Theme documentation](../../lib/core/custom-theme/README.md) |
| ShellModule | Refer to [Shell documentation](../../lib/core/shell/README.md) |
| FormBaseModule | Use standalone components instead. |
| CoreTestingModule | Use standalone components instead. |
| ProcessServicesCloudModule | Refer to [ProcessServicesCloudModule replacement](#processservicescloudmodule-replacement) |
### ProcessServicesCloudModule replacement
To replace this module, import the standalone components directly or use the following provider API to replicate its behavior:
```typescript
providers: [
provideTranslations('adf-process-services-cloud', 'assets/adf-process-services-cloud'),
provideCloudPreferences(),
provideCloudFormRenderer(),
{ provide: TASK_LIST_CLOUD_TOKEN, useClass: TaskListCloudService }
]
```
## New features and APIs
You can start using the new features and APIs introduced in the 8.0.0 release.
### XMLHttpRequest.withCredentials
Support for disabling the `withCredentials` property in `app.config.json` for identity providers that disallow credentials has been introduced. You can configure it as shown below:
```json
{
"auth": {
"withCredentials": false
}
}
```
### provideShell
The new provideShell API for providing the main application layout can replace the `withRoutes(routes: Routes | AppShellRoutesConfig)` method, as shown below.
```typescript
import { provideShell } from '@alfresco/adf-core/shell';
provideShell(
{
routes: [],
appService: AppService,
authGuard: AuthGuard,
navBar: {
minWidth: 0,
maxWidth: 100
}
}
)
```
### provideI18N
The new `provideI18N` API for providing translation can replace `provideTranslations('app', 'assets')` method, as shown below.
```typescript
import { provideI18N } from '@alfresco/adf-core';
provideI18N(
{
defaultLanguage: "en", // optional, defaults to "en"
assets: [['en', '/assets/i18n/en.json'], ['fr', '/assets/i18n/fr.json']]
}
)
```
## Final steps
After updating your code, thoroughly test your application to ensure everything works as expected.
If you encounter any issues during the upgrade process, refer to the Angular update guide or seek assistance from the ADF community.
docs/upgrade-guide/upgrade60-61.md
+147
View File
@@ -0,0 +1,147 @@
---
Title: Upgrading from ADF v6.0 to v6.1
---
# Upgrading from ADF v6.0 to v6.1
This guide provides instructions on how to upgrade your v6.0.0 ADF projects to v6.1.0.
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup.
Do not skip this task if you want your application to be updated to the most recent version of ADF.
Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates.
After the upgrade, check the other sections below to see if there are any changes affecting your project.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Angular Flex-Layout removed](#angular-flex-layout-removed)
- [`@mat-datetimepicker` peer dependency major bump](#mat-datetimepicker-peer-dependency-major-bump)
- [`@alfresco/js-api` and ADF peers use a caret range](#alfrescojs-api-and-adf-peers-use-a-caret-range)
- [Third-party libraries](#third-party-libraries)
- [New components and features](#new-components-and-features)
- [Display Rich Text form widget (cloud)](#display-rich-text-form-widget-cloud)
- [Configurable header text color](#configurable-header-text-color)
- [Behavioural changes](#behavioural-changes)
## Library updates
Update the `package.json` file with the latest library versions:
```json
{
"dependencies": {
"@alfresco/adf-core": "6.1.0",
"@alfresco/adf-content-services": "6.1.0",
"@alfresco/adf-process-services": "6.1.0",
"@alfresco/adf-process-services-cloud": "6.1.0",
"@alfresco/adf-insights": "6.1.0",
"@alfresco/adf-extensions": "6.1.0",
"@alfresco/js-api": ">=6.1.0"
}
}
```
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`.
Reinstall your dependencies
```sh
npm install
```
**Note:** the ADF libraries now depend on `@alfresco/js-api` (and on each other) through a `^6.1.0` caret range,
where `6.0.0` used an exact pin. Make sure your application resolves a JS-API build of `6.1.0` or later.
**Tooling note:** the repository's pinned Node version (`.nvmrc`) moved from **14** to **18**, so the libraries are
now built and tested on Node 18. Align your build/CI Node version accordingly.
## Breaking changes
The ADF project follows the [semver](https://semver.org/) conventions. `6.1.0` is a minor release, so there are
no removed or renamed public exports; the items below are dependency-level changes that can still affect your build.
### Angular Flex-Layout removed
`@angular/flex-layout` (`^14.0.0-beta.40`) has been **removed** as a dependency from every ADF library
(`@alfresco/adf-core`, `@alfresco/adf-content-services`, `@alfresco/adf-process-services`,
`@alfresco/adf-process-services-cloud` and `@alfresco/adf-insights`). All internal usage of `fxLayout`,
`fxFlex`, `fxHide` and `FlexLayoutModule` was removed from the component templates and modules.
ADF no longer re-exports `FlexLayoutModule`, and it was never part of the public API barrels, so this does not
break any ADF import. However, if your own application relied on ADF transitively installing
`@angular/flex-layout` and you use flex-layout directives in your **own** templates, add the dependency to your
application directly:
```sh
npm install @angular/flex-layout@^14.0.0-beta.40
```
### `@mat-datetimepicker` peer dependency major bump
`@alfresco/adf-core` bumped its `@mat-datetimepicker` peer dependencies by a major version:
| Peer dependency | Before | After |
| ---------------------------- | --------- | --------- |
| `@mat-datetimepicker/core` | `^9.0.68` | `^10.1.1` |
| `@mat-datetimepicker/moment` | `^9.0.68` | `^10.1.1` |
If your application pins these packages, update them to the `^10.1.1` range so your installed version matches
the one ADF is built against.
### `@alfresco/js-api` and ADF peers use a caret range
The peer dependencies inside the ADF libraries changed from exact pins (`6.0.0`) to caret ranges (`^6.1.0`). This
applies to `@alfresco/js-api` and to the inter-library ADF peers (for example `@alfresco/adf-core` and
`@alfresco/adf-extensions`). Ensure your lockfile resolves compatible `6.x` builds; a stale exact pin of
`@alfresco/js-api@6.0.0` should be updated to `>=6.1.0`.
## Third-party libraries
| Name | Version | Notes |
| ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `@angular/flex-layout` | removed | No longer a dependency of any ADF library (see [Angular Flex-Layout removed](#angular-flex-layout-removed)). |
| `@mat-datetimepicker/core` | `^10.1.1` | Major bump from `^9.0.68` (peer of `@alfresco/adf-core`). |
| `@mat-datetimepicker/moment` | `^10.1.1` | Major bump from `^9.0.68` (peer of `@alfresco/adf-core`). |
## New components and features
### Display Rich Text form widget (cloud)
A new form widget, `DisplayRichTextWidgetComponent` (selector `display-rich-text`), is now declared and exported
by `FormCloudModule` in `@alfresco/adf-process-services-cloud`. Previously the widget class existed but was not
wired into the module, so it could not be used. It renders read-only rich-text content within a cloud form.
### Configurable header text color
`[HeaderLayoutComponent](../core/components/header.component.md)` (selector `adf-layout-header`) now reads a new
`headerTextColor` key from `app.config.json` and, when present, applies it to the
`--theme-header-text-color` CSS custom property (which defaults to the primary palette's contrast color).
```json
{
"headerTextColor": "#ffffff"
}
```
## Behavioural changes
| Area | Change |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Tree component](../content-services/components/tree.component.md) | Pagination is now emitted only when the top-level entries change, and an expand/collapse regression was fixed. |
| Form save button (cloud) | On clicking the system **save** outcome the save button is now disabled, and it is re-enabled when a form field value changes. |
| Task / process lists (cloud) | Changing only column visibility no longer triggers a reload of the task or process list. |
| Task lists (cloud) | The loading spinner no longer disappears before the list has finished loading. |
| Task details (cloud) | The loading spinner alignment after opening task details was corrected. |
| [Tags creator](../content-services/components/tags-creator.component.md) | The "required field" message is no longer shown after discarding changes; the first tag position and an extra scrollbar (shown while the spinner is visible) were also corrected. |
| [Image viewer](../core/components/viewer.component.md) | Navigation between images was fixed, and image display in full-screen mode was corrected. |
| User roles fetch | `UserAccessService` now appends an `appkey` query parameter (read from the `application.key` app-config value) when fetching identity roles, if that value is configured. |
| Search facets | Facet, filter and widget chips had markup/icon adjustments in the facets section. |
| [Card view select item](../core/components/card-view.component.md) | The select input's position in the edit template was changed. |
| Start process / task outcomes | Outcome button positioning in the start-process form and the attach-file button style were corrected. |
| Group cloud | The identity group validation error message was replaced with a shorter version. |
| Theme | A task-filter color was changed to use the accent-contrast color. |
docs/upgrade-guide/upgrade61-62.md
+380
View File
@@ -0,0 +1,380 @@
---
## Title: Upgrading from ADF v6.1 to v6.2
# Upgrading from ADF v6.1 to v6.2
This guide provides instructions on how to upgrade your v6.1.0 ADF projects to v6.2.0.
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup.
Do not skip this task if you want your application to be updated to the most recent version of ADF.
Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates.
After the upgrade, check the other sections below to see if there are any changes affecting your project.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Dependency injection refactor (](#dependency-injection-refactor-inject)`inject()`[)](#dependency-injection-refactor-inject)
- [SharedLinksApiService.createSharedLinks](#sharedlinksapiservicecreatesharedlinks)
- [Share dialog: expiry is now date-only](#share-dialog-expiry-is-now-date-only)
- [Route-aware filter selection](#route-aware-filter-selection)
- [Removed items](#removed-items)
- [Renamed items](#renamed-items)
- [CSS class renames](#css-class-renames)
- [Encapsulation changes](#encapsulation-changes)
- [SCSS reference variables](#scss-reference-variables)
- [Third-party libraries](#third-party-libraries)
- [New components and features](#new-components-and-features)
- [Logical search filter](#logical-search-filter)
- [Advanced search: autocomplete chips](#advanced-search-autocomplete-chips)
- [Header customization](#header-customization)
- [Icon font set](#icon-font-set)
- [OAuth2 configuration handling](#oauth2-configuration-handling)
- [Behavioural changes](#behavioural-changes)
- [Theme changes](#theme-changes)
## Library updates
Update the `package.json` file with the latest library versions:
```json
{
"dependencies": {
"@alfresco/adf-core": "6.2.0",
"@alfresco/adf-content-services": "6.2.0",
"@alfresco/adf-process-services": "6.2.0",
"@alfresco/adf-process-services-cloud": "6.2.0",
"@alfresco/adf-insights": "6.2.0",
"@alfresco/adf-extensions": "6.2.0",
"@alfresco/js-api": ">=6.2.0"
}
}
```
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`.
Reinstall your dependencies
```sh
npm install
```
**Note:** the ADF libraries now depend on `@alfresco/js-api` with a `>=6.2.0` range (previously a `^6.1.0` caret range). Make sure your application resolves a JS-API build of `6.2.0` or later.
## Breaking changes
### Dependency injection refactor (`inject()`)
A large number of exported services, components and abstract base classes were refactored
to use Angular's `inject()` function instead of constructor-parameter injection.
As a result **their public constructor signatures changed** — most now take no arguments
(or a reduced set).
This affects you only if you **subclass** one of these classes and call `super(...)`,
or if you **instantiate them directly** (for example, `new AuthenticationService(...)` in a unit test).
| Library | Affected classes |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@alfresco/adf-core` | `[BaseAuthenticationService](../../lib/core/src/lib/services/base-authentication.service.ts)`, `[AuthenticationService](../core/services/authentication.service.md)`, `[OIDCAuthenticationService](../../lib/core/src/lib/auth/oidc/oidc-authentication.service.ts)`, `[AuthGuardBase](../../lib/core/src/lib/auth/guard/auth-guard-base.ts)`, `AuthGuard`, `AuthGuardBpm`, `AuthGuardEcm`, `BaseCardView`, `[CardViewTextItemComponent](../../lib/core/src/lib/card-view/components/card-view-textitem/card-view-textitem.component.ts)`, `CardViewDateItemComponent`, `CardViewSelectItemComponent`, `CardViewArrayItemComponent`, `CardViewBoolItemComponent`, `CardViewKeyValuePairsItemComponent`, `CardViewMapItemComponent` |
| `@alfresco/adf-content-services` | `UploadBase`, `[UploadButtonComponent](../content-services/components/upload-button.component.md)`, `[UploadDragAreaComponent](../content-services/components/upload-drag-area.component.md)` |
| `@alfresco/adf-process-services` | `[FormComponent](../process-services/components/form.component.md)`, `[StartFormComponent](../core/components/start-form.component.md)` |
| `@alfresco/adf-process-services-cloud` | `BaseCloudService`, `FormCloudService`, `FormDefinitionSelectorCloudService`, `ProcessListCloudService`, `ProcessTaskListCloudService`, `ProcessCloudService`, `StartProcessCloudService`, `NotificationCloudService`, `UserPreferenceCloudService`, `StartTaskCloudService`, `TaskCloudService`, `TaskFilterCloudService`, `ServiceTaskListCloudService`, `TaskListCloudService` |
If you extend one of these classes, drop the old positional arguments from your `super(...)` call.
Before:
```ts
export class MyUpload extends UploadButtonComponent {
constructor(uploadService, contentService, nodesApiService, translationService, logService, ngZone) {
super(uploadService, contentService, nodesApiService, translationService, logService, ngZone);
}
}
```
After:
```ts
export class MyUpload extends UploadButtonComponent {
constructor() {
super();
}
}
```
If you were instantiating these classes manually in tests, note that `inject()` only works
inside an Angular injection context. Use `TestBed` and retrieve the instance from the injector
instead of calling `new`.
**Note:** `BaseCloudService` now injects `[LogService](../core/services/log.service.md)` itself,
so `this.logService` is available to every cloud-service subclass. Subclasses that previously
declared their own `logService` no longer need to.
### SharedLinksApiService.createSharedLinks
A new middle parameter was added to `[createSharedLinks](../core/services/shared-links-api.service.md)`
so that expiry settings can be applied to the shared link itself.
Before:
```ts
createSharedLinks(nodeId: string, options: any = {}): Observable<SharedLinkEntry>
```
After:
```ts
createSharedLinks(nodeId: string, sharedLinkWithExpirySettings?: SharedLinkBodyCreate, options: any = {}): Observable<SharedLinkEntry>
```
If you call this method with positional arguments, update the call:
```ts
// Before
this.sharedLinksApiService.createSharedLinks(nodeId, options);
// After
this.sharedLinksApiService.createSharedLinks(nodeId, undefined, options);
```
### Share dialog: expiry is now date-only
The share-link expiry control in `[ShareDialogComponent](../../lib/content-services/src/lib/content-node-share/content-node-share.dialog.ts)`
changed from a date-**time** picker to a **date-only** picker, and the date library moved from
`moment` to `date-fns`.
- The `sharedLinkDateTimePickerType` app-config key is **no longer read**. Setting it has no effect; the picker is date-only.
- Methods that previously accepted/returned `moment.Moment` now use the native `Date` type (for example `onTimeChanged(date: Date)`). Update any override accordingly.
- The template handler `onDatetimepickerClosed` was renamed to `onDatePickerClosed`, and the `#dateTimePickerInput` template reference to `#datePickerInput` — this affects you only if you override the dialog template.
### Route-aware filter selection
`[ProcessFiltersComponent](../process-services/components/process-filters.component.md)` and
`[TaskFiltersComponent](../process-services/components/task-filters.component.md)` (in `@alfresco/adf-process-services`)
now inject `Router` (plus `Location` / `ActivatedRoute` respectively) to highlight the active
filter based on the current route. If you instantiate these components in a test, provide routing
(for example, import `RouterTestingModule`).
## Removed items
| Item | Package | Notes |
| ------------------------------------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NotificationIconPipe` (`notificationIcon`) | `@alfresco/adf-core` | Internal, non-exported pipe. Icon resolution now happens in the notification factory. Only affects unsupported use of the deep `notifications/pipes/notification-icon.pipe` path. |
| `mockAuthConfigImplicitFlow`, `mockAuthConfigCodeFlow` | `@alfresco/adf-core` | Test mocks removed. Inline your own equivalents if your tests imported them. |
| `sharedLinkDateTimePickerType` (app-config key) | `app.config.json` | No longer read — the share-link expiry picker is date-only. |
## Renamed items
### CSS class renames
If you target these selectors from your own stylesheets, update them:
| Component | Before | After |
| -------------------------------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------- |
| [About server settings](../core/components/about.component.md) | `.adf-github-link-container` | `.adf-about-server-settings` (+ `.adf-about-server-settings__card`) |
| [Edit task filter](../process-services-cloud/components/edit-task-filter-cloud.component.md) | `.adf-edit-task-filter-description` | `.adf-edit-task-filter-header__description` |
| [Edit process filter](../process-services-cloud/components/edit-process-filter-cloud.component.md) | `.adf-edit-process-filter-description` | `.adf-edit-process-filter-header__description` |
### Encapsulation changes
`AboutServerSettingsComponent` and `PackageListComponent` **no longer use** `ViewEncapsulation.None`.
Global CSS overrides that previously "bled into" these components will no longer apply — theme them
through the new [CSS custom properties](#theme-changes) instead.
### SCSS reference variables
If you import ADF's `[_reference-variables.scss](../../lib/core/src/lib/styles/_reference-variables.scss)`
directly, note that several `$adf-ref-*` primitives were consolidated/renamed. The public `--adf-*`
CSS custom property names are unchanged — prefer overriding those instead.
| Before | After |
| ---------------------------------------------------------------- | ------------------------------- |
| `$adf-ref-edit-task-and-service-filter-header-title-color` | `$adf-ref-title-color` |
| `$adf-ref-edit-task-and-service-filter-header-description-color` | `$adf-ref-description-color` |
| `$adf-ref-edit-task-and-service-filter-header-height` | `$adf-ref-height-48` |
| `$adf-ref-card-border-radius` | `$adf-ref-card-border-radius-0` |
## Third-party libraries
| Name | Version | Notes |
| ---------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `material-icons` | `^1.13.8` | The bundled Material Icons font and its `material-icons.css` were removed from the build in favour of the published `[material-icons](https://www.npmjs.com/package/material-icons)` package. If your app relied on ADF bundling the font, provide it yourself. |
| `date-fns` | `^2.30.0` | New dependency (replaces `moment` in the share dialog). |
## New components and features
| Name | Package | Description |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ----------------------------------------------------- |
| `[SearchLogicalFilterComponent](../content-services/components/search-logical-filter.component.md)` | `@alfresco/adf-content-services` | `logical-filter` search widget (AND / OR / AND-NOT). |
| `[SearchChipInputComponent](../content-services/components/search-chip-input.component.md)` | `@alfresco/adf-content-services` | Reusable chip text-entry field. |
| `[SearchFilterAutocompleteChipsComponent](../content-services/components/search-filter-autocomplete-chips.component.md)` | `@alfresco/adf-content-services` | `autocomplete-chips` search widget (Tags / Location). |
| `[SearchChipAutocompleteInputComponent](../content-services/components/search-chip-autocomplete-input.component.md)` | `@alfresco/adf-content-services` | Chip input with `mat-autocomplete`. |
| `[IsIncludedPipe](../content-services/pipes/is-included.pipe.md)` (`adfIsIncluded`) | `@alfresco/adf-content-services` | Returns whether a value is contained in an array. |
### Logical search filter
A new search widget, `logical-filter`, lets users build AND / OR / AND-NOT queries from three
phrase inputs. Enable it by referencing the `logical-filter` widget type in your search configuration:
```json
{
"search": {
"categories": [
{
"id": "logic",
"name": "Query",
"enabled": true,
"component": {
"selector": "logical-filter",
"settings": { "field": "cm:name,cm:title" }
}
}
]
}
}
```
### Advanced search: autocomplete chips
A new search widget, `autocomplete-chips`, provides chip-based multi-select with autocomplete for
filters such as Tags and Location. For `field: 'TAG'` it loads options through the tag service;
otherwise it uses the `options` from the widget settings. `[SearchWidgetSettings](../../lib/content-services/src/lib/search/models/search-widget-settings.interface.ts)`
gains a new optional property `allowOnlyPredefinedValues?: boolean`.
```json
{
"id": "tags",
"name": "Tags",
"enabled": true,
"component": {
"selector": "autocomplete-chips",
"settings": { "field": "TAG", "allowOnlyPredefinedValues": true }
}
}
```
### Header customization
`[HeaderLayoutComponent](../core/components/header.component.md)` gained two new inputs:
| Input | Type | Default | Description |
| ------------ | --------- | -------- | ---------------------------------------- |
| `showLogo` | `boolean` | `true` | Whether the logo is displayed. |
| `toggleIcon` | `string` | `'menu'` | Icon used for the sidenav toggle button. |
### Icon font set
`[IconComponent](../core/components/icon.component.md)` gained a new `fontSet` input, letting you
render an icon from a custom Material icon font set:
```html
<adf-icon value="my_icon" fontSet="my-font-set"></adf-icon>
```
### OAuth2 configuration handling
`[AppConfigService](../core/services/app-config.service.md)` now exposes a normalized `oauth2` getter.
Before:
```ts
const oauth = this.appConfigService.get(AppConfigValues.OAUTHCONFIG, {});
```
After:
```ts
const oauth = this.appConfigService.oauth2; // returns an OauthConfigModel, defaulting to {}
```
- The `implicitFlow`, `silentLogin` and `codeFlow` flags now accept the string values `'true'` / `'false'` in `app.config.json` in addition to real booleans, and are coerced to booleans by the getter. The `oauth2.silentLogin` schema type was widened to `["boolean", "string"]`.
- `[OauthConfigModel](../../lib/core/src/lib/auth/models/oauth-config.model.ts)` gains an optional `redirectSilentIframeUri?: string` field.
## Behavioural changes
| Area | Change |
| --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search facets | Facet chips with no results are rendered disabled and show a `remove` icon instead of the dropdown arrow. |
| Search facet/filter chips | The dropdown arrow flips between `keyboard_arrow_down` / `keyboard_arrow_up` with the menu state, the toggled-chip border uses the primary color, and the filter "cancel" action was relabeled from **Remove** to **Clear**. |
| [People (cloud)](../process-services-cloud/components/people-cloud.component.md) | No longer triggers an identity search for an empty value; at least one character is required. |
| Process / task filters | A filter is highlighted as active only when the current route matches the filter context and it is the current filter. |
| [Card view text item](../../lib/core/src/lib/card-view/components/card-view-textitem/card-view-textitem.component.ts) | On an invalid edit, `CardViewUpdateService.update` is now also emitted (with the edited value) after clearing previous errors. |
| [App config](../core/services/app-config.service.md) | When `app.config.json` fails schema validation, `AppConfigService` now logs `console.error('app.config.json contains validation errors')` and continues with the existing config. |
| Shared link expiry (security) | Setting an expiry now recreates the shared link with an `expiresAt` value so the backend enforces expiry on the link itself; turning the expiry off recreates a non-expiring link. |
| Accessibility | The filter-menu close control is now a real `button`, Shift+Tab is trapped inside filter menu cards, and the autocomplete input is associated with its listbox via `aria-controls`. |
## Theme changes
Several components now expose their styles through `--adf-*` CSS custom properties, so you can theme
them without overriding internal selectors. Defaults preserve the previous appearance. Override a
property in your global stylesheet, for example:
```scss
:root {
--adf-card-view-background: #fafafa;
--adf-card-view-border-radius: 8px;
}
```
The notable additions in this release:
| Component | CSS custom properties |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Card view](../core/components/card-view.component.md) | `--adf-card-view-background` (default `white`), `--adf-card-view-border` (`unset`), `--adf-card-view-border-color` (`unset`), `--adf-card-view-border-radius` (`0`) |
| [About panel](../core/components/about.component.md) | `--adf-about-panel-header-height` (`48px`), `--adf-about-panel-header-title-color` |
| About server settings | `--adf-about-server-settings-background`, `--adf-about-server-settings-color`, `--adf-about-server-settings-border-radius`, `--adf-about-server-settings-padding` |
| Package list table | `--adf-package-list-table-background`, plus `--adf-package-list-table-header-*` and `--adf-package-list-table-row-*` (borders, min-height, cell colors) |
| [Edit task / service filter](../process-services-cloud/components/edit-task-filter-cloud.component.md) | `--adf-edit-task-and-service-filter-header-title-color`, `--adf-edit-task-and-service-filter-header-description-color`, `--adf-edit-task-and-service-filter-header-height`, `--adf-edit-task-and-service-filter-content-text-label-color`, `--adf-edit-task-and-service-filter-content-select-label-color` |
| [Edit process filter](../process-services-cloud/components/edit-process-filter-cloud.component.md) | `--adf-edit-process-filter-header-height`, `--adf-edit-process-filter-header-title-color`, `--adf-edit-process-filter-header-description-color`, `--adf-edit-process-filter-content-text-label-color`, `--adf-edit-process-filter-content-select-label-color` |
docs/upgrade-guide/upgrade62-63.md
+377
View File
@@ -0,0 +1,377 @@
## Title: Upgrading from ADF v6.2 to v6.3
# Upgrading from ADF v6.2 to v6.3
This guide provides instructions on how to upgrade your v6.2.0 ADF projects to v6.3.0.
---
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup.
Do not skip this task if you want your application to be updated to the most recent version of ADF.
Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates.
After the upgrade, check the other sections below to see if there are any changes affecting your project.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [JS-API v7 and type migrations](#js-api-v7-and-type-migrations)
- [Third-party libraries](#third-party-libraries)
- [HTTP client and auth](#http-client-and-auth)
- [Breadcrumbs moved to a secondary entry point](#breadcrumbs-moved-to-a-secondary-entry-point)
- [Search API changes](#search-api-changes)
- [Comments component](#comments-component)
- [Removed and hidden items](#removed-and-hidden-items)
- [CSRF default changed](#csrf-default-changed)
- [Role-based authorization](#role-based-authorization)
- [Other breaking changes](#other-breaking-changes)
- [Deprecated items](#deprecated-items)
- [New components and features](#new-components-and-features)
- [Advanced search](#advanced-search)
- [Core breadcrumbs](#core-breadcrumbs)
- [Data Table form widget](#data-table-form-widget)
- [Content metadata](#content-metadata)
- [Other additions](#other-additions)
- [Behavioural changes](#behavioural-changes)
- [Theme changes](#theme-changes)
## Library updates
Update the `package.json` file with the latest library versions:
```json
{
"dependencies": {
"@alfresco/adf-core": "6.3.0",
"@alfresco/adf-content-services": "6.3.0",
"@alfresco/adf-process-services": "6.3.0",
"@alfresco/adf-process-services-cloud": "6.3.0",
"@alfresco/adf-insights": "6.3.0",
"@alfresco/adf-extensions": "6.3.0",
"@alfresco/js-api": ">=7.0.0"
}
}
```
**Important:** ADF 6.3.0 requires `@alfresco/js-api` **v7 or later** (`>=7.0.0`). This is the biggest
single change to take into account — see [JS-API v7 and type migrations](#js-api-v7-and-type-migrations).
The advanced date-range search and several date pickers now use `date-fns`. Make sure the new
peer dependency `@angular/material-date-fns-adapter` is installed.
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`, then reinstall:
```sh
npm install
```
## Breaking changes
### JS-API v7 and type migrations
ADF now consumes the strongly-typed models from `@alfresco/js-api` v7 directly instead of its own
handwritten wrappers. Update your type references accordingly.
| Before (ADF wrapper / old type) | After (`@alfresco/js-api` type) |
| ------------------------------- | ------------------------------- |
| `MinimalNode` | `Node` |
| `MinimalNodeEntryEntity` | `Node` |
| `AssocChildBody` | `ChildAssociationBody` |
| `QueryBody` | `SearchRequest` |
| `SiteBody` | `SiteBodyCreate` |
| `FavoriteBody` | `FavoriteBodyCreate` |
The wrapper model file `document-library.model.ts` was **removed** from `@alfresco/adf-content-services`.
The following exports are no longer available from ADF — import the equivalents from `@alfresco/js-api`:
`NodePaging`, `NodePagingList`, `NodeMinimalEntry`, `NodeMinimal`, `Pagination`, `UserInfo`,
`ContentInfo`, `PathInfoEntity` (→ `PathInfo`), `PathElementEntity` (→ `PathElement`), `NodeProperties`.
Public service signatures changed as a result — for example:
```ts
// NodesApiService — before
getNode(nodeId: string, options?: any): Observable<MinimalNode>
// after
getNode(nodeId: string, options?: any): Observable<Node>
```
- `[ContentService](../core/services/content.service.md)`: `folderCreate` / `folderEdit` are now `Subject<Node>`.
- `[SearchService](../core/services/search.service.md)`: `searchByQueryBody(queryBody: SearchRequest)`.
- `BaseQueryBuilderService` (base of `[SearchQueryBuilderService](../content-services/services/search-query-builder.service.md)`): `updated` is now `Subject<SearchRequest>`; `update`, `execute`, `search`, `buildQuery` all use `SearchRequest`.
- `SearchConfigurationInterface.generateQueryBody(...)` now returns `SearchRequest`. Note `SearchRequest` is a **class** (`new SearchRequest({...})`), whereas `QueryBody` was a plain interface — object literals still assign structurally.
- `User` from `@alfresco/js-api` is now a **class** rather than a type alias.
### Third-party libraries
To support Angular 14+, several dependencies were upgraded (major bumps with their own breaking changes):
| Package | Before | After |
| ------------------------------------ | --------- | -------------------------------------------- |
| `@alfresco/js-api` | `>=6.2.0` | `>=7.0.0` |
| `chart.js` | `2.9.4` | `^4.3.0` |
| `ng2-charts` | `2.4.2` | `^4.1.1` |
| `ngx-monaco-editor` | `8.1.1` | replaced by `ngx-monaco-editor-v2` `^14.0.4` |
| `@angular/material-date-fns-adapter` | — | new dependency |
If you use the Insights charts, migrate to the `ng2-charts` v4 / `chart.js` v4 API (tree-shakeable
registration, new chart config). If you use the Monaco editor, switch the import from
`ngx-monaco-editor` to `ngx-monaco-editor-v2`.
### HTTP client and auth
- The Alfresco API HTTP client was replaced by an Angular `HttpClient`-based `AdfHttpClient`
(the old `alfresco-api.http-client` identifier is gone). Update any references to `AdfHttpClient`.
- HTTP-client and auth configuration moved out of `CoreModule` into `AuthModule`. Make sure your
application imports `AuthModule` so the API client and auth config are provided.
- Read the username/token from `[AuthenticationService](../core/services/authentication.service.md)`
rather than from `AlfrescoApi`'s `oauth2Auth`.
- **`NullInjectorError: No provider for RedirectAuthService!`** — because auth moved into `AuthModule`, importing
`CoreModule` alone no longer provides the OIDC `RedirectAuthService`. Import `AuthModule.forRoot()` in your root
module (use `AuthModule.forRoot({ useHash: true })` for hash-based routing) to resolve the error.
### Breadcrumbs moved to a secondary entry point
The new breadcrumb components ship from a dedicated secondary entry point rather than the root barrel:
```ts
// Components
import { BreadcrumbComponent, BreadcrumbItemComponent } from '@alfresco/adf-core/breadcrumbs';
```
```scss
// Theme
@use '@alfresco/adf-core/breadcrumbs' as breadcrumbs;
```
They are **not** exported from the root `@alfresco/adf-core`, and their theme is no longer part of the
core styles index — add the imports above where needed.
### Search API changes
- `SearchChipInputComponent` **was removed.** Remove any imports/usages (the logical filter no longer uses it).
- `disableUpdateOnSubmit` was removed from search widget settings — delete it from your `search.config`.
- `[SearchLogicalFilterComponent](../content-services/components/search-logical-filter.component.md)` changed its value model. The per-field condition type went from `string[]` to a single space-separated `string`, and a new `MATCH_EXACT = 'matchExact'` field was added:
```ts
// LogicalSearchCondition — before: { matchAll: string[]; matchAny: string[]; exclude: string[] }
// after: { matchAll: string; matchAny: string; matchExact: string; exclude: string }
```
- `SearchChipAutocompleteInputComponent` and `SearchFilterAutocompleteChipsComponent` now use an
`AutocompleteOption` object model instead of plain strings. If you configured these with `string[]`
options, migrate to `AutocompleteOption[]` (`{ value: string; id?: string; fullPath?: string }`),
and note the new optional `SearchWidgetSettings.autocompleteOptions` field.
### Comments component
The comments components (`[adf-comments](../core/components/comments.component.md)` and
`adf-comment-list`) were cleaned up, with several consumer-facing consequences:
- **The** `interfaces` **barrel was removed.** Import `CommentsService` / the comments token from their
specific files (or the top-level `public-api`) instead of `.../comments/interfaces`.
- **Comment text is no longer sanitised as HTML** — the message is rendered as plain text
(`white-space: pre-line`), not via `[innerHTML]`. Any HTML in a comment now shows as literal text.
- **Comment data must be** `CommentModel` **instances.** Display logic moved into new `CommentModel`
getters (`hasAvatarPicture`, `userDisplayName`, `userInitials`); plain object literals cast as
`CommentModel` will no longer render correctly. Build them with `new CommentModel({...})`.
- `CommentListComponent` removed the public members `selectedComment`, `currentLocale`, and the
methods `getUserShortName()` and `isPictureDefined()`; selection side-effects and the
`.adf-is-selected` styling were dropped (the component just emits `clickRow`).
- Several template element IDs (`adf-comment-{id}`, `comment-user-*`, `comment-message-*`, …) were
removed — update any CSS/E2E selectors that relied on them.
### Removed and hidden items
| Item | Package | Notes |
| -------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SearchChipInputComponent` | `@alfresco/adf-content-services` | Removed (see [Search API changes](#search-api-changes)). |
| `document-library.model` exports | `@alfresco/adf-content-services` | Removed; use `@alfresco/js-api` types. |
| `AlfrescoApiCompatibility` usage | `@alfresco/adf-process-services` | `ExternalAlfrescoApiService` now extends `[AlfrescoApiService](../core/services/alfresco-api.service.md)` and uses `AlfrescoApi` (v7). Migrate any code typed against `AlfrescoApiCompatibility`. |
| Several `DocumentListComponent` / `DataTableComponent` methods | `@alfresco/adf-content-services`, `@alfresco/adf-core` | Made `private` (`updateCustomSourceData`, `setupDefaultColumns`, `preserveExistingSelection`, `isSingleSelectionMode`, `isMultipleSelectionMode`, `hasPreselectedNodes`, `hasPreselectedRows`, `hasCustomLayout`). `resetNewFolderPagination()` remains public. |
| `CallApiParams` (interface) | `@alfresco/adf-process-services-cloud` | Removed from the `BaseCloudService` public surface — it now uses `RequestOptions` from `@alfresco/js-api`. Only affects code that imported `CallApiParams` directly. |
### CSRF default changed
The default for the `disableCSRF` app-config key changed to `true`. When the key is **absent**
from `app.config.json`, CSRF handling is now disabled by default. If your backend requires the ADF
CSRF token, set it explicitly:
```json
{
"disableCSRF": false
}
```
### Role-based authorization
Roles are now resolved from the JWT access token instead of the remote `identity-adapter-service`
roles endpoint (a new `hxp_authorization` claim is supported alongside `realm_access`). As a result:
- `UserAccessService.fetchUserAccess()` is now **synchronous** (returns `void`, was `Promise`).
- `UserAccessService.resetAccess()` was **removed**, and its constructor no longer injects `OAuth2Service`.
- `AuthGuardSsoRoleService.canActivate()` is now **synchronous** (returns `boolean`, was `Promise<boolean>`).
### Other breaking changes
- **Bearer-excluded URL matching** is now anchored to the host + first path segment
(`^https?://[^/]+/<pattern>`) instead of matching anywhere in the URL. Review any custom
`bearerExcludedUrls` patterns that relied on substring matching.
- **DataTable multiselect checkbox** wrapper changed from a `<div>` to a `<label>` (same classes),
and row padding moved onto the first/last cells. Update CSS/E2E selectors targeting
`div.adf-datatable-checkbox` or the old `.adf-datatable-row` padding.
- The header user-info container's default right margin changed from `16px` to `8px`.
- Date pickers/filters that used `moment.Moment` values now use native `Date`
(see [Behavioural changes](#behavioural-changes)).
## Deprecated items
The following components are deprecated (still functional, but slated for removal). Their exact
`@deprecated` notes:
| Component | Selector | Note |
| ----------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `[WebscriptComponent](../content-services/components/webscript.component.md)` | `adf-webscript-get` | "Webscript component has never been turned into a product and has no UI/UX and no use cases in ACA/ADW/ACC." |
| `[LikeComponent](../content-services/components/like.component.md)` | `adf-like` | "Like component is not used in ACA/ADW/ACC, can be removed." |
| `[RatingComponent](../content-services/components/rating.component.md)` | `adf-rating` | "Rating component is not used in ACA/ADW/ACC, can be removed." |
The NgModules that bundle those components are also now `@deprecated` (`@alfresco/adf-content-services`):
**`SocialModule`** (bundles the Like/Rating components) and **`WebScriptModule`** (bundles the Webscript
component). Stop importing them.
## New components and features
### Advanced search
Several new advanced-search building blocks were added in `@alfresco/adf-content-services`, along with
two new widget selector types (`date-range-advanced`, `properties`):
| Component | Selector | Description |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------- |
| `[SearchDateRangeAdvancedComponent](../../lib/content-services/src/lib/search/components/search-date-range-advanced-tabbed/search-date-range-advanced/search-date-range-advanced.component.ts)` | `adf-search-date-range-advanced` | Date-range form with "Any / In the last / Between" modes (date-fns based). |
| `SearchDateRangeAdvancedTabbedComponent` | `adf-search-date-range-advanced-tabbed` | Search widget (`date-range-advanced`) wrapping the date-range form in tabs. |
| `[SearchFilterTabbedComponent](../../lib/content-services/src/lib/search/components/search-filter-tabbed/search-filter-tabbed.component.ts)` (+ `SearchFilterTabDirective`) | `adf-search-filter-tabbed` / `[adf-search-filter-tab]` | Tabbed layout for grouping filter content. |
| `SearchFacetChipTabbedComponent` | `adf-search-facet-chip-tabbed` | Facet chip grouping two facet fields (e.g. creator + modifier) into tabs. |
| `SearchPropertiesComponent` | `adf-search-properties` | Search widget (`properties`) to filter by file size and file type. |
`BaseQueryBuilderService` is now a public export. See the search configuration docs for how to wire
the new widget selectors into your `search.config`.
### Core breadcrumbs
A new breadcrumb component set is available from the `@alfresco/adf-core/breadcrumbs` secondary entry
point (see [Breadcrumbs moved to a secondary entry point](#breadcrumbs-moved-to-a-secondary-entry-point)).
| Component | Selector | Description |
| ------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BreadcrumbComponent` | `adf-breadcrumb` | Standalone breadcrumb with `@Input() compact` and `@Output() compactChange`; collapses to first + last item with an overflow menu in compact mode. |
| `BreadcrumbItemComponent` | `adf-breadcrumb-item` | Content-projected breadcrumb item. |
### Data Table form widget
A new **Data Table** cloud form widget renders tabular data inside a form, backed by process/form
variables or a direct JSON value.
- New `FormFieldTypes.DATA_TABLE = 'data-table'` and `FormFieldModel.schemaDefinition: DataColumn[]` in `@alfresco/adf-core`.
- New `DataTableWidgetComponent` (selector `data-table`) and `WidgetDataTableAdapter` in `@alfresco/adf-process-services-cloud`, auto-registered by `CloudFormRenderingService`.
- The `VariableConfig` interface is now exported from `@alfresco/adf-core` (`{ variableName; optionsPath?; optionsId?; optionsLabel? }`), and form-field `optionType` gained a `'variable'` value so dropdowns can resolve their options from a process/form variable.
### Content metadata
`[ContentMetadataCardComponent](../content-services/components/content-metadata-card.component.md)` gained new configuration:
| Member | Type | Default | Description |
| ---------------------------- | ----------------------- | ------- | --------------------------------------------------------------------------------- |
| `@Input() editable` | `boolean` | `false` | Toggles editable state of the content metadata (supports two-way `[(editable)]`). |
| `@Output() editableChange` | `EventEmitter<boolean>` | — | Emitted when the editable state changes. |
| `@Input() displayTags` | `boolean` | `true` | Show tags in the card. |
| `@Input() displayCategories` | `boolean` | `true` | Show categories in the card. |
### Other additions
- **CardView chip labels** — `[CardViewComponent](../core/components/card-view.component.md)`,
`CardViewItemDispatcherComponent` and `CardViewTextItemComponent` gained
`@Input() displayLabelForChips: boolean = false` to render a header label above multivalued chip properties.
- **About panel automation id** — `AboutPanelDirective` gained `@Input() automationId: string`, rendered as `data-automation-id`.
- `provideTranslations(id, path)` — a convenience provider factory exported from `@alfresco/adf-core`, replacing the verbose `TRANSLATION_PROVIDER` literal (the old form still works).
- `ALFRESCO_API_FACTORY` — a new injection token (with `AlfrescoApiFactory` interface) lets applications supply a custom `AlfrescoApi` implementation, e.g. to invalidate the session on HTTP 401.
- New additive `adfDateTime` pipe (`DateTimePipe`) in `@alfresco/adf-core`.
## Behavioural changes
| Area | Change |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Date handling | Several pipes/components migrated from `moment` to `date-fns`: `TimeAgoPipe`, process-name pipes, `LockService`, `DateRangeFilterComponent`/service, `StartTaskCloudComponent`, `TaskListComponent`. Date-picker/filter values are now native `Date` objects instead of `moment.Moment`. (moment is still a dependency for other code.) |
| DataTable | Whole checkbox cell is clickable; in single-selection mode clicking a selected row now **unselects** it and emits `row-unselect`; actions menus open on `Enter`; sorting matches on `sortingKey`; the header row is retained when a filter is active with no results. |
| Version list | The restore action is disabled for the latest version of a file. |
| People | `PeopleContentService.getPerson(id)` no longer overwrites the cached current user (that side-effect moved to `getCurrentUserInfo()`). |
| Viewers | Viewer form widgets accept a single file object (not just arrays) and no longer show a file after it was removed. |
| Notifications | The "mark all as read" control is now an icon button (`done_all`). |
| Security | Input sanitisation hardened: search highlight uses safer tag stripping, comment text is HTML-escaped, the login component guards against prototype pollution (`__proto__`/`constructor`/`prototype`), and user initials are built via the DOM to escape user names. |
## Theme changes
The Identity User Info avatar styles are now themeable via CSS custom properties:
| Property | Default |
| ---------------------------------------- | -------------------------------------- |
| `--adf-identity-user-info-background` | `var(--adf-theme-primary-300)` |
| `--adf-identity-user-info-height` | `40px` |
| `--adf-identity-user-info-width` | `40px` |
| `--adf-identity-user-info-line-height` | `40px` |
| `--adf-identity-user-info-font-size` | `var(--theme-adf-picture-1-font-size)` |
| `--adf-user-info-container-margin-right` | `8px` |
docs/upgrade-guide/upgrade63-64.md
+293
View File
@@ -0,0 +1,293 @@
---
Title: Upgrading from ADF v6.3 to v6.4
---
# Upgrading from ADF v6.3 to v6.4
This guide provides instructions on how to upgrade your v6.3.0 ADF projects to v6.4.0.
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup.
Do not skip this task if you want your application to be updated to the most recent version of ADF.
Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates.
After the upgrade, check the other sections below to see if there are any changes affecting your project.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Date handling (moment → date-fns)](#date-handling-moment--date-fns)
- [DataColumnType moved and new column types](#datacolumntype-moved-and-new-column-types)
- [Document list column configuration](#document-list-column-configuration)
- [Card view components](#card-view-components)
- [Typography from theme](#typography-from-theme)
- [Error-handling clean-up](#error-handling-clean-up)
- [SCSS include path](#scss-include-path)
- [Other breaking changes](#other-breaking-changes)
- [Deprecated items](#deprecated-items)
- [New components and features](#new-components-and-features)
- [Behavioural changes](#behavioural-changes)
- [Theme changes](#theme-changes)
## Library updates
Update the `package.json` file with the latest library versions:
```json
{
"dependencies": {
"@alfresco/adf-core": "6.4.0",
"@alfresco/adf-content-services": "6.4.0",
"@alfresco/adf-process-services": "6.4.0",
"@alfresco/adf-process-services-cloud": "6.4.0",
"@alfresco/adf-insights": "6.4.0",
"@alfresco/adf-extensions": "6.4.0",
"@alfresco/js-api": ">=7.1.0"
}
}
```
**Dependency changes to note:**
- ADF no longer depends on `moment`, `@angular/material-moment-adapter`, or `@mat-datetimepicker/moment`.
If your application still uses `moment` directly (or the deprecated ADF moment pipes/adapter), add
`moment` to your own `package.json`.
- ADF uses `@angular/material-date-fns-adapter` and `date-fns` for date handling — make sure they resolve.
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`, then reinstall:
```sh
npm install
```
## Breaking changes
### Date handling (moment → date-fns)
ADF now uses `date-fns` for all date parsing/formatting and provides its own Material date adapters.
**Removed dependencies** — `moment`, `@angular/material-moment-adapter`, and `@mat-datetimepicker/moment`
are removed from the ADF libraries' peer dependencies. Remove any direct imports of
`@angular/material-moment-adapter` / `@mat-datetimepicker/moment` from your app.
**New API (from `@alfresco/adf-core`):**
| Symbol | Purpose |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AdfDateFnsAdapter` | `DateAdapter<Date>` implementation (replaces `MomentDateAdapter`). Auto-switches locale from `UserPreferencesService`; has a settable `displayFormat`. |
| `AdfDateTimeFnsAdapter` | `DatetimeAdapter<Date>` implementation for date-time pickers. |
| `ADF_DATE_FORMATS` | `MatDateFormats` value to provide via `MAT_DATE_FORMATS`. |
| `ADF_DATETIME_FORMATS` | `MatDatetimeFormats` value to provide via `MAT_DATETIME_FORMATS`. |
| `DateFnsUtils` | Static date helpers (`formatDate`, `parseDate`, `convertMomentToDateFnsFormat`, …). |
Replace the moment adapter wiring in your component providers:
```ts
// Before
providers: [
{ provide: MAT_DATE_FORMATS, useValue: MOMENT_DATE_FORMATS },
{ provide: DateAdapter, useClass: MomentDateAdapter }
]
// After
providers: [
{ provide: MAT_DATE_FORMATS, useValue: ADF_DATE_FORMATS },
{ provide: DateAdapter, useClass: AdfDateFnsAdapter }
// for date-time pickers, also:
// { provide: MAT_DATETIME_FORMATS, useValue: ADF_DATETIME_FORMATS },
// { provide: DatetimeAdapter, useClass: AdfDateTimeFnsAdapter }
]
```
**Removed / deprecated exports:**
- `CLOUD_FORM_DATE_FORMATS` was **removed** from `@alfresco/adf-process-services-cloud` — use `ADF_DATE_FORMATS` from `@alfresco/adf-core`.
- `MomentDateAdapter` and `MOMENT_DATE_FORMATS` are **deprecated** (still exported). `MomentDateAdapter` no longer imports moment directly — it relies on a globally-available `moment`.
**Date format tokens change** — format strings moved from moment tokens to date-fns tokens, e.g.
`DD-MM-YYYY` → `dd-MM-yyyy`, `YYYY` → `yyyy`. Update custom date formats in your `app.config.json` and
component inputs. (Moment-style tokens passed to `AdfDateFnsAdapter.displayFormat` are auto-converted,
but prefer native date-fns tokens.) The default cloud form date format is now `dd-MM-yyyy`.
**Type changes** — date values that were typed `moment.Moment` are now native `Date` (for example
`DateWidgetComponent.minDate` / `maxDate` / `startAt`, and its `onDateChange` event). Update any code
that constructed or consumed these as moment objects; use `dateAdapter.parse/format` or `DateFnsUtils`
instead of `moment()`.
### DataColumnType moved and new column types
The column type definitions moved packages:
- `DataColumnType` and `DataColumnTypes` are **no longer exported from `@alfresco/adf-core`** — they are
now exported from **`@alfresco/adf-extensions`**. Update your imports:
```ts
// Before
import { DataColumnType } from '@alfresco/adf-core';
// After
import { DataColumnType } from '@alfresco/adf-extensions';
```
- The allowed column `type` values grew from `text | image | date | json | icon | fileSize | location`
to also include **`boolean`**, **`amount`**, and **`number`**. `DataColumnComponent.type` is now typed
as the `DataColumnType` union (previously a loose `string`).
**Data-table form widget no longer forces columns to text** — the cloud/process Data Table form widget
(`WidgetDataTableAdapter`) previously overwrote every column's `type` with `'text'`. That behaviour was
removed, so the `type` declared in a widget's `schemaDefinition` is now honoured. If a schema declared a
non-text `type` but relied on it rendering as plain text, set `type: 'text'` explicitly to preserve the
old appearance. This change has no compile-time signal.
### Document list column configuration
[`DocumentListComponent`](../content-services/components/document-list.component.md) now extends
`DataTableSchema` and supports a user-facing column selector:
- New `@Input() columnsPresetKey?: string` — key of a columns preset defined in `extension.json`.
- New `@Input() maxColumnsVisible?: number` — caps the number of simultaneously visible columns.
- `DocumentListPresetRef` (in `@alfresco/adf-extensions`) gained an optional `isHidden?: boolean`.
Because the component was refactored to extend `DataTableSchema`, several **private** members were
removed (`layoutPresets`, `hasCustomLayout`, `getLayoutPreset()`, `setTableSchema()`,
`setupDefaultColumns()`, `loadLayoutPresets()`). Standard `<adf-document-list>` usage is unaffected, but
consumers who subclassed the component or relied on those internals must adapt.
### Card view components
- **Selector rename** — `CardViewKeyValuePairsItemComponent` selector changed from
`adf-card-view-keyvaluepairsitem` to **`adf-card-view-key-value-pairs-item`**. Update any template using the old selector.
- **Encapsulation** — `CardViewSelectItemComponent` now uses `ViewEncapsulation.None`, so its styles are
global. New host classes were added to several items (`.adf-card-view-selectitem`,
`.adf-card-view-textitem`, `.adf-card-view-key-value-pairs-item`, `.adf-card-view-dateitem`) — review
any consumer CSS that targets these components.
- **`CardViewDateItemComponent`** — removed the public `dateFormat` property and the `AppConfigService`
constructor dependency (constructor arity change). Non-editable dates are now parsed with the native
`Date` rather than an app-config format.
- **`ContentMetadataComponent.canExpandTheCard`** — signature changed from `(group: CardViewGroup)` to
`(groupTitle: string)`.
### Typography from theme
The error and user-info components now take typography from the Material theme instead of hard-coded
CSS. This removes some CSS classes that consumers may have targeted:
- `ErrorContentComponent` now injects `BreakpointObserver` (constructor arity change) and applies
`mat-*` typography classes; the hard-coded font-size rules and `@media` block were removed.
- The user-info components ([`content-user-info`](../content-services/components/content-user-info.component.md),
`identity-user-info`, `process-user-info`) replaced `.adf-userinfo-title` with `.mat-title`, removed
`.adf-userinfo__detail-profile`, and changed the full-name element from `<span>` to `<h2>`. Element IDs
(`ecm-username`, `identity-username`, etc.) are unchanged.
### Error-handling clean-up
Around twenty services had their internal `handleError` / `catchError` wrappers removed
(`AuditService`, `SitesService`, `DownloadZipService`, `CustomResourcesService`, `DocumentListService`,
`NodeCommentsService`, `RatingService`, `SearchService`, `IdentityUserService`, `IdentityGroupService`,
`AppsProcessService`, `TaskFilterService`, and others). Consequences:
- Subscribers now receive the **raw API error** rather than a normalised `'Server error'` string, and
errors are **no longer logged** via `LogService`. Ensure your own `error` callbacks handle the raw error.
- `RenditionService` and `WebscriptComponent` now reject/throw with a real `Error` object instead of
`undefined`.
- `LogService` was removed from many of these services' constructors (only relevant if you instantiate
them manually).
Several public return types were also tightened, e.g.: `AuditService.getAuditApp()` →
`Observable<AuditApp>`; `CustomResourcesService.getRecentFiles()` → `ResultSetPaging`, `loadFavorites()`
→ `FavoritePaging`, `loadSites()` → `SitePaging`; `TaskListService.getTotalTasks()` →
`Observable<TaskListModel>`; and `ProcessFilterService` filter methods now return
`UserProcessInstanceFilterRepresentation`. `ActivitiAlfrescoContentService.toJson()` / `toJsonArray()`
were removed. Update any code relying on the previous types.
### SCSS include path
Component SCSS partials now share responsive breakpoints via `@import 'styles/flex';` (the `layout-bp`
mixin). If your build imports ADF component SCSS partials directly, add ADF core's styles folder to your
Sass include paths (`node_modules/@alfresco/adf-core/...` — the repo uses `../core/src/lib`), otherwise
`@import 'styles/flex'` will fail to resolve. Breakpoint thresholds are unchanged, so there is no
responsive behaviour change.
### Other breaking changes
- **Constructor arity changes** (only affect manual instantiation): `LibraryDialogComponent`
(+`NotificationService`), `ErrorContentComponent` (+`BreakpointObserver`), `CardViewDateItemComponent`
(removed `AppConfigService`).
- **CSS class rename** — the advanced date facet container class changed from
`adf-search-date-range-horizontal-container` to `adf-search-date-range-container-row`.
- **Load More** — `InfinitePaginationComponent` now emits `RequestPaginationModel.merge = true` on "Load
More" (was `false`). Handlers that branch on `merge` will behave differently.
- **Dependency** — the CLI/root `request` dependency was replaced by `node-fetch` (`^2.7.0`); `request`
and `@types/request` were removed.
## Deprecated items
| Item | Package | Note |
| ------------------------------------------------------------------------------ | -------------------- | ----------------------------------------------------------------------------------------------------- |
| `MomentDateAdapter` | `@alfresco/adf-core` | "this class is deprecated and should not be used." Use `AdfDateFnsAdapter` / `AdfDateTimeFnsAdapter`. |
| `MOMENT_DATE_FORMATS` | `@alfresco/adf-core` | Superseded by `ADF_DATE_FORMATS`. |
| `MomentDatePipe` (`adfMomentDate`), `MomentDateTimePipe` (`adfMomentDateTime`) | `@alfresco/adf-core` | Not migrated; still require a globally-available `moment` at runtime. |
## New components and features
### Data table column types
New column types with dedicated cell renderers in `@alfresco/adf-core`:
| Type | Cell component | Config |
| --------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `boolean` | `BooleanCellComponent` | Also adds the `BooleanPipe` (`adfBoolean`). |
| `amount` | `AmountCellComponent` | New `DataColumn.currencyConfig?: CurrencyConfig` (`{ code?; display?; digitsInfo?; locale? }`). |
| `number` | `NumberCellComponent` | New `DataColumn.decimalConfig?: DecimalConfig` (`{ digitsInfo?; locale? }`). `CurrencyConfig extends DecimalConfig`. |
Data columns also gained an optional `@Input() order?: number` (`DataColumnComponent`) / `order?` field
(`DataColumn`); custom schema columns are sorted by it.
### Configurable document list columns
A column selector (`adf-datatable-column-selector`) can now show/hide document-list columns, driven by
the new `columnsPresetKey` / `maxColumnsVisible` inputs above. `ColumnsSelectorComponent` gained
`@Input() columnsSorting` (default `true`) and `@Input() maxColumnsVisible?`.
### Content metadata custom panels
[`ContentMetadataComponent`](../../lib/content-services/src/lib/content-metadata/components/content-metadata/content-metadata.component.ts) and
[`ContentMetadataCardComponent`](../content-services/components/content-metadata-card.component.md) gained `@Input() customPanels: ContentMetadataCustomPanel[]`, rendering
registered extension components as extra metadata panels:
```ts
interface ContentMetadataCustomPanel {
panelTitle: string;
component: string; // registered extension component id
}
```
A custom panel whose `panelTitle` matches the `displayAspect` input is rendered initially expanded.
### Other additions
- `ProcessContentService.getProcessesAndTasksOnContent(sourceId, source, size?, page?)` — lists processes
and tasks associated with a document.
- New date-fns helpers `AdfDateFnsAdapter`, `AdfDateTimeFnsAdapter`, `DateFnsUtils`, `ADF_DATE_FORMATS`,
`ADF_DATETIME_FORMATS` (see [Date handling](#date-handling-moment--date-fns)).
## Behavioural changes
| Area | Change |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Data table | Cloud/process Data Table form widget honours declared column `type` (no longer forced to text). |
| Permissions | `NodePermissionService.getNodeRoles` returns the node's settable permissions directly for nodes not under a Site (no search API call). |
| Groups | The user-name column falls back to the group `id` when `displayName` is missing. |
| Rendition | `RenditionService` rendition polling now retries correctly until the rendition is `CREATED`. |
| Viewer | `PdfViewerComponent` handles horizontally overflowing pages (toolbar shifts, container height `100vh` → `100%`). |
| Pagination | "Load More" no longer resets scroll to the top and suppresses the loading spinner while merging. |
| i18n | The process/task list "Name" column header is now "Task Name". |
| Accessibility | Date-facet number input and tag chip list gained aria labels/roles. |
## Theme changes
Error and user-info typography now derive from the Material theme rather than hard-coded font sizes; see
[Typography from theme](#typography-from-theme). Consumers should theme these via Material typography
rather than by overriding the removed font-size CSS.
docs/upgrade-guide/upgrade64-652.md
+201
View File
@@ -0,0 +1,201 @@
---
Title: Upgrading from ADF v6.4 to v6.5.2
---
# Upgrading from ADF v6.4 to v6.5.2
This guide provides instructions on how to upgrade your v6.4.0 ADF projects to v6.5.2 (covering the
6.5.0, 6.5.1 and 6.5.2 releases).
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup.
Do not skip this task if you want your application to be updated to the most recent version of ADF.
Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates.
After the upgrade, check the other sections below to see if there are any changes affecting your project.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Authentication refactor](#authentication-refactor)
- [OAuth2 app.config keys](#oauth2-appconfig-keys)
- [Standalone components and pipes](#standalone-components-and-pipes)
- [Data table date column](#data-table-date-column)
- [Search query migration (Elasticsearch)](#search-query-migration-elasticsearch)
- [Notification history](#notification-history)
- [Info drawer styling](#info-drawer-styling)
- [Other breaking changes](#other-breaking-changes)
- [New components and features](#new-components-and-features)
- [Behavioural changes](#behavioural-changes)
- [Theme changes](#theme-changes)
## Library updates
Update the `package.json` file with the latest library versions:
```json
{
"dependencies": {
"@alfresco/adf-core": "6.5.2",
"@alfresco/adf-content-services": "6.5.2",
"@alfresco/adf-process-services": "6.5.2",
"@alfresco/adf-process-services-cloud": "6.5.2",
"@alfresco/adf-insights": "6.5.2",
"@alfresco/adf-extensions": "6.5.2",
"@alfresco/js-api": ">=7.2.0"
}
}
```
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`, then reinstall:
```sh
npm install
```
## Breaking changes
### Authentication refactor
Authentication was rewritten to run entirely inside ADF (on `AdfHttpClient`) instead of delegating to
`@alfresco/js-api`. The monolithic authentication service was split into dedicated services, and OIDC
logic was relocated. Module registration in your `AppModule` is unchanged (you still import `AuthModule`),
but the following affect consumer code:
- **`OIDCAuthenticationService` was renamed to `OidcAuthenticationService`.** Update any import/usage by name.
- **`addTokenToHeader` now takes the request URL as its first argument:**
```ts
// Before
addTokenToHeader(headers?: HttpHeaders): Observable<HttpHeaders>
// After
addTokenToHeader(requestUrl: string, headersArg?: HttpHeaders): Observable<HttpHeaders>
```
This affects any custom `Authentication` implementation or interceptor.
- **Relocated methods:**
- `setRedirect()` / `getRedirect()` moved to `BasicAlfrescoAuthService`.
- `ssoImplicitLogin()` / `isPublicUrl()` moved to `OidcAuthenticationService`.
- **`AuthGuardBase`** switched from `inject()` field injection to an explicit constructor requiring
`(AuthenticationService, BasicAlfrescoAuthService, OidcAuthenticationService, Router, AppConfigService, MatDialog, StorageService)`. Any subclass with its own constructor must pass these through `super(...)`.
- `CoreModule` no longer imports the legacy JS-API client modules (`LegacyApiClientModule`,
`AlfrescoJsClientsModule`). If you relied on them being pulled in transitively via core, import them explicitly.
New auth services are exported from `@alfresco/adf-core`: `BasicAlfrescoAuthService`, `ContentAuth`,
`ProcessAuth`, and the `AuthenticationServiceInterface`.
- **The ECM/BPM-specific auth accessors are now `@deprecated`** (still functional): `getEcmUsername()` /
`getBpmUsername()` on `AuthenticationService` and `OidcAuthenticationService`, and `getTicketEcm()` /
`getTicketBpm()` on `BasicAlfrescoAuthService`. Migrate to the unified `getUsername()` / token accessors — these
deprecated methods are removed later, in v8.2.1.
### OAuth2 app.config keys
The OIDC/OAuth2 configuration in `app.config.json` changed:
| Key | Change | Consumer action |
| -------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `oauth2.redirectSilentIframeUri` | Silent-refresh now reads this value instead of a hardcoded `/silent-refresh.html`. | **Set this explicitly** if you use silent refresh, otherwise the silent-refresh URL is undefined. |
| `oauth2.redirectUri` | New optional post-login redirect base, appended to the location origin when not `/`. | Optional; useful for apps served from a sub-path. |
| `oauth2.secret` | No longer a **required** schema property (only `host`, `clientId`, `scope` are required). | Public/PKCE clients no longer need to supply `secret`. |
If you ship your own copy of `silent-refresh.html`, add the message-post that returns the token to the
opener/parent window (`(window.opener || window.parent).postMessage(location.hash || ('#' + location.search), location.origin)`),
otherwise the token is not picked up after a silent refresh.
### Standalone components and pipes
The following became **standalone** and were moved from their module's `declarations` to `imports`. If
your own NgModule directly declared any of them, import them instead:
- `DateCellComponent`, `LocationCellComponent` (datatable cells)
- `LocalizedDatePipe`, `TimeAgoPipe`
`LocationCellComponent` now also requires the column's `format` to be set for the value/tooltip to render.
### Data table date column
`date`-type columns are now configurable via a new `dateConfig`, and `DateCellComponent` was reworked:
- New interfaces in `@alfresco/adf-core`: `LocaleConfig { locale?: string }` and
`DateConfig extends LocaleConfig { format?: string; tooltipFormat?: string }` (`DecimalConfig` now also
extends `LocaleConfig`).
- New optional `DataColumn.dateConfig?: DateConfig` and `@Input() dateConfig` on `DateCellComponent`.
- **Removed** from `DateCellComponent`: the `static DATE_FORMAT` constant and the public `currentLocale`,
`dateFormat`, `tooltipDateFormat` fields (and its old multi-argument constructor). Update code referencing them.
Format/tooltip/locale now resolve `dateConfig.*` → app-config `dateValues.*` → defaults (`format: 'medium'`,
`tooltipFormat: 'medium'`).
### Search query migration (Elasticsearch)
Some built-in search queries were migrated from the older Solr-style special properties (`PNAME`, `ANAME`)
to path-based AFTS syntax (`PATH:`) for Elasticsearch compatibility:
- `CustomResourcesService.getRecentFiles()` filter: `-PNAME:"0/wiki"` → `-PATH:"//cm:wiki/*"`.
- Add-permission authority search: `ANAME:("0/APP.DEFAULT")` → `PATH:"//cm:APP.DEFAULT/*"`; `userName` was
added and `displayName` removed from the matched fields.
If you have a custom `search.config` or `SearchConfigurationService` that emits `PNAME`/`ANAME` fragments,
migrate them to `PATH:"//cm:.../*"` syntax against an Elasticsearch-compatible backend. The
`AutocompleteOption` interface gained an optional `query?: string` so an autocomplete option can supply
its own query fragment instead of the default `field:"value"`.
### Notification history
- The storage key moved from the `NotificationHistoryComponent.NOTIFICATION_STORAGE` static field to an
exported module-level constant `NOTIFICATION_STORAGE` in `notification.model.ts`. Import it from there
instead of the component.
- `NotificationModel` gained an optional `read?: boolean`. The history menu now tracks read/unread state
(see [Behavioural changes](#behavioural-changes)).
### Info drawer styling
`InfoDrawerComponent` tabs no longer override Material's internal `.mat-tab-label` classes; they use
ADF-owned classes (`.adf-info-drawer-tab`, `.adf-info-drawer-tab--active`) driven by design tokens. If you
styled the info-drawer tabs by targeting `.mat-tab-label`, retarget the new classes or the tokens (see
[Theme changes](#theme-changes)).
The internal SCSS mixin signature changed from `adf-components-variables()` to
`adf-components-variables($theme)`. If you call this mixin directly, pass the theme.
### Other breaking changes
- **Insights** — the `analytics.service.mock` test-fixture module (e.g. `fakeReportList`) was removed from
the `@alfresco/adf-insights` mock public API. Inline your own fixtures if you imported it.
## New components and features
- **Header background** — [`HeaderLayoutComponent`](../core/components/header.component.md) gained
`@Input() backgroundImage: string` (default `''`), and its `@Input() color` type was widened from
`ThemePalette` to `ThemePalette | string`, so it now also accepts a hex color (e.g. `'#42f57e'`).
- **Document list resizing** — [`DocumentListComponent`](../content-services/components/document-list.component.md)
gained `@Input() isResizingEnabled` (default `false`) and `@Input() blurOnResize` (default `true`);
`DataTableComponent` also gained `@Input() blurOnResize`.
- **Data table date config** — per-column `dateConfig` (see [Data table date column](#data-table-date-column)).
- **Info drawer design tokens** — themeable `--adf-info-drawer-tab-*` CSS custom properties (see [Theme changes](#theme-changes)).
- **Insights** — new exported abstract `DiagramElement` directive base class.
## Behavioural changes
| Area | Change |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Auth | Silent refresh now returns a fresh token to the app; `redirectUri`/`redirectSilentIframeUri` from `app.config.json` are honoured for login/silent-refresh URLs. |
| Notifications | The history menu shows only unread notifications; "mark as read" flags notifications as read and keeps them in storage rather than deleting them. New notifications default to `read: false`. |
| Viewer | PDF/TIFF viewer thumbnails now refresh when the displayed file changes. |
| Data table | Very long file/folder names no longer shift column alignment (body width `fit-content` → `100%`). |
| Share dialog | The extra gray area/padding around the share-link dialog content was removed. |
| Custom theme | Custom palette shades 100–300 are now calculated correctly, and custom themes inherit the default font family. |
## Theme changes
- **Info drawer tabs** are now themeable via `--adf-info-drawer-tab-*` CSS custom properties
(default/hover/active-unfocused/active-focused colors, backgrounds and bottom lines) instead of Material
internal class overrides.
- **Custom palette** generation was fixed (shades 100–300 now map to the correct base colors), and custom
themes now use the shared `$default-font-family` rather than a hardcoded Muli stack — expect minor visual
differences in custom themes.
docs/upgrade-guide/upgrade652-66.md
+238
View File
@@ -0,0 +1,238 @@
---
Title: Upgrading from ADF v6.5.2 to v6.6.0
---
# Upgrading from ADF v6.5.2 to v6.6.0
This guide provides instructions on how to upgrade your v6.5.2 ADF projects to v6.6.0.
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup.
Do not skip this task if you want your application to be updated to the most recent version of ADF.
Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates.
After the upgrade, check the other sections below to see if there are any changes affecting your project.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Search date-range widget replaced](#search-date-range-widget-replaced)
- [Content metadata property panels](#content-metadata-property-panels)
- [Authentication and SSO renames](#authentication-and-sso-renames)
- [JS-API integrated into the monorepo](#js-api-integrated-into-the-monorepo)
- [Viewer close button](#viewer-close-button)
- [Notification history reverted](#notification-history-reverted)
- [Extension configuration](#extension-configuration)
- [Constructor signature changes](#constructor-signature-changes)
- [Theme reference variables](#theme-reference-variables)
- [New components and features](#new-components-and-features)
- [Behavioural changes](#behavioural-changes)
- [Theme changes](#theme-changes)
- [Notable internal changes](#notable-internal-changes)
## Library updates
Update the `package.json` file with the latest library versions:
```json
{
"dependencies": {
"@alfresco/adf-core": "6.6.0",
"@alfresco/adf-content-services": "6.6.0",
"@alfresco/adf-process-services": "6.6.0",
"@alfresco/adf-process-services-cloud": "6.6.0",
"@alfresco/adf-insights": "6.6.0",
"@alfresco/adf-extensions": "6.6.0",
"@alfresco/js-api": ">=7.5.0"
}
}
```
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`, then reinstall:
```sh
npm install
```
## Breaking changes
### Search date-range widget replaced
The simple from-to `date-range` search widget was replaced by the tabbed advanced date-range widget:
- The old `SearchDateRangeComponent` (a `SearchWidget` with `from`/`to` controls, selector `adf-search-date-range`) was **removed**.
- The advanced components were **renamed**: `SearchDateRangeAdvancedComponent` → `SearchDateRangeComponent`
and `SearchDateRangeAdvancedTabbedComponent` → `SearchDateRangeTabbedComponent`. Update TypeScript imports
accordingly. Note that `SearchDateRangeComponent` now refers to a **different class** than before.
- The `date-range-advanced` widget selector was **removed**; the `date-range` selector now resolves to
`SearchDateRangeTabbedComponent`.
**What to change in your `search.config` / `app.config.json`:**
- Replace `"selector": "date-range-advanced"` with `"selector": "date-range"`.
- Existing `"selector": "date-range"` filters now render the tabbed widget. Migrate their settings — `field`
now supports a comma-separated list (one tab per field), and add `displayedLabelsByField`:
```json
"component": {
"selector": "date-range",
"settings": {
"field": "cm:created",
"dateFormat": "dd-MMM-yy",
"maxDate": "today",
"displayedLabelsByField": { "cm:created": "Created Date" }
}
}
```
`dateFormat` now defaults to `dd-MMM-yy` when omitted. Date-range i18n keys were reorganised — re-check any overrides.
Every filter widget in the filter panel now gets default **Clear** / **Apply** buttons via a new
`SearchFilterCardComponent` wrapper (`adf-search-filter-card`), which adds an extra element between the
expansion panel and `adf-search-widget-container` — review custom CSS/E2E selectors.
### Content metadata property panels
`[ContentMetadataComponent](../../lib/content-services/src/lib/content-metadata/components/content-metadata/content-metadata.component.ts)`
was reworked so each panel (General Info, Tags, Categories, and each aspect group) is independently
expandable and editable. Consequently:
- **`ContentMetadataComponent.editable` `@Input` was removed and replaced by `@Input() readOnly` (default `false`)** —
note the inverted meaning. Migrate `[editable]="x"` to `[readOnly]="!x"`.
- **`ContentMetadataCardComponent`** lost its `@Output() editableChange` and the `toggleEdit()` / `toggleExpanded()` methods.
- `BaseCardView` (core) gained `@Input() editable = false`; `InfoDrawerComponent` gained `@Input() icon: string | null`.
- The `CardViewGroup` and `ContentMetadataCustomPanel` interfaces gained optional `expanded?` (and `editable?` on the group).
### Authentication and SSO renames
Several public authentication members were renamed as part of adding PKCE (authorization-code) flow support:
| Before | After |
| ---------------------------------------------- | ---------------------------------------------------------- |
| `LoginComponent.implicitFlow` (property) | `LoginComponent.ssoLogin` |
| `LoginComponent.redirectToImplicitLogin()` | `LoginComponent.redirectToSSOLogin()` |
| `OidcAuthenticationService.ssoImplicitLogin()` | `OidcAuthenticationService.ssoLogin(redirectUrl?: string)` |
- New `app.config.json` OAuth2 key **`oauth2.codeFlow`** enables the PKCE authorization-code flow (set
`implicitFlow: false` + `codeFlow: true`). A new Docker env var `APP_CONFIG_OAUTH2_CODE_FLOW` maps to it.
- The app-config JSON schema file was renamed from `schema.json` to **`app.config.schema.json`**. The OAuth2
config now forwards the whole `oauth2` object to `angular-oauth2-oidc`, so additional keys (`oidc`, `issuer`,
`postLogoutRedirectUri`, `silentRefreshRedirectUri`, `silentRefreshTimeout`, `dummyClientSecret`,
`skipIssuerCheck`, `strictDiscoveryDocumentValidation`) are now recognised and passed through.
### JS-API integrated into the monorepo
`@alfresco/js-api` source now lives inside the ADF monorepo (`lib/js-api`) and is published at `7.5.0`. The
**package name and import specifier are unchanged** (`import { … } from '@alfresco/js-api'`). However, a number
of Activiti / AGS / Search / Content **model classes were converted to interfaces** to reduce bundle size —
code that used `new SomeModel()` or `instanceof SomeModel` on those models must switch to plain-object usage.
### Viewer close button
`ViewerComponent` and `AlfrescoViewerComponent` gained a configurable close-button position:
- New exported enum `CloseButtonPosition { Right = 'right', Left = 'left' }`.
- New `@Input() closeButtonPosition: CloseButtonPosition` (default `CloseButtonPosition.Left`) and `@Input() hideInfoButton: boolean` (default `false`).
- **The close button's `data-automation-id` changed** from `adf-toolbar-back` to `adf-toolbar-left-back`
(with a new `adf-toolbar-right-back`). Update any tests/selectors targeting `adf-toolbar-back`.
### Notification history reverted
The read/unread notification model introduced in the 6.5.x line was **reverted** in 6.6.0. Relative to 6.5.2:
- The exported `NOTIFICATION_STORAGE` constant was removed; the storage key is again the static field
`NotificationHistoryComponent.NOTIFICATION_STORAGE`.
- `NotificationModel.read` and `NotificationHistoryComponent.unreadNotifications` were removed.
- "Mark as read" again clears the notification list (rather than flagging items as read).
If you adopted the 6.5.x read/unread API, revert those usages.
### Extension configuration
`ExtensionService` can now also receive inline `ExtensionConfig` values, not just JSON file names. This
changed some signatures:
- New provider factory `provideExtensionConfigValues(values: ExtensionConfig[])` and injection token `EXTENSION_JSON_VALUES`.
- `ExtensionService` constructor gained the injected `EXTENSION_JSON_VALUES` argument (the token has a default,
so DI apps are unaffected; manual instantiation/tests must pass the extra array).
- `ExtensionLoaderService.load(...)` gained an optional 4th `extensionValues?: ExtensionConfig[]` parameter.
### Constructor signature changes
These services gained new constructor dependencies (only relevant if you instantiate them manually or in tests):
- `ContentService` (+ optional `ThumbnailService`)
- `TagService`, `CategoryService` (+ `AppConfigService`)
- `DialogAspectListService` (+ `TagService`, `CategoryService`)
- `PropertyGroupTranslatorService` (`NotificationService` replaced by `LogService`)
### Theme reference variables
Alongside the new design tokens (see [Theme changes](#theme-changes)), a theme refactor repointed many
existing `--adf-*` custom properties from static `$adf-ref-*` reference variables to Material palette lookups,
and **deleted several `$adf-ref-*` variables** from `_reference-variables.scss`. Consumers who overrode those
internal SCSS reference variables directly are affected — override the public `--adf-*` CSS custom properties instead.
## New components and features
- **Tabbed date-range search** — the `date-range` widget is now a tabbed component supporting ANY / IN LAST /
BETWEEN ranges, per-field tabs, per-field labels (`displayedLabelsByField`), and default Clear/Apply actions
(`SearchFilterCardComponent`). A new `TabLabelsPipe` (`tabLabels`) is exported.
- **Content-metadata property panels** — a new standalone `ContentMetadataHeaderComponent`
(`adf-content-metadata-header`) and per-panel expand/edit state; the info drawer can show a node icon; new
`ContentService` helpers (`getNodeIcon`, `isSmartFolder`, `isRuleFolder`, `isLinkFolder`).
- **Disable tags / categories** — new `app.config.json` keys `plugins.tags` and `plugins.categories` (default
`true`); `TagService.areTagsEnabled()` / `CategoryService.areCategoriesEnabled()`; a new
`AspectListComponent` `@Input() excludedAspects: string[]`; and an optional `SearchCategory.rules.visible` for
conditional search-category visibility.
- **Document list column persistence** — `[DocumentListComponent](../content-services/components/document-list.component.md)`
gained setter inputs `setColumnsVisibility`, `setColumnsWidths`, `setColumnsOrder` and outputs
`columnsVisibilityChanged`, `columnsWidthChanged`, `columnsOrderChanged`, so a host app can persist and
restore column configuration.
- **Drag-drop column reordering** — the `DocumentListPresetRef` config gained `draggable?: boolean`; disabled
columns are skipped as drop targets.
- **Resizable task/process lists** — `TaskListComponent` and `ProcessInstanceListComponent` gained
`@Input() isResizingEnabled` (default `false`) and `@Input() blurOnResize` (default `true`).
- **Viewer close-button position** — see [Viewer close button](#viewer-close-button).
- **Inline extension config** — `provideExtensionConfigValues([...])` (see [Extension configuration](#extension-configuration)).
- **Icon column cell** — the `icon` data-table column type is now rendered by a dedicated `IconCellComponent`
with value validation and tooltip support.
- **Tag validation** — creating a tag now blocks illegal characters (`' : " \ | < > / ?`) with an inline error.
- **Design tokens** — new themeable `--adf-*` properties for `PeopleCloudComponent`, `GroupCloudComponent`,
`TaskAssignmentFilterCloudComponent`, and `ProcessHeaderCloudComponent` (see [Theme changes](#theme-changes)).
## Behavioural changes
| Area | Change |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Auth (basic) | On app load, an invalid/stale ECM ticket now triggers an automatic logout (`onLogout`) instead of a false "logged-in" state. |
| Auth (js-api) | `invalidateSession()` on a 401 only fires when js-api owns authentication (avoids spurious invalidation under ADF-managed OAuth). |
| Auth (upload) | The `multipart/form-data` header is preserved when the body is a real `FormData` (fixes descriptor import in HXP). |
| Forms | Radio widgets update the form value immediately on selection. |
| Viewer | The PDF viewer works over plain HTTP (no `crypto.randomUUID`), and `AlfrescoViewerComponent` shows the original file's mime type icon. |
| Data table | Column headers show a tooltip with the (translated) column title. |
| Search | The search-properties facet clear button now actually clears the underlying query. |
## Theme changes
New themeable CSS custom properties were added for several cloud components (defaults derive from the Material
theme palette):
- **People cloud** — `--adf-people-cloud-input-label-default-color`, `--adf-people-cloud-input-label-focus-color`, `--adf-people-cloud-autosuggest-result-active-color`, `--adf-people-cloud-autosuggest-result-disabled-color`, `--adf-people-cloud-input-caption-error-color`.
- **Group cloud** — the `--adf-group-cloud-*` equivalents of the above.
- **Task assignment filter** — `--adf-task-assignment-filter-option-default-color`, `--adf-task-assignment-filter-option-selected-color`, `--adf-task-assignment-filter-label-default-color`, `--adf-task-assignment-filter-label-focus-color`.
- **Process header** — `--adf-process-header-cloud-card-background`.
A new `--theme-warn-color-a700` theme color was added (used for stronger warning text/borders, e.g. in the
share dialog). See also [Theme reference variables](#theme-reference-variables) for the removed `$adf-ref-*` internals.
## Notable internal changes
- `@alfresco/js-api` was moved into the monorepo (`lib/js-api`) and published at `7.5.0`; the public import
path is unchanged.
- Numerous `!important` declarations were removed from component styles (toolbar, pagination, permission list,
card-view date item, version list, task form, add-permission panel, etc.) — low impact, but review custom
overrides that relied on the old specificity.
docs/upgrade-guide/upgrade66-671.md
+230
View File
@@ -0,0 +1,230 @@
---
Title: Upgrading from ADF v6.6.0 to v6.7.1
---
# Upgrading from ADF v6.6.0 to v6.7.1
This guide provides instructions on how to upgrade your v6.6.0 ADF projects to v6.7.1 (covering the
6.7.0 and 6.7.1 releases).
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup.
Do not skip this task if you want your application to be updated to the most recent version of ADF.
Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates.
After the upgrade, check the other sections below to see if there are any changes affecting your project.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Angular Material CSS classes](#angular-material-css-classes)
- [Tags and categories config keys renamed](#tags-and-categories-config-keys-renamed)
- [Content metadata property panel API](#content-metadata-property-panel-api)
- [Card view methods are now getters](#card-view-methods-are-now-getters)
- [REGEX card-view validator inverted](#regex-card-view-validator-inverted)
- [Version list infinite scroll](#version-list-infinite-scroll)
- [Authentication changes](#authentication-changes)
- [Data table sorting and resizing](#data-table-sorting-and-resizing)
- [Viewer extension projection](#viewer-extension-projection)
- [Task list service](#task-list-service)
- [Other breaking changes](#other-breaking-changes)
- [New components and features](#new-components-and-features)
- [Behavioural changes](#behavioural-changes)
- [Theme changes](#theme-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-process-services": "6.7.1",
"@alfresco/adf-process-services-cloud": "6.7.1",
"@alfresco/adf-insights": "6.7.1",
"@alfresco/adf-extensions": "6.7.1",
"@alfresco/js-api": ">=7.5.0"
}
}
```
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`, then reinstall:
```sh
npm install
```
## Breaking changes
### Angular Material CSS classes
A large refactor (~130 files) removed all references to **Angular Material internal CSS classes** (`.mat-*`,
`.cdk-*`) from ADF component styles, in preparation for the Material MDC migration. ADF SCSS now styles its own
`adf-*` host classes instead. A stylelint rule was added to forbid `mat-`/`material-`/`cdk-` selector prefixes.
**Consumer impact:** because ADF components use `ViewEncapsulation.None`, their old `.mat-*` overrides leaked
globally. If your app relied on those leaked overrides, or targeted `.mat-*` inside ADF components, restyle
against the new `adf-*` host classes. Concrete removals to be aware of:
- `CategoriesManagementComponent.addCategoryToAssign()` signature changed from `(change: MatSelectionListChange)`
to `(category: Category)` — the only hard TypeScript break in this commit.
- `content-user-info` dropped its environment `mat-tab-group` (`#tab-group-env`, `.adf-userinfo-tab`, `.adf-hide-tab`).
- `content-node-selector` removed its "headless tabs" mode (`.adf-content-node-selector-headless-tabs`).
- `sites-dropdown.component.scss` was deleted.
### Tags and categories config keys renamed
The `app.config.json` keys that enable/disable the tags and categories features (introduced in 6.6.0) were
**renamed**:
| Before (6.6.0) | After (6.7.x) |
| -------------------- | --------------------------- |
| `plugins.tags` | `plugins.tagsEnabled` |
| `plugins.categories` | `plugins.categoriesEnabled` |
Update your `app.config.json`, or the flags silently fall back to their `true` default. The methods
`TagService.areTagsEnabled()` and `CategoryService.areCategoriesEnabled()` are unchanged.
### Content metadata property panel API
`ContentMetadataComponent` was refactored so only one panel edits at a time, replacing the per-panel
(General Info / Tags / Categories / group) state introduced in 6.6.0. Many public members were **removed**:
- Removed methods include `canExpandTheCard`, `onToggleGeneralInfoEdit`, `onToggleTagsEdit`,
`onToggleCategoriesEdit`, `onToggleGroupEdit`, `onSaveGeneralInfoChanges`, `onSaveTagsChanges`,
`onSaveCategoriesChanges`, `onSaveGroupChanges`, `isEditingPanel`, and the `onCancel*Edit` methods.
- Removed fields/getters include `isGeneralPanelExpanded`, `isTagPanelExpanded`, `isCategoriesPanelExpanded`,
`currentGroup`, `isEditingModeGeneralInfo/Tags/Categories`, `canEditGeneralInfo`, `isEditingGeneralInfo`,
`canEditTags`, `isEditingTags`, `canEditCategories`, `isEditingCategories`, `hasGroupToggleEdit`,
`isGroupToggleEditing`, `tagNameControlVisible`, `categoryControlVisible`.
- They are replaced by a unified API: fields `editing`, `editedPanelTitle`, `currentPanel`, an exposed
`DefaultPanels` enum, and methods `isPanelEditing()`, `saveChanges()`, `toggleGroupEditing()`,
`cancelGroupEditing()`, `expandPanel()`, `closePanel()`, `resetEditing()`.
- A new `ContentMetadataPanel { panelTitle: string; expanded?: boolean }` interface was added, and
`ContentMetadataCustomPanel` now extends it.
- **`CardViewGroup.editable` became a required property** (was optional) — constructing `CardViewGroup` literals now requires `editable`.
The `@Input`/`@Output`/selector of `ContentMetadataComponent` are unchanged.
### Card view methods are now getters
To remove redundant function calls from templates, several card-view members changed from **methods to getters**.
Drop the parentheses in any custom code/templates calling them:
- `CardViewArrayItemComponent`: `showClickableIcon`, `displayCount`, `isClickable`.
- `CardViewDateItemComponent`: `showProperty`, `showClearAction`.
- `CardViewMapItemComponent`: `showProperty`, `isClickable`.
### REGEX card-view validator inverted
`CardViewItemMatchValidator` (the `REGEX` card-view constraint) gained a `requiresMatch?` parameter, and its
default semantics **inverted**: with `requiresMatch` falsy, a value that **matches** the pattern is now treated
as **invalid** (used to express forbidden-character patterns for e.g. folder names). Existing REGEX constraints
that expected "match means valid" must now set `requiresMatch: true`. The validator's `flags` are now forwarded
from config as well.
### Version list infinite scroll
`VersionListComponent` now loads versions lazily in batches via CDK virtual scroll:
- **The public `versions: VersionEntry[]` property was removed.** Use `latestVersion: VersionEntry` (or the new
`versionsDataSource`) instead — e.g. `versionList.versions[0].entry` becomes `versionList.latestVersion?.entry`.
- A new abstract `InfiniteScrollDatasource<T>` and `VersionListDataSource` are exported from
`@alfresco/adf-content-services`; `VersionManagerModule` now imports `@angular/cdk/scrolling`.
### Authentication changes
- **Code-flow infinite loop fix** — the OIDC login callback is now driven by `OidcAuthGuard` (root-provided) on
the `view/authentication-confirmation` route rather than by `AuthenticationConfirmationComponent`. As a result:
- `AuthService.loginCallback()` signature changed to `loginCallback(loginOptions?: LoginOptions)`.
- `OidcAuthGuard` constructor gained `Router`; its `canActivate`/`canActivateChild` no longer take route/state args.
- `AuthModuleConfig` gained `preventClearHashAfterLogin?: boolean` (defaults to `true`).
- **`requireAlfTicket` auto-wiring moved to content-services** — the automatic ECM ticket fetch after OAuth login
was moved out of `@alfresco/adf-core` into a new `ContentAuthLoaderService` `APP_INITIALIZER` in
`@alfresco/adf-content-services`. `BasicAlfrescoAuthService.requireAlfTicket()` still exists in core, but apps
that import **only** `@alfresco/adf-core` (not `ContentModule`) no longer get the automatic fetch — import
`ContentModule.forRoot()` or call `requireAlfTicket()` yourself on `authService.onLogin`.
- **`nonceStateSeparator`** is now set to `'~'` in the OIDC `AuthConfig` (fixes login with IdPs sensitive to the state/nonce separator).
### Data table sorting and resizing
- **Sorting default changed** — `ObjectDataTableAdapter.sort()` and `DataSorting` now use `String.localeCompare`
with `Intl.CollatorOptions` and **`{ numeric: true }` by default** (both gained an optional `options?: Intl.CollatorOptions`
parameter). Numeric and date columns may sort differently than in 6.6.0.
- **Columns are resizable by default** — `DataColumn` / `DataColumnComponent` gained a `resizable` flag that
**defaults to `true`** (`DocumentListPresetRef.resizable?` too). Set `resizable="false"` per column to opt out.
- `DataTableComponent.isResizing` is now a read-only getter (was a mutable field).
### Viewer extension projection
Custom viewer extension templates are now projected explicitly instead of via the old `externalExtensions` push:
- `ViewerComponent` / `AlfrescoViewerComponent` accept the extensions through a `#viewerExtensions` template ref
(`@ContentChild`) / `@Input() viewerExtensions: TemplateRef<any>`.
- `ViewerExtensionDirective` now populates `extensionsSupportedByTemplates` rather than `externalExtensions`.
- `ViewerRenderComponent` constructor gained an `Injector` parameter (affects manual instantiation).
### Task list service
`TaskListService` (`@alfresco/adf-process-services`):
- The public method `findAllTasksWithoutState()` was **removed**.
- `findAllTaskByState()` was **renamed to `findAllTasksByState()`** (note the extra "s").
The `all` state is now handled by `findTasksByState` (it applies to both open and completed tasks).
### Other breaking changes
- `FormCloudComponent` constructor gained a `DisplayModeService` dependency (see [Full-screen task forms](#new-components-and-features)); `FormRepresentationModel.displayMode` was added.
- `FormFieldModel`'s `value` setter no longer calls `updateForm()` when the value is unchanged.
- `WidgetVisibilityModel.leftType` / `rightType` return type widened to `string | null`.
## New components and features
- **Decimal form widget** — a new `DecimalWidgetComponent` (selector `adf-decimal`) renders `bigdecimal`
fields (new `FormFieldTypes.DECIMAL = 'bigdecimal'`), backed by a `DecimalFieldValidator` and a new
`FormFieldModel.precision` property. Registered automatically by the form rendering service.
- **Full-screen user task forms** — `FormCloudComponent` and `TaskFormCloudComponent` gained
`@Input() displayModeConfigurations` and `@Output() displayModeOn` / `displayModeOff`, backed by a new
`DisplayModeService` and `FormCloudDisplayMode { inline, fullScreen }` — forms can switch between inline and full-screen.
- **Dynamic chip list** — a new standalone `DynamicChipListComponent` (`adf-dynamic-chip-list`, with a `Chip`
interface) is exported from `@alfresco/adf-core`; `TagNodeListComponent` now delegates its chip rendering to it.
- **Unsaved-changes dialog / guard** — new `UnsavedChangesDialogComponent` and `UnsavedChangesGuard`
(`CanDeactivate`) exported from `@alfresco/adf-core`.
- **Group service** — `GroupService` gained `getGroup()` and `updateGroup()` (the js-api `Group`/`GroupBodyUpdate`
models gained an optional `description`).
- **Resizable columns by default** and **per-column `resizable`** config (see [Data table sorting and resizing](#data-table-sorting-and-resizing)).
- **Storage prefix factory** — a new `STORAGE_PREFIX_FACTORY_SERVICE` injection token and `StoragePrefixFactory`
let apps supply a dynamic `StorageService` prefix (the `application.storagePrefix` app-config value still takes precedence).
- **Header design tokens** — new themeable `--adf-header-icon-button-*` CSS custom properties (see [Theme changes](#theme-changes)).
## Behavioural changes
| Area | Change |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Card view dates | `date`-type card-view values are now displayed timezone-agnostically (stored at UTC midnight), fixing off-by-one-day display; new `DateFnsUtils.forceLocal` / `forceUtc` helpers. Custom `d:date` aspect strings no longer crash the app. |
| Card view text item | Non-editable text items render as `readonly` (not `disabled`) with a corrected clickable area; `update()` is a no-op when not editable. |
| Aspect list | The aspect dialog no longer overwrites node aspects it doesn't display; hidden aspects are preserved and included in `valueChanged`. |
| Document list | Size / Modified-by columns re-render correctly after editing properties; nodes are deleted sequentially; declared records hide the "Edit Offline" / "Upload New Version" actions. |
| Search | The search filter panel no longer shows duplicated Clear/Apply buttons for the date-time widget; tab content re-displays correctly after switching tabs. |
| Tags | Creating a tag validates against illegal characters; a to-be-created tag can be removed without clearing the "already exists" error. |
| Forms | Required people/groups widgets keep the submit button disabled while empty; integer "greater than" visibility conditions work. |
## Theme changes
`HeaderLayoutComponent` gained themeable CSS custom properties for its icon buttons:
- `--adf-header-icon-button-default-color`
- `--adf-header-icon-button-default-border-radius`
- `--adf-header-icon-button-hover-color`
- `--adf-header-icon-button-pressed-color`
- `--adf-header-icon-button-disabled-color`
More broadly, the Material-CSS-class removal (see [Angular Material CSS classes](#angular-material-css-classes))
means ADF no longer ships overrides of Material internals — theme ADF components through their `adf-*` classes
and documented CSS custom properties.
docs/upgrade-guide/upgrade671-68.md
+172
View File
@@ -0,0 +1,172 @@
---
Title: Upgrading from ADF v6.7.1 to v6.8.0
---
# Upgrading from ADF v6.7.1 to v6.8.0
This guide provides instructions on how to upgrade your v6.7.1 ADF projects to v6.8.0.
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup.
Do not skip this task if you want your application to be updated to the most recent version of ADF.
Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates.
After the upgrade, check the other sections below to see if there are any changes affecting your project.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Removed global helper classes and !important](#removed-global-helper-classes-and-important)
- [Standalone component conversions](#standalone-component-conversions)
- [Search provider changes](#search-provider-changes)
- [Form rendering and widget changes](#form-rendering-and-widget-changes)
- [Data table column sizing](#data-table-column-sizing)
- [Viewer changes](#viewer-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.8.0",
"@alfresco/adf-content-services": "6.8.0",
"@alfresco/adf-process-services": "6.8.0",
"@alfresco/adf-process-services-cloud": "6.8.0",
"@alfresco/adf-insights": "6.8.0",
"@alfresco/adf-extensions": "6.8.0",
"@alfresco/js-api": ">=7.5.0"
}
}
```
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`, then reinstall:
```sh
npm install
```
## Breaking changes
### Removed global helper classes and !important
A `declaration-no-important` stylelint rule was introduced and `!important` was removed from ADF component
styles across ~74 files. As part of this:
- The SCSS partial `_default-class.scss` was **deleted**, removing the global helper classes
**`.adf-hide-small`** and **`.adf-hide-xsmall`**. If your app used these ADF-provided classes to hide
elements at small/extra-small breakpoints, define your own equivalents.
- No ADF component CSS class was renamed, but consumer CSS that previously depended on ADF rules winning
via `!important` may now behave differently due to specificity — review your overrides.
### Standalone component conversions
Several component sets were converted to `standalone: true` and now import the specific Angular Material
modules they need instead of the monolithic `MaterialModule`: **About**, **Toolbar**, **Context Menu**, and
**Pagination**.
For normal consumers this is **non-breaking** — the corresponding NgModules (`AboutModule`, `ToolbarModule`,
`ContextMenuModule`, `PaginationModule`) are retained with unchanged exports, and import paths are unchanged.
The one thing to fix: if your own NgModule **declared** any of these ADF components (which was never
correct), you must now **import** them instead, since a standalone component cannot be declared.
Notes:
- `ContextMenuListComponent` is now publicly exported (and exported by `ContextMenuModule`) — additive.
- `AboutRepositoryInfoComponent` now uses `ViewEncapsulation.None`, so its styles are no longer encapsulated.
### Search provider changes
- `ContentNodeSelectorPanelComponent.queryBuilderService` changed from **public to private**, and the panel
no longer provides `SearchQueryBuilderService` under the `SEARCH_QUERY_SERVICE_TOKEN` (it provides the class
directly). Code reading `panel.queryBuilderService`, or injecting `SEARCH_QUERY_SERVICE_TOKEN` from the
panel's injector scope, must inject `SearchQueryBuilderService` directly.
- `SearchQueryBuilderService`'s constructor gained a third, `@Optional()` parameter for the new
`ADF_SEARCH_CONFIGURATION` token (see [New components and features](#new-components-and-features)) — DI usage
is unaffected; only manual instantiation with a third positional argument is impacted.
### Form rendering and widget changes
- **`FormRendererComponent`** constructor gained a `FORM_FIELD_MODEL_RENDER_MIDDLEWARE` dependency (used by the
new decimal-precision middleware). Relevant only if you instantiate it manually.
- **`DecimalWidgetComponent`** lost its public `displayValue` property and no longer implements `OnInit` — the
precision rounding moved to a render middleware.
- **`FormFieldModel.validate()`** now also validates read-only fields whose type is "validatable" (currently the
new display-external-property type), via a new `isFieldValidatable()`. Read-only fields of other types still skip validation.
- `FormCloudComponent.parseForm(json?)` signature changed — the argument is optional and the return type is now
`FormModel | null` (returns `null` for empty form JSON). Adjust strict-typed callers.
### Data table column sizing
Column widths were reworked to be responsive again (they broke with the 6.7.x "resizable by default" change):
- The column style binding uses the `flex` shorthand; the datatable exposes `getFlexValue(col): string`
returning `'0 1 <width>px'`. A new `.adf-datatable-cell-data` CSS class is applied to header and body cells,
and the **last column** is intentionally left flexible (no fixed flex, no resize handle) so it absorbs remaining width.
- The header drag-icon placeholder element was removed — any test/selector using the automation id
`adf-datatable-cell-header-drag-icon-placeholder-<key>` must be updated.
### Viewer changes
- `ViewerRenderComponent.cacheTypeForContent` default changed from `''` to `'no-cache'`.
- `AlfrescoViewerComponent` now refreshes the preview based on the node's **version** property rather than the
file name; the image viewer's cropper now replaces on `urlFile` change (was `fileName`). Consumers relying on
a name-only refresh should be aware of this.
## New components and features
- **Injectable search configuration** — a new `ADF_SEARCH_CONFIGURATION` injection token
(`@alfresco/adf-content-services`) lets you provide a `SearchConfiguration` at runtime that takes priority
over the `search` node of `app.config.json`:
```ts
providers: [
{ provide: ADF_SEARCH_CONFIGURATION, useValue: { /* SearchConfiguration */ } }
]
```
- **Simple search input** — a new standalone `SearchInputComponent` (selector `adf-search-input`) formats user
input into an AFTS query and emits it via `@Output() changed`. Inputs: `value`, `label`, `placeholder`,
`fields` (default `['cm:name']`). It formats only; it does not run the search.
- **Category selector dialog** — a new `CategorySelectorDialogComponent` (`adf-category-selector-dialog`) with a
`CategorySelectorDialogOptions { select: Subject<Category[]>; multiSelect?: boolean }`, opened via
`MatDialog.open(...)`. `CategoriesManagementComponent` gained an `@Input() multiSelect` (default `true`).
- **Search exports and projection** — many previously-internal search symbols are now exported (e.g.
`SearchFacetChipComponent`, `SearchWidgetChipComponent`, `SearchFilterTabDirective`, `FileSizeOperator`,
`DateRangeType`, `SearchDateRange`, and more), and `SearchFilterChipsComponent` now supports content
projection via `<ng-content>`.
- **Display external property widget** — a new cloud form widget `DisplayExternalPropertyWidgetComponent`
(selector `adf-cloud-display-external-property`, new `FormFieldTypes.DISPLAY_EXTERNAL_PROPERTY = 'display-external-property'`), auto-registered by `CloudFormRenderingService`. `FormFieldModel` gained an
optional `externalProperty?: string`.
- **Form field render middleware** — a new `FORM_FIELD_MODEL_RENDER_MIDDLEWARE` token and
`FormFieldModelRenderMiddleware` interface let you transform fields at render time; `DecimalRenderMiddlewareService`
uses it to round incoming `bigdecimal` values to the field's `precision`.
- **Constant field types** — `FormFieldTypes.CONSTANT_VALUE_TYPES` / `isConstantValueType()`; fields of these
types keep their design-time value and are not overridden by process/form variables.
- **Form preview state** — `FormService.getPreviewState()` (returns `false` by default); in preview mode the
attach-file widget now shows a warning instead of opening the file dialog.
- **OIDC-compliant logout** — new optional `oauth2` keys in `app.config.json`: `logoutUrl`,
`logoutParameters` (e.g. `["client_id", "returnTo", "response_type"]`), and `audience` (forwarded as a custom
query param, for Auth0-style providers). Absolute (`http`-prefixed) `redirectUri` values are now honored
verbatim. New Docker env vars include `APP_CONFIG_OAUTH2_LOGOUT_URL`, `APP_CONFIG_OAUTH2_LOGOUT_PARAMETERS`,
`APP_CONFIG_OAUTH2_AUDIENCE`, `APP_CONFIG_OAUTH2_CLIENT_SECRET`, `APP_CONFIG_OAUTH2_SCOPE`.
- **Custom-UI auth flow type** — the process-services-cloud `Descriptor` model gained an optional
`customUIAuthFlowType?: DescriptorCustomUIAuthFlowType` (`CODE` | `IMPLICIT`).
- **Image zoom on wheel** — the image viewer now zooms with the mouse wheel.
## Behavioural changes
| Area | Change |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Forms — dates | Date widgets display the same day regardless of timezone (`DateFnsUtils.forceLocal`/`forceUtc` reimplemented). The datetime picker now opens on Enter rather than on focus. A non-required datetime field with a `null` value no longer triggers spurious Min/Max validation. |
| Forms — decimal | Incoming `bigdecimal` values are rounded to the field's configured `precision` at render time. |
| Content metadata | The "no items" message shows only for editable groups when not editing; property-panel tabs no longer change background color on focus. |
| Viewer | The viewer reliably reloads after a version restore and the toolbar no longer disappears. |
| Version list | Long version comments are truncated with an ellipsis and shown in full via a hover tooltip. |
| Tooltip card | The `adf-tooltip-card` directive no longer throws when its overlay reference is undefined. |
docs/upgrade-guide/upgrade68-69.md
+185
View File
@@ -0,0 +1,185 @@
---
Title: Upgrading from ADF v6.8 to v6.9
---
# Upgrading from ADF v6.8 to v6.9
This guide provides instructions on how to upgrade your v6.8.0 ADF projects to v6.9.0.
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup.
Do not skip this task if you want your application to be updated to the most recent version of ADF.
Upgrades of multiple versions of ADF cannot be done in one step only, but should follow the chain of sequential updates.
After the upgrade, check the other sections below to see if there are any changes affecting your project.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Removed components and directives](#removed-components-and-directives)
- [DataTable and DocumentList API cleanup](#datatable-and-documentlist-api-cleanup)
- [DataTable multiselect checkbox id](#datatable-multiselect-checkbox-id)
- [Removed / deprecated modules (standalone migration)](#removed--deprecated-modules-standalone-migration)
- [Data table form widget: JSON paths](#data-table-form-widget-json-paths)
- [Constructor and DI changes](#constructor-and-di-changes)
- [Other breaking changes](#other-breaking-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.9.0",
"@alfresco/adf-content-services": "6.9.0",
"@alfresco/adf-process-services": "6.9.0",
"@alfresco/adf-process-services-cloud": "6.9.0",
"@alfresco/adf-insights": "6.9.0",
"@alfresco/adf-extensions": "6.9.0",
"@alfresco/js-api": ">=7.5.0"
}
}
```
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`, then reinstall:
```sh
npm install
```
## Breaking changes
### Removed components and directives
The following long-deprecated items were **removed**. There is no drop-in replacement — remove any usage:
| Removed | Kind | Selector | Package |
| --------------------------------------------------------- | ---------------------------- | ------------------------------- | -------------------- |
| `LikeComponent` | Component | `adf-like` | adf-content-services |
| `RatingComponent` | Component | `adf-rating` | adf-content-services |
| `RatingService`, `RatingServiceInterface`, `SocialModule` | Service / Interface / Module | — | adf-content-services |
| `WebscriptComponent` | Component | `adf-webscript-get` | adf-content-services |
| `WebScriptModule` | Module | — | adf-content-services |
| `FolderCreateDirective` | Directive | `[adf-create-folder]` | adf-content-services |
| `FolderEditDirective` | Directive | `[adf-edit-folder]` | adf-content-services |
| `FolderDirectiveModule` | Module | — | adf-content-services |
| `CardViewContentProxyDirective` | Directive | `[adf-card-view-content-proxy]` | adf-core |
| `ProcessNamePipe` | Pipe | — | adf-process-services |
| `ProcessServicesPipeModule` | Module | — | adf-process-services |
| `SecurityControlsServiceModule` | Module (empty) | — | adf-content-services |
The folder directives were moved into the demo-shell only — if you used `[adf-create-folder]` /
`[adf-edit-folder]`, port an equivalent into your own app.
### DataTable and DocumentList API cleanup
Deprecated API was removed from `DataTableComponent` (`adf-datatable`) and `DocumentListComponent`
(`adf-document-list`). The **"gallery" display mode no longer exists** — both always render as a list.
- **Removed** `@Input() display` from both components, and the exported `DisplayMode` enum
(`{ List, Gallery }`). Remove any `[display]="'gallery'"` / `[display]="'list'"` bindings.
- **Removed** `DataTableComponent` public methods `iconAltTextKey()`, `hasSelectionMode()`, `getSortingKey()`,
and the `fakeRows` property.
- **Removed** the `NavigableComponentInterface` interface; `DocumentListComponent` no longer implements it.
### DataTable multiselect checkbox id
The per-row selection checkbox in `adf-datatable` now uses an **index-suffixed id** instead of a static one,
fixing an accessibility regression that also caused clicking a row's checkbox to select the wrong row:
```html
<!-- before --> <mat-checkbox id="select-file" ...>
<!-- after --> <mat-checkbox [id]="'select-file-' + idx" ...> <!-- select-file-0, select-file-1, ... -->
```
Any test/CSS selector targeting `#select-file` (or `[for="select-file"]`) must migrate to the indexed form
(`#select-file-0`, …).
### Removed / deprecated modules (standalone migration)
Many components, pipes and directives were converted to **standalone**. In most cases the owning NgModule is
retained (now marked `@deprecated`) with unchanged exports, so importing consumers are unaffected — but you
should migrate to importing the standalone symbol directly. Deprecated-but-retained modules include:
`AppConfigModule`, `DirectiveModule`, `PipeModule` (core); `IconModule`, `TemplateModule`, `AppsListModule`
(process); `ContentPipeModule` (content).
Real breaks in this effort:
- **`TemplateModule` (core) no longer re-exports `MatButtonModule`.** If you relied on `TemplateModule`
transitively providing `mat-button`, import `MatButtonModule` yourself.
- `ProcessNamePipe` and `ProcessServicesPipeModule` were **deleted** (see the table above).
- New exported convenience symbols: `CORE_PIPES` (core), `CONTENT_PIPES` (content), and `TooltipCardComponent`
is now publicly exported.
- **`LogService` (`@alfresco/adf-core`) is now `@deprecated`** — the class still works but is slated for removal.
This is the counterpart to the constructor cleanup below (several services stopped injecting it this release);
migrate off `LogService` in your own code.
### Data table form widget: JSON paths
The cloud form **Data Table widget** now resolves data via JSON paths, which changes how column configuration
is interpreted:
- `WidgetDataTableAdapter` no longer **extends** `ObjectDataTableAdapter` — it now **implements**
`DataTableAdapter` (composition), and its constructor arguments `(data, schema)` are now **required**. Code
depending on it being an `ObjectDataTableAdapter` instance must adapt.
- A column's **`key` is now interpreted as a JSON path** into each data item. Keys containing `.` or `[...]`
are parsed as paths rather than literal property names. New supported syntaxes: bracket notation for keys
with special characters (`data['non.standard key']`), nested objects inside arrays, and single array-index
access (`orders[2].customer.name`; a single trailing `[n]` per segment — `[0][1]` is not supported).
- For process/task list **variable columns**, the variable map is now keyed by column **`id`** (previously by
`title`). Ensure each variable column has a correct, unique `id`.
### Constructor and DI changes
`LogService` (and some other dependencies) were removed from several constructors — this only affects code that
manually instantiates these classes or subclasses them and calls `super(...)`:
- `BaseAuthenticationService` — constructor is now `protected` and no longer takes `LogService`; subclasses
`BasicAlfrescoAuthService` and `OidcAuthenticationService` drop it from `super(...)` too.
- `IdentityRoleService`, `ClipboardService`, `DropdownSitesComponent`, `AlfrescoViewerComponent`,
`UploadButtonComponent` — no longer inject `LogService`.
- `AspectListService` — `LogService` was replaced by `AppConfigService` in the constructor.
- `ContentNodeSelectorPanelComponent` — no longer injects `AppConfigService`; its `queryBuilderService` is
private. The `adf-content-node-selector.sorting` app-config key is no longer read (default sort is
`['createdAt', 'desc']`).
- `FormCloudComponent` — constructor gained a `FormCloudSpinnerService` dependency.
- `DisplayRichTextWidgetComponent` — constructor gained a `DomSanitizer` dependency.
### Other breaking changes
- **`ContentNodeShareModule.forRoot()` / `.forChild()` were removed** — import `ContentNodeShareModule` directly.
- `TaskDetailsComponent` (`adf-task-details`) removed the `@Input() debugMode` and the public methods
`isShowAttachForm()` and `isTaskActive()`; `TaskHeaderComponent` removed the public `inEdit` field.
- `FormRendererComponent` no longer implements `OnChanges` (its rules manager now initialises once in `ngOnInit`).
## New components and features
- **Form spinner event** — a new `FormSpinnerEvent` / `FormSpinnerEventPayload` (`@alfresco/adf-core`) and a
`FormService.toggleFormSpinner` subject let application code show/hide an overlay spinner over a cloud form:
```ts
this.formService.toggleFormSpinner.next(new FormSpinnerEvent(type, { showSpinner: true, message }));
```
- **Widget error output** — the base `WidgetComponent` gained an `@Output() widgetError`, inherited by all form widgets.
- **Aspect list counter** — `AspectListComponent` gained an `@Output() updateCounter: EventEmitter<number>`, emitted whenever the number of selected aspects changes.
- **Start process cancel button** — `StartProcessCloudComponent` gained an `@Input() showCancelButton` (default `true`).
- **Accessibility** — a repo-wide accessibility lint pass added keyboard handlers (`tabindex`, `role`,
`keyup.enter`), `aria-*` attributes, and `for`/`id` label associations across many components.
- **Data table JSON paths** — see [Data table form widget: JSON paths](#data-table-form-widget-json-paths).
## Behavioural changes
| Area | Change |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DataTable | Multiselect row selection via checkbox now selects the correct row; column resizing works with multiselect enabled; small-window/mobile layouts no longer leave empty space. |
| Forms | Cloud form variables resolve static values from the component `data` input in start-event forms; the date widget handles negative range values; the rich-text display widget no longer emits a stray comma (content is now sanitised). |
| Folder dialog | The Create/Update button disables on first click to prevent duplicate folder-creation requests. |
| Version list | Layout fixes ensure action buttons (restore/download) remain visible and are not clipped off-screen. |
| Aspects dialog | The selected-aspects counter now updates correctly on select/deselect/reset/clear, and dialog buttons stay visible. |
docs/upgrade-guide/upgrade69-70.md
+407
View File
@@ -0,0 +1,407 @@
---
Title: Upgrading from ADF v6.9 to v7.0
---
# Upgrading from ADF v6.9 to v7.0
This guide provides instructions on how to upgrade your v6.9.0 ADF projects to v7.0.0.
**v7.0.0 is a major release.** It moves ADF across three Angular major versions (**14 → 17**) — including the
Angular Material **MDC migration** — upgrades **rxjs 6 → 7**, requires **`@alfresco/js-api` v8**, switches the
test runner to **Jest**, and completes a large **standalone-component migration**. Expect real work: audit your
Material CSS overrides, update import paths for moved/removed symbols, and align your own Angular/tooling versions.
Because 7.0.0 was released through a chain of alpha builds, this guide is organised into a
[shared overview](#major-platform-changes) followed by a [per-release section](#changes-by-release) for each
intermediate tag (`7.0.0-alpha.2`, `-alpha.3`, `-alpha.4`, `-alpha.6`, `-alpha.7`, and the final `7.0.0`).
Apply them in order.
> **Note on alpha.5:** there is no `7.0.0-alpha.5` tag. Its changes were released as part of `7.0.0-alpha.6`
> and are documented under that heading.
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Since this
is a major version with many breaking changes, budget time to build, run, and re-test your application after upgrading.
## Contents
- [Library updates](#library-updates)
- [Major platform changes](#major-platform-changes)
- [Changes by release](#changes-by-release)
- [7.0.0-alpha.2](#700-alpha2)
- [7.0.0-alpha.3](#700-alpha3)
- [7.0.0-alpha.4](#700-alpha4)
- [7.0.0-alpha.6](#700-alpha6)
- [7.0.0-alpha.7](#700-alpha7)
- [7.0.0 (final)](#700-final)
## Library updates
Update the `package.json` file with the latest library versions:
```json
{
"dependencies": {
"@alfresco/adf-core": "7.0.0",
"@alfresco/adf-content-services": "7.0.0",
"@alfresco/adf-process-services": "7.0.0",
"@alfresco/adf-process-services-cloud": "7.0.0",
"@alfresco/adf-insights": "7.0.0",
"@alfresco/adf-extensions": "7.0.0",
"@alfresco/js-api": ">=8.0.0"
}
}
```
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`, then reinstall:
```sh
npm install
```
## Major platform changes
These changes accumulate across the alpha chain but affect every consumer of 7.0.0:
| Area | 6.9.0 | 7.0.0 |
| ------------------------ | ------------- | ---------------- |
| Angular | 14.1.3 | **17.1.3** |
| Angular Material / CDK | 14.1.2 | **17.1.2** (MDC) |
| rxjs | 6.6.6 | **7.8.1** |
| zone.js | 0.11.4 | **0.14.8** |
| TypeScript | 4.7.4 | **5.3.3** |
| Nx | `@nrwl/*` 14 | **`@nx/*` 20** |
| `angular-oauth2-oidc` | 13 | **17** |
| `@alfresco/js-api` | 7.5 | **>= 8.0.0** |
| Test runner | Karma/Jasmine | **Jest** |
| Node.js (`engines.node`) | >= 6.0.0 | **>= 18.0.0** |
Key consumer implications:
- **Angular Material MDC migration** — Angular Material's components were rewritten onto MDC, changing their
internal DOM and CSS class names (`.mat-*` → `.mat-mdc-*`). If your application styles Material internals
(directly or by overriding ADF component styles), you must re-audit those styles. This is the single biggest
source of visual breakage.
- **Accessibility / DOM & roles** — beyond the MDC class changes, ADF's accessibility pass altered DOM and ARIA in
several components: Material tooltips became the native `[title]` attribute, search facet chips moved from
`mat-chip-option` to `mat-chip`, `role` attributes changed on the DataTable and Columns Selector, and the Aspect
List HTML structure changed. Re-check any tests or CSS keyed off these roles/structure.
- **Node 18** — the repository's `engines.node` was raised from `>= 6.0.0` to `>= 18.0.0`; move your build/CI to Node 18+.
- **rxjs 7** — adopt rxjs 7 (`firstValueFrom`/`lastValueFrom` instead of `toPromise`, stricter operator typings).
- **js-api v8** — ADF requires `@alfresco/js-api` `>= 8.0.0`.
- **Jest** — ADF's own tests moved from Karma/Jasmine to Jest. If your test setup extends ADF testing utilities,
migrate to Jest.
- **Standalone components** — most ADF components, directives and pipes are now `standalone`. Many NgModules were
removed or deprecated; import the standalone symbols (or the exported `*_DIRECTIVES` const arrays) directly.
- **Date handling** — date pipes/adapters are date-fns based; the legacy moment-based pipes are removed (see 7.0.0 final).
- **`ng update`** — where migrations are provided, run `ng update @alfresco/adf-core@7.0.0` to apply automated fixes.
## Changes by release
### 7.0.0-alpha.2
The Angular **14 → 15** step and the **Material MDC migration**.
**Platform / dependencies**
- Angular and Material `14 → 15.2`; the MDC migration rewrites hundreds of component stylesheets.
- rxjs `6.6 → 7.8`; TypeScript `4.7 → 4.9`; Nx (still `@nrwl`) `14 → 15`; `@alfresco/js-api` → `8.0.0-alpha`.
- Date handling moves to a **date-fns adapter**: new `AdfDateFnsAdapter`, `AdfDateTimeFnsAdapter`, and
`ADF_DATE_FORMATS` (wired to `DateAdapter` / `MAT_DATE_FORMATS`).
**Breaking removals / renames / moves**
- `ButtonsMenuComponent` **moved** from `@alfresco/adf-core` to `@alfresco/adf-insights`.
- `AuthModule` is **no longer exported from the `@alfresco/adf-core` root** — import it from the auth entry point.
- Removed pipes: `BooleanPipe`, `IsIncludedPipe`, `TabLabelsPipe` (core). Removed `AuditService`.
- Removed About items: `AboutGithubLinkComponent`, `AboutPlatformVersionComponent`, and `AaeInfoService`;
`AboutModule` is deprecated in favour of an exported `ABOUT_DIRECTIVES` array.
- Removed public directives `PeopleSearchActionLabelDirective` and `PeopleSearchTitleDirective` (process-services);
removed the insights analytics `WidgetComponent` export; removed `SortingPickerModule`; the extensions
`AppExtensionServiceMock` is no longer exported.
- Removed the standalone date/datetime **form-field validators** from `FORM_FIELD_VALIDATORS` and the public
exports (`DateFieldValidator`, `DateTimeFieldValidator`, and the `Boundary`/`Min`/`Max` date & datetime
variants) — date/datetime validation moved into Angular reactive-form validators.
- The `content-user-info` and `process-user-info` components, and `CoreAutomationService`, were **moved to the
demo shell** (no longer part of the libraries).
- The shared `MaterialModule` is deprecated/removed from several libraries; stop depending on it and import the
specific Angular Material modules you need.
- `process-services` public API restructured — `people-process.service`, `apps-process.service`,
`task-comments.service` now live under `lib/services`. **Note:** `BpmUserModel`, `UserProcessModel`,
`ProcessInstance`, `ProcessInstanceVariable`, `FilterRepresentationModel`, `FilterParamsModel` and
`AppDefinitionRepresentationModel` were **not removed** — they are retained as `@deprecated` type aliases to the
equivalent `@alfresco/js-api` types (via `lib/compat/types`). Migrate to the js-api types. However,
`TaskDetailsModel` and `StartTaskModel` **were removed outright** (their model file was deleted and no
`@deprecated` alias is provided) — switch to the equivalent `@alfresco/js-api` task types (e.g. `TaskRepresentation`).
Likewise removed outright with no alias: `ProcessListModel`, `TaskListModel`, `FilterProcessRepresentationModel`,
`ProcessFilterParamRepresentationModel`, `ProcessFilterRequestRepresentation` and `TaskQueryRequestRepresentationModel`
— move to the equivalent `@alfresco/js-api` types.
- **Removed process-services directives:** `TaskAuditDirective` and `NoTaskDetailsTemplateDirective`
(`@alfresco/adf-process-services`, previously exported from `task-list`) were removed — drop the usages.
- Card-view validator filenames were corrected (`*.valiator.ts` → `*.validator.ts`) — this breaks deep-path
imports of those files (the barrel export is unaffected).
**Standalone / module changes**
- Wide standalone migration across core, content-services, extensions, insights and process-services; many
NgModules (card-view, content-type, node-comments, site-dropdown, form, apps-list, attachment, task-list,
dynamic-table, sorting-picker, dynamic-chip-list, and more) were deleted. Several modules were replaced by
exported directive arrays: `ANALYTICS_PROCESS_DIRECTIVES` (insights), `ABOUT_DIRECTIVES`, `FORM_DIRECTIVES`,
`APPS_LIST_DIRECTIVES`, `ATTACHMENT_DIRECTIVES` (process-services), `EXTENSION_DIRECTIVES` (extensions).
`ExtensionsModule` is deprecated (its `forChild()` remains as a deprecated shim).
- Some standalone components also moved to nested folders, breaking deep-path imports (e.g. `StartFormComponent`
→ `.../form/start-form/start-form.component`; the attachment components).
- "Break dependency on Material Module" work means Layout/DataTable/Form components self-import only the Material
pieces they use.
**New features**
- New standalone core UI components: `AvatarComponent`, `ButtonComponent`, `ProgressComponent`, and a new
`header` entry point (`HeaderComponent`, `NavbarComponent`, `NavbarItemComponent`). New `AlfrescoIconComponent`
(`adf-alfresco-icon`) in content-services.
- New generic `DialogComponent` (core `dialogs`) that can return data on confirmation; new `ConfirmDialogModule`;
new `DIALOG_COMPONENT_DATA` injection token + `DialogData.componentData` so embedded dialog components can receive injected data.
- New card-view `long` type (`CardViewLongItemModel`, `CardViewItemLongValidator`, `CardViewItemPositiveLongValidator`).
- New exported form helpers: `FieldOptionType`, `FieldSelectionType`, `FieldAlignmentType`,
`FormFieldTypes.REACTIVE_TYPES` + `isReactiveType()`, `FormFieldModel.markAsValid()`, `DEFAULT_DATE_FORMAT`,
`FormOutcomeModel.skipValidation`, and `FormRendererComponent` `@Input() readOnly`.
- New `@Input()`s: `ViewerComponent`/`ViewerRenderComponent`/`PreviewExtensionComponent` `nodeId` (custom viewer
extensions receive the node id); `PeopleCloudComponent` `hideInputOnSingleSelection`, `formFieldAppearance`,
`formFieldSubscriptSizing`, `showErrors`; `SearchWidgetContainerComponent` `useHeaderQueryBuilder` (constructor
also drops `SearchQueryBuilderService` and adds `Injector`).
- DataTable `@Input() displayCheckboxesOnHover` (default `false`); `DocumentListService.reload()` / `reload$`.
- New content-services feature areas: **Legal Hold**, **Predictions API**, and a **feature-flags** library. New Form Header widget and viewer file-rotation support.
- Insights packaging: `chart.js`, `ng2-charts`, `raphael`, `@alfresco/adf-core` and `@ngx-translate/core` moved
from `peerDependencies` to `dependencies`.
**Behavioural**
- `matTooltip` was replaced by the native `[title]` attribute across ~96 templates (accessibility) — tooltip
timing/position inputs no longer apply where replaced.
- **DATE and DATETIME widgets migrated to Angular reactive forms.** Dropdown/radio REST options are now fetched
only when `optionType === 'rest'` (previously any `restUrl` triggered a fetch), and read-only dropdown/radio
widgets no longer call REST APIs or show validation errors.
- Date/time widgets became timezone-aware; a `token_received` event is emitted on login; `PdfViewerComponent`
disables pdf.js `isEvalSupported` (security); the tree-view component was marked for deprecation.
### 7.0.0-alpha.3
Auth and js-api relocation.
**Platform / dependencies**
- `angular-oauth2-oidc` `13 → 15`; `axios` pinned as a direct dependency; peer ranges opened to js-api `8.0.0-alpha`.
**Breaking removals / renames / moves**
- **`AlfrescoApiService` (and `AlfrescoApiServiceMock`) moved from `@alfresco/adf-core` to
`@alfresco/adf-content-services`.** Update your imports. An `ng update` migration
(`updateAlfrescoApiImports`, run via `ng update @alfresco/adf-core@7.0.0`) rewrites these automatically. The
related `AlfrescoApiLoaderService`, `AlfrescoApiNoAuthService` and the `createAlfrescoApiInstance` factory are
now exported from content-services, and the API-initialising `APP_INITIALIZER` moved from `CoreModule` to
`ContentModule` — make sure your app imports `ContentModule`.
- `ExtensionService.setAuthGuards()` / `getAuthGuards()` signatures changed to `Record<string, unknown>` /
`Array<unknown>` (aligns with the functional guards).
- **Auth route guards are now functional `CanActivateFn` values**, not injectable classes: `AuthGuard`,
`AuthGuardBpm`, `AuthGuardEcm`, `AuthGuardSsoRoleService`, `OidcAuthGuard`. The base class **`AuthGuardBase`
was deleted**, and a new `SHELL_AUTH_TOKEN` injection token was added. Route configs and any subclasses must migrate.
- Removed: `DirectionalityConfigService` (folded into `UserPreferencesService`); pipes `MimeTypeIconPipe`,
`LocalizedRolePipe`, `FilterOutEveryObjectByPropPipe`; the `setupTestBed` test helper.
**Standalone / testing ergonomics**
- New `NoopAuthModule` and `NoopTranslateModule` (core testing) to simplify consumer test beds.
**New features**
- **Knowledge Retrieval / Search-AI**: new `AgentService` and `SearchAiService` (content-services).
- New `@Output() updatedFilter` (`EventEmitter<string>`) on process/task filter cloud components (a distinct
emitter on each); new `@Output() rowsSelected` on `ProcessListComponent`; form/widget styling support (new
`predefined-theme` export, `PredefinedThemeModel`); new OAuth config keys `clockSkewInSec` and `sessionChecksEnabled`.
- `StartProcessCloudService.getStartEventConstants(appName, processDefinitionId)` — start/cancel buttons can now be
customised from process-definition constants; `StartProcessCloudComponent` `@Output() error` type changed to `EventEmitter<any>`.
- `RichTextEditorComponent` gained `@Input() placeholder` and `@Input() autoFocus`.
- `DROPDOWN` was added to `FormFieldTypes.REACTIVE_TYPES` (dropdowns now bind/validate via reactive forms;
`DropdownCloudWidgetComponent` is now standalone). `ProcessCommentsComponent` was simplified (its `@Output() error` was removed).
### 7.0.0-alpha.4
The Angular **15 → 16** step.
**Platform / dependencies**
- Angular and Material `15 → 16.2`; `zone.js → 0.13`; **Nx package scope renamed `@nrwl/* → @nx/*` (16)**;
`angular-oauth2-oidc 15 → 16`; chart.js 4; ng-packagr 16.
**Breaking removals / renames**
- Removed `FilterStringPipe` (core). Columns-selector now filters in the component.
- `DisplayModeService` methods widened from the `FormCloudDisplayMode` enum to `string` (to allow a `standalone`
display mode and custom modes) — relax enum-typed callers to `string`.
- **Process/task filter counters changed shape** — the public `counters$: { [key]: Observable<number> }` on
`ProcessFiltersCloudComponent` / `BaseTaskFiltersCloudComponent` was **removed** and replaced by a synchronous
`counters: { [key]: number }` (plus a new `initFilterCounters()` method). Templates using `counters$ | async` must migrate.
- The abstract `AuthService` gained abstract members `onLogout$: Observable<void>` and
`isDiscoveryDocumentLoaded$: Observable<boolean>` — custom `AuthService` implementations must implement them.
`OidcAuthenticationService` gained public `shouldPerformSsoLogin$`.
**New tokens / API**
- New `TASK_SEARCH_API_METHOD_TOKEN` (`'GET' | 'POST'`) enabling the new POST task-search endpoint (Activiti ≥ 8.7).
In `'POST'` mode `TaskListCloudComponent` honours new `string[]` inputs `names`, `processDefinitionNames`,
`statuses`, `assignees`, `priorities`, `completedByUsers`; new exports `TaskListRequestModel`,
`TaskFilterCloudAdapter`, `ProcessTaskListCloudService`, and `TaskListRequestTaskVariableFilter`.
- New `JWT_STORAGE_SERVICE` token so consumers can supply custom OAuth storage to `JwtHelperService`.
**New features**
- **Saved Search** (ADW): new `SavedSearchesService` and `SavedSearch` interface (content-services `common`).
- `VersionListComponent` / `VersionManagerComponent` gained `@Input() allowVersionDelete`, `allowViewVersions`
and `showActions` (all default `true`); `NewVersionUploaderDialogData` gained the matching optional fields; the
version list now uses a virtual-scroll viewport.
- New `refreshFilter(filterKey)` on process/task filter components; new `FormService.onFormVariableChanged`;
`StartProcessCloudComponent` gained `@Input() displayModeConfigurations`.
**Behavioural**
- Auth infinite-loop / clock-skew rework: new internal `RetryLoginService`, `TimeSyncService`, and a
`TokenInterceptor` (HTTP interceptor) — the user is now logged out after 3 failed login attempts. Re-test SSO flows.
### 7.0.0-alpha.6
(There was no `alpha.5` tag; those changes are included here.) **No framework version bumps in this window** —
the changes are API/feature-level.
**Breaking removals / renames**
- Removed `ProcessTaskListCloudService` from the process-list public API entry point.
- Renamed exported const `RUNNING_STATUS → DEPLOYED_STATUS`; `AppListCloudComponent` now queries `DEPLOYED` apps.
The related method `getRunningApplications()` was renamed to `getDeployedApplications()` on
`EditProcessFilterCloudComponent` and `BaseEditTaskFilterCloudComponent`.
- `TaskListRequestModel.variableKeys` (and `ProcessListRequestModel.variableKeys`) renamed to `processVariableKeys`;
`TaskListRequestModel` gained an optional `processInstanceId`.
- `ContainerModel` methods became getters: `isGroup()` → getter `isTypeFieldGroup`; `isCollapsible()`/
`isCollapsedByDefault()` → getters (drop the `()`); new getter `hideHeader`.
- **Constructor changes** (affect manual instantiation/subclassing): `PermissionListComponent` now requires
`ContentService` (and exposes a new `updatePermissionsAllowed` getter); `SidenavLayoutComponent` now requires
`ChangeDetectorRef`; `TaskHeaderComponent` gained `CardViewUpdateService`.
- The Saved Searches storage file changed from `saved-searches.json` to `config.json` (existing saved searches
won't be found until re-saved).
**New features**
- New **process search API**: `ProcessListRequestModel`, `ProcessFilterCloudAdapter`, `ProcessListCloudService.fetchProcessList()`,
and a `PROCESS_SEARCH_API_METHOD_TOKEN` (`'GET' | 'POST'`); `getProcessByRequest()` is now `@deprecated`.
New `ProcessListCloudComponent` inputs `names`, `initiators`, `appVersions`, `statuses` (POST mode).
- DataTable: `DataRow.isSelectable?`, and drag-to-reorder rows via `@Input() enableDragRows` / `@Output() dragDropped`.
- CardView autocomplete support (`CardViewSelectItemModel.autocompleteBased`).
- `TaskHeaderComponent` gained `@Input() readOnly` and `@Input() resetChanges` (a `Subject<void>`); the Assignee
field became an inline-editable autocomplete (re-assignable when assigned to the current user).
**Behavioural**
- `DataTableSchema.isColumnSchemaCreated$` now backed by a `BehaviorSubject` (emits an initial `false`, both
branches emit `true`) — relevant if you subclass `DataTableSchema`.
- Large internal migration to Angular's `takeUntilDestroyed` (128 files) — relevant if you subclass these components.
- Kerberos no longer adds a basic-auth header; CSRF header now respects the `disableCsrf` flag.
### 7.0.0-alpha.7
Standalone migration of `process-services-cloud`, plus new libraries.
**Platform / dependencies**
- `angular-oauth2-oidc 16 → 17`; new `graphql-ws` dependency. Angular remains 16.2 in this window.
- `@alfresco/adf-core` peer dependencies were **pinned to exact Angular 16.2.9** — align your peers accordingly.
**Breaking removals / renames / moves**
- **The `@alfresco/adf-testing` library (`lib/testing`) was removed entirely.** Remove any imports from it.
- `TaskFormCloudComponent` moved to a nested path (`./components/task-form-cloud/task-form-cloud.component`) —
deep imports break; the package entry-point export is preserved.
- Tag creator components were consolidated (a transforming pipe and styles removed).
- **Removed pipes/directives** (`process-services-cloud`): `ProcessNameCloudPipe` (together with its
`ProcessServicesCloudPipeModule`), `InitialGroupNamePipe`, and `CancelProcessDirective` (from
`ProcessDirectiveModule`) were removed — verified gone at 7.0.0. Drop the usages or switch to the standalone
equivalents.
- **Start-Task-Cloud removed:** `StartTaskCloudComponent`, `StartTaskCloudService` and `StartTaskCloudModule`
(`@alfresco/adf-process-services-cloud`) were removed entirely (present at `alpha.6`, gone at `alpha.7`).
- **Identity DI-override tokens removed:** `IDENTITY_USER_SERVICE_TOKEN` and `IDENTITY_GROUP_SERVICE_TOKEN` were
removed; the `IdentityUserServiceInterface` / `IdentityGroupServiceInterface` types moved to
`@alfresco/adf-core` (`auth/interfaces`). Re-point any custom identity-service provider.
- **Deprecated:** `TaskListCloudService.getTaskByRequest()` (and the `TaskListCloudServiceInterface` member) is now
`@deprecated` — use `fetchTaskList()` (mirrors the `getProcessByRequest()` deprecation in alpha.6).
**Standalone / module changes**
- Broad standalone migration of `process-services-cloud`: many NgModules were removed or reduced
(`ProcessDirectiveModule`, `TaskDirectiveModule`, `StartTaskCloudModule`, `StartProcessCloudModule`,
`ProcessCommonModule`, the cloud `material.module`, and others). Import the standalone components/directives directly.
**New features**
- **Screens**: new `ScreenRenderingService` and `UserTaskCloudComponent` (process-services-cloud).
- New `WebSocketService` (Apollo/graphql-ws); `NotificationCloudService` refactored onto it.
- `truncate` pipe now exported from core; new `Truncate` display option for text `DataColumn`; new optional
`DataColumn.subtitle`; new `@Input() showProvidedActions` (default `false`) on `DataTableComponent`,
`ProcessListCloudComponent` and `BaseTaskListCloudComponent`.
- People widget multi-select (`field.params.multiple`); `adfLocalizedDate` pipe gains a `timezone` argument;
`ObjectDataTableAdapter` server/client `SortingMode`.
- New exported `ReactiveFormWidget` interface (`{ updateReactiveFormControl(); formService }`); `FormRulesManager.onDestroy$` opened to `protected`.
- `NodesApiService` gained `initiateFolderSizeCalculation(nodeId)` and `getFolderSizeInfo(nodeId, jobId)` (backing the folder size-details dialog).
- New model fields: `ApplicationInstanceModel.canAccessAudit`; `ServiceTaskQueryCloudRequestModel` gained
completed/started date-range fields; new `ScreenCloudComponent` + `UserTaskCustomUi` interface.
- `AppsProcessCloudService.getDeployedApplicationsByStatus` signature changed (`role?: string` → `roles?: string | string[]`).
**Behavioural**
- **Required inputs are now enforced across ~55 components** (~66 inputs) in core, content-services,
process-services and process-services-cloud — `@Input()` became `@Input({ required: true })`. Affected
components include `NameColumnComponent`, `TreeViewComponent`, `VersionComparisonComponent`,
`VersionUploadComponent`, `CommentListComponent`, `NodeCommentsComponent`, `TaskHeaderComponent`,
`BreadcrumbComponent`, `CategoriesManagementComponent`, `ContentMetadataComponent`/`ContentMetadataCardComponent`,
`ContentNodeSelectorPanelComponent`, the library/permission/tag/search-facet/card-view/datatable components,
and many more. Any template that omits one of these inputs now fails to compile — audit your templates.
- `onLogout` is emitted when redirected to the login page; `ProcessFilterOperators` adds `'ne'`.
### 7.0.0 (final)
The Angular **16 → 17** step and the Jest migration.
**Platform / dependencies**
- Angular and Material `16 → 17.1`; TypeScript `5.3`; zone.js `0.14`; Nx `20`; `apollo-angular 6`.
- **Test runner migrated from Karma/Jasmine to Jest.**
- Rich-text editor dependencies bumped (several `@editorjs/*` majors); font-size dependency swapped to `@valano/change-font-size`.
**Breaking removals / renames**
- **`MomentDatePipe` and `MomentDateTimePipe` were removed** — migrate to the date-fns based date pipe/adapter.
- `FullNamePipe.transform` gained an optional `emailDisplayed?: boolean` argument (backward compatible; appends `<email>` when true).
- `FormModel` constructor gained a 7th optional `injectedFieldValidators?` argument, and its `fieldValidators`
default is now populated via injected validators.
**New features**
- New injection tokens for pluggable form validators: `FORM_SERVICE_FIELD_VALIDATORS_TOKEN` and
`FORM_CLOUD_SERVICE_FIELD_VALIDATORS_TOKEN` — provide `FormFieldValidator[]` app-wide.
- New `SAVED_SEARCHES_SERVICE_PREFERENCES` token + `SavedSearchesPreferencesApiService`; **Saved Searches now
persist via the Preferences API**.
- Screens: new `lib/screen` public API (`UserTaskCustomUi` model) with full-screen support.
- Form sections rendered at runtime (`FormSectionComponent`); new public `UnitTestingUtils` test helper.
- New public export `DEFAULT_LANGUAGE_LIST` (`core/common`); `DocumentListComponent` `@Input() displayDragAndDropHint`
(default `true`); `FormBaseComponent` getter `hasVisibleOutcomes`.
- `CardViewBaseItemModel` gained `isValidValue?` (and now skips unsupported constraint types with a `console.warn`
instead of throwing); `ContentMetadataComponent` gained `invalidProperties` and disables the save button while any property is invalid.
- `RequiredFieldValidator` now also supports the `ALFRESCO_FILE_VIEWER` and `PROPERTIES_VIEWER` widget types.
**Behavioural**
- **Service-tasks API data shape changed** — `ServiceTaskListCloudComponent` now unwraps `entries.map(t => t.entry)`;
consumers reading raw service-task rows must unwrap `.entry`.
- Submit/start button state is now computed from validators across cloud form/task/start-process components.
- `CommentsComponent` moved to a reactive `commentControl` and disables the add button for whitespace-only comments.
- The required-field asterisk is now toggled via CSS `visibility` (not `*ngIf`) across ~27 widget templates —
a DOM change if you key off the asterisk element's presence.
- Re-verify custom Material MDC themes and rich-text-editor integrations against Angular 17.
docs/upgrade-guide/upgrade70-80.md
+243
View File
@@ -0,0 +1,243 @@
---
Title: Upgrading from ADF v7.0 to v8.0
---
# Upgrading from ADF v7.0 to v8.0
This guide provides instructions on how to upgrade your v7.0.0 ADF projects to v8.0.0.
**v8.0.0 is a major release.** It moves ADF from Angular **17 to 19** (via internal 18 → 19 steps), upgrades
**`@ngx-translate/core` to v16** and **`@alfresco/js-api` to v9**, upgrades **pdf.js from 3.x to 5.x**, and
performs a large **theming clean-up** (the prebuilt themes and the ADF colour/variable SCSS partials are removed).
Budget time to migrate your Angular version, your theme, your i18n bootstrap, and your PDF viewer worker asset.
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Because this is
a major version with many breaking changes, build, run and re-test your application after upgrading.
## Contents
- [Library updates](#library-updates)
- [Major platform changes](#major-platform-changes)
- [Breaking changes](#breaking-changes)
- [Angular 19 and standalone](#angular-19-and-standalone)
- [Internationalisation (i18n)](#internationalisation-i18n)
- [Theming clean-up](#theming-clean-up)
- [PDF viewer (pdf.js 5)](#pdf-viewer-pdfjs-5)
- [Viewer components](#viewer-components)
- [API signature and model changes](#api-signature-and-model-changes)
- [Constructor / DI changes](#constructor--di-changes)
- [Removed roles and DOM hooks](#removed-roles-and-dom-hooks)
- [Deprecations](#deprecations)
- [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": "8.0.0",
"@alfresco/adf-content-services": "8.0.0",
"@alfresco/adf-process-services": "8.0.0",
"@alfresco/adf-process-services-cloud": "8.0.0",
"@alfresco/adf-insights": "8.0.0",
"@alfresco/adf-extensions": "8.0.0",
"@alfresco/js-api": ">=9.0.0",
"@ngx-translate/core": ">=16.0.0"
}
}
```
Clean your old distribution and dependencies by deleting `node_modules` and `package-lock.json`, then reinstall:
```sh
npm install
```
## Major platform changes
| Area | 7.0.0 | 8.0.0 |
| ----------------------------------- | ---------- | ----------------- |
| Angular / Material / CDK | 17.1 | **19.2** |
| TypeScript | 5.3 | **5.8.2** |
| zone.js | 0.14.8 | **0.15.0** |
| Nx | 20.0 | **20.8** |
| `@ngx-translate/core` | 14/15 | **>= 16.0.0** |
| `apollo-angular` / `@apollo/client` | 6.0 / 3.11 | **10.0.3 / 3.13** |
| `pdfjs-dist` | 3.3 | **5.1.91** |
| `@alfresco/js-api` | >= 8.0.0 | **>= 9.0.0** |
Angular Material remains on the **M2 (Material 2) theming APIs** in 8.0.0 — the Material Design 3 migration was
deferred. Move your own application to Angular 19 / TypeScript 5.8 / zone.js 0.15 / Nx 20.8 in lockstep, and
upgrade `apollo-angular` (a major bump) if you use GraphQL.
The declared `engines.node` floor is unchanged (`>=18.0.0`), but the version the libraries are **built and tested
on** moved from Node 20 to **Node 22** (`.nvmrc` `20.18.1` → `22.14.0`) — align your build/CI Node version.
## Breaking changes
### Angular 19 and standalone
- Migrate your application to Angular 19. Standalone is the default in Angular 19, so the redundant
`standalone: true` flags were dropped from ADF components. Any app NgModule that still **declares** ADF
components must import them as standalone instead.
### Internationalisation (i18n)
`@ngx-translate/core` v16 changed how translation is wired, and `CoreModule` was modernised:
- **`CoreModule` no longer re-exports `TranslateModule`.** Components that used the `translate` pipe via a
transitive `TranslateModule` must now import ngx-translate's standalone `TranslatePipe` (or provide translation
themselves).
- **`CoreModule.forRoot()` no longer auto-provides `MomentDateAdapter`, `TranslateStore`, or `TranslateService`**
(translation now uses `provideTranslateService`), and no longer re-exports `HttpClientModule` / the XSRF module
(HTTP is wired via `provideHttpClient(...)`). Provide these yourself if you depended on them transitively.
- Prefer the new standalone providers (see [New components and features](#new-components-and-features)):
`provideI18N(...)`, `provideAppConfig()`, `provideShellRoutes(...)` (`ShellModule` is deprecated),
`provideHttpClient()`.
### Theming clean-up
The ADF theming layer was significantly reduced (`AAE-34390`/`AAE-34439`/`AAE-34458`). This is the biggest
source of build/visual breakage for apps with custom themes:
- **Prebuilt themes were removed** — the `lib/core/src/lib/styles/prebuilt/*` themes (`adf-blue-orange`,
`adf-indigo-pink`, etc.) no longer ship. Replace any `@import '@alfresco/adf-core/prebuilt-themes/...'` with a
custom theme (`mat.define-palette` + `mat.define-light-theme` + `@include alfresco-material-theme($theme)`) or
an Angular Material prebuilt theme.
- **The colour / variable SCSS partials were deleted**: `_colors.scss` (palettes `$alfresco-ecm-blue`,
`$alfresco-accent-orange`, `$alfresco-warn`, the `$black-*/-white-*-opacity` helpers, …), `_reference-variables.scss`
(all `$adf-ref-*`), and `_components-variables.scss` (the `adf-components-variables($theme)` mixin). Redefine any
of these you referenced in your own theme.
- **Many `--adf-*` component CSS custom properties were removed** (card-view, info-drawer tabs, people/group-cloud,
header icon-button, edit-task/process-filter, package-list, about-*, identity-user-info, etc.) — these are no
longer overridable via CSS variables. A small set of metadata/error/secondary-button/chip/sidenav custom
properties is retained.
- **Removed mixins:** `adf-components-variables($theme)` and `adf-snackbar-theme`. The snackbar classes
`.adf-error-snackbar` / `.adf-warning-snackbar` / `.adf-info-snackbar` are no longer coloured by ADF — style them
in your app.
- **Default font changed** from `Muli` to `Roboto`.
- Form widgets no longer render a custom `.adf-asterisk` span for required fields (the native Material required
marker is used); a new `.adf-form-field-input` class was added, with placeholder-conditional `floatLabel`.
- Docs removed: `basic-theming.md`, `typography.md`, and the "using a prebuilt theme" section of `theming.md`.
### PDF viewer (pdf.js 5)
`pdfjs-dist` was upgraded from 3.x to **5.1.91**, which changes how the worker is loaded:
- The worker asset was renamed from `pdf.worker.min.js` to **`pdf.worker.min.mjs`**. Update your build's asset copy
(`node_modules/pdfjs-dist/build/pdf.worker.min.mjs`). The component now fetches the worker and loads it via a
Blob `workerPort` (to tolerate servers that return the wrong MIME type for `.mjs`).
- New overridable injection tokens `PDFJS_MODULE` and `PDFJS_VIEWER_MODULE`.
- pdf.js scale values are now strings (`isSameScale(oldScale: string, newScale: string)`), and the viewer container
now also carries the native `pdfViewer` class.
### Viewer components
- **`ViewerRenderComponent` `@Input() isLoading` was removed** — loading state is now managed internally and cleared
via child-renderer completion outputs / a new public `markAsLoaded()`. Remove any `[isLoading]` binding. Custom
viewer/preview-extension components should emit a `contentLoaded` output (new on `TxtViewerComponent` and
`PreviewExtensionComponent`; `imageLoaded`/`canPlay`/`pagesLoaded` on the built-in renderers) to clear the spinner.
- **`AlfrescoViewerComponent`** — `readOnly` is now a public `@Input()` (previously an internal permission-derived
field; the permission result moved to an internal `canEditNode`). New `@Input() showToolbarDividers` (also on core
`ViewerComponent`, which gained an `adf-viewer-inline` host class when not in overlay mode).
### API signature and model changes
- **`TagService.createTags(tags)`** now returns `Observable<TagEntry | TagPaging>` (was `Observable<TagEntry[]>`).
Read results via `result.list.entries[i].entry.tag`; import `TagPaging` from `@alfresco/js-api`. The `refresh`
output now emits the paging object.
- **`AspectListService` was reworked** — `getAspects()`, `getStandardAspects()` and `getCustomAspects()` were
removed/repurposed. `getAspects(whiteList, opts?)` now takes a whitelist and returns `AspectPaging` (not
`AspectEntry[]`); new `getAllAspects(...)` returns a new `CustomAspectPaging`. New exported `StandardAspectsWhere`
/ `CustomAspectsWhere`.
- **Knowledge Retrieval / Search-AI models changed** (`@alfresco/js-api`): `AiAnswer.questionId` → `question`,
`AiAnswer.references` → `objectReferences` (new `AiAnswerObjectReference`), new `AiAnswer.complete`;
`AiAnswerReference.referenceText` was replaced by `rank` / `rankScore`.
- **`FormBaseComponent.hasVisibleOutcomes` getter was removed** — outcome visibility now lives in a new exported
pure helper `isOutcomeButtonVisible(...)` (from the new `form/buttons-visibility` public export).
- **`UserTaskCloudComponent.taskCompleted`** now emits `boolean` (the "open next task" flag) instead of the task id
`string`; `TaskScreenCloudComponent.taskCompleted` / `UserTaskCustomUi.taskCompleted` were retyped.
- `WidgetComponent.isRequired()` return type narrowed from `any` to `boolean` (returns `false`, not `null`, when not required).
- **APS (classic) task-filter methods renamed**: `TaskFilterService.getInvolvedTasksFilterInstance` →
`getOverdueTasksFilterInstance`, `getQueuedTasksFilterInstance` → `getUnassignedTasksFilterInstance`; the default
filters changed from "Involved/Queued" to "Overdue/Unassigned" (existing user filters are auto-migrated on load).
- Dropdown form fields: `FormFieldModel.value` may now be the full option object `{ id, name }` rather than a string id.
### Constructor / DI changes
Only relevant if you manually instantiate or subclass these:
- `NodeFavoriteDirective` / `LibraryFavoriteDirective` constructors gained `NotificationService`.
- `AlfrescoApiLoaderService` constructor gained a `SecurityOptionsLoaderService` dependency.
### Removed roles and DOM hooks
Update e2e/CSS selectors:
- The datatable row checkbox no longer has `role="checkbox"` (use `data-adf-datatable-row-checkbox` / `[attr.aria-checked]`).
- The add-user/group search results no longer have `role="listbox"`.
- The viewer file-name spans `.adf-viewer__display-name-without-extension` / `-extension` were replaced by a single
span; a new public `ViewerComponent.displayName` (middle-ellipsised at 50 chars) is available.
## Deprecations
These still work in 8.0.0 but are slated for removal — migrate when you upgrade:
- **`ShellModule`** → use **`provideShell(opts?)`** (`@alfresco/adf-core/shell`), which takes
`{ routes, appService?, authGuard?, navBar? }` and wires the whole shell (see
[New components and features](#new-components-and-features)).
- **`FormBaseModule`** (`@alfresco/adf-core`) → import the standalone form components directly.
- **`CoreTestingModule`** (`@alfresco/adf-core`) → use the standalone components in your test beds.
- **`ProcessServicesCloudModule`** (`@alfresco/adf-process-services-cloud`) → import the standalone components
directly, or replicate the module with providers:
```ts
providers: [
provideTranslations('adf-process-services-cloud', 'assets/adf-process-services-cloud'),
provideCloudPreferences(),
provideCloudFormRenderer(),
{ provide: TASK_LIST_CLOUD_TOKEN, useClass: TaskListCloudService }
]
```
- **Dialog / snackbar NgModules** are now `@deprecated` — import the standalone component directly instead of the
module: `ConfirmDialogModule`, `EditJsonDialogModule`, `UnsavedChangesDialogModule`, `SnackbarContentModule`
(`@alfresco/adf-core`) and `DownloadZipDialogModule` (`@alfresco/adf-content-services`).
(The theming layer / prebuilt themes are covered under [Theming clean-up](#theming-clean-up).)
## New components and features
- **`provideI18N(config?)`** (core) — standalone i18n bootstrap: `provideI18N({ defaultLanguage: 'en', assets: [['app', '/assets/i18n']] })`. Wraps `provideTranslateService` + `provideTranslations` (both still available).
- **`provideShell(opts?)`** (`@alfresco/adf-core/shell`) — the recommended replacement for the deprecated
`ShellModule`; it takes `{ routes, appService?, authGuard?, navBar? }` and wires the whole shell (calling the
narrower **`provideShellRoutes(routes)`** helper internally). Plus **`provideAppConfig()`**,
**`provideCloudPreferences()`** and **`provideCloudFormRenderer()`** — standalone provider helpers.
- **`auth.withCredentials`** — a new `app.config.json` key (`AppConfigValues.AUTH_WITH_CREDENTIALS`) that controls the
HTTP `withCredentials` flag, so it can be disabled for identity providers that reject credentials. A new
`SecurityOptionsLoaderService` (content-services) applies it early during bootstrap.
- **New outputs / methods:** `CommentsComponent` / `NodeCommentsComponent` `@Output() commentAdded`;
`ProcessContentService.getContentRenditionTypePreview(contentId)`; `StorageService.getItems()`;
`TaskFilterService.updateTaskFilter(...)`.
- **Records management:** new `FilePlansApi.getFilePlanRoles(...)` plus `FilePlanRole*` models (js-api), used to verify legal-hold capabilities and hide the RM library join button when unauthorised.
- **Process / forms:** an "Open next task" checkbox for screen-based tasks (`UserTaskCloudComponent` /
`TaskScreenCloudComponent` gained `@Input() showNextTaskCheckbox`, `isNextTaskCheckboxChecked` and
`@Output() nextTaskCheckboxCheckedChanged`); `ProcessDefinitionCloud.constantValues` (new `ConstantValues` type);
`rootProcessInstanceId` propagated to dynamic task screens; the Data Table widget now renders empty tables and a
preview placeholder instead of erroring; `FormCloudComponent.showCompleteButton` input.
- **Categories dialog** now validates prohibited symbols (`: " \ | < > / ? *`) and trailing dots.
- Favorite directives now show snackbar notifications; the `<html lang>` attribute now updates on language change.
## Behavioural changes
| Area | Change |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Document list | Navigating to a new folder now resets the active `filterValue`; custom column visibility/order/width persist across refresh. |
| Forms | Hidden required dropdowns are no longer invalid; clearing a numeric field stores `null` (not `''`); required dropdowns show a single asterisk; async form enrichment now populates date fields and hides the spinner correctly; `onProcessFinish` fires reliably from `onFormLoaded`. |
| Content metadata | Content in non-edited panels stays visible while another panel is edited (new `isPanelEditing(panelTitle)` / `editedPanelTitle`). |
| Aspect list | All aspects are fetched (paged) when the first call doesn't return them all. |
| Viewer | Loading state is driven by renderer completion; PDF documents scale correctly; the image viewer is no longer cropped; the file name is truncated with a tooltip. |
| Accessibility | Loading bars/spinners gained aria labels; nested interactive controls were removed from the datatable; form tab navigation uses a focus trap. |
docs/upgrade-guide/upgrade80-811.md
+140
View File
@@ -0,0 +1,140 @@
---
Title: Upgrading from ADF v8.0 to v8.1.1
---
# Upgrading from ADF v8.0 to v8.1.1
This guide provides instructions on how to upgrade your v8.0.0 ADF projects to v8.1.1 (covering the 8.1.0 and
8.1.1 releases).
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The steps
below may involve code changes — commit or back up your work first.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Removed components, modules and exports](#removed-components-modules-and-exports)
- [Viewer title API](#viewer-title-api)
- [Node comments avatar service](#node-comments-avatar-service)
- [Translation key namespacing](#translation-key-namespacing)
- [Deprecations](#deprecations)
- [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": "8.1.1",
"@alfresco/adf-content-services": "8.1.1",
"@alfresco/adf-process-services": "8.1.1",
"@alfresco/adf-process-services-cloud": "8.1.1",
"@alfresco/adf-insights": "8.1.1",
"@alfresco/adf-extensions": "8.1.1",
"@alfresco/js-api": ">=9.1.1"
}
}
```
Angular, Material, TypeScript, zone.js and Nx are unchanged from 8.0.0 (Angular 19.2). Clean `node_modules` and
`package-lock.json`, then `npm install`.
## Breaking changes
### Removed components, modules and exports
The following public items were removed. Migrate away from them:
| Removed | Kind | Package | Migration |
| ---------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `RichTextEditorComponent` | Component (+ its module and all `@editorjs/*` deps) | `@alfresco/adf-process-services-cloud` | The rich-text **editor** moved to the HxP monorepo and no longer ships in ADF. (The read-only `DisplayRichTextWidgetComponent` remains.) |
| `AppConfigModule` | NgModule | `@alfresco/adf-core` | Use `provideAppConfig()`. |
| `AuthRoutingModule`, `loginFactory` | Module / factory | `@alfresco/adf-core` | Use `provideCoreAuth()`; routes are exposed as the `AUTH_ROUTES` constant. |
| `BaseAuthenticationService.isOauthConfiguration()` | Method | `@alfresco/adf-core` | Removed (dead code). |
| `DebugAppConfigService` | Service | `@alfresco/adf-core` | Removed. |
| `DocumentActionModel`, `FolderActionModel` | Classes | `@alfresco/adf-content-services` | Removed from `document-list` models. |
| `EXTENSION_DIRECTIVES` (from `extensions.module`), `setupExtensions` factory | Const / factory | `@alfresco/adf-extensions` | Use `provideAppExtensions()`. |
| `ScreenRenderingService` (old deep path `lib/services/`) | Service (relocated) | `@alfresco/adf-process-services-cloud` | Moved under `screen/services`; still exported from the package root. Use `provideScreen()` to register custom screens. |
### Viewer title API
`ViewerComponent` gained an `@Input() title` (with a `displayTitle` field and a two-line title/filename toolbar
block), and its truncation helper was **renamed**:
- `getDisplayFileName()` was **removed** — use `getDisplayTruncatedValue(value: string)` instead.
### Node comments avatar service
`NodeCommentsService` now resolves comment avatars via the People API:
- `getUserImage(avatarId)` → **`getUserImage(userId: string)`** — the parameter is now a **user id** (it calls
`PeopleApi.getAvatarImageUrl(userId)`), not a content/avatar node id. Update callers accordingly.
- The service constructor no longer injects `ContentService` (affects manual instantiation only).
### Translation key namespacing
The search-text input's translation keys were corrected to the `CORE.` namespace. If you provide **custom
translations** for these keys, move them under `CORE.SEARCH.*`:
| Before | After |
| ----------------------------- | ---------------------------------- |
| `SEARCH.BUTTON.TOOLTIP` | `CORE.SEARCH.BUTTON.TOOLTIP` |
| `SEARCH.BUTTON.ARIA-LABEL` | `CORE.SEARCH.BUTTON.ARIA-LABEL` |
| `SEARCH.INPUT.ARIA-LABEL` | `CORE.SEARCH.INPUT.ARIA-LABEL` |
| `SEARCH.FILTER.BUTTONS.CLOSE` | `CORE.SEARCH.FILTER.BUTTONS.CLOSE` |
## Deprecations
These still work but should be migrated to the new standalone provider APIs:
- `AuthModule` / `AuthModule.forRoot()` → **`provideCoreAuth(config?)`**.
- `CoreModule` → compose `provideI18N(...)`, `provideAppConfig()`, `provideCoreAuth(...)`. Note `CoreModule.forRoot()`
no longer wires up the auth interceptor, the snackbar default options, or the decimal form-field render
middleware — add them via the providers if you relied on them.
- `ExtensionsModule` / `ExtensionsModule.forChild()` → **`provideAppExtensions()`**.
- Auth methods `isEcmLoggedIn()` / `isBpmLoggedIn()` → `isLoggedIn()` (use `isECMProvider()` / `isBPMProvider()`
for the auth type); `getEcmUsername()` / `getBpmUsername()` → the new unified `getUsername()`.
- `ProcessModule` / `ProcessModule.forRoot()` (`@alfresco/adf-process-services`) is now `@deprecated` → import the
standalone components directly / use the provider API.
- `FormBaseComponent` static outcome constants (`@alfresco/adf-core`) are now `@deprecated`: `SAVE_OUTCOME_ID`,
`COMPLETE_OUTCOME_ID`, `START_PROCESS_OUTCOME_ID` → `FormModel.SAVE_OUTCOME` / `COMPLETE_OUTCOME` /
`START_PROCESS_OUTCOME`; `COMPLETE_OUTCOME_NAME` → `FormOutcomeModel.COMPLETE_ACTION`.
## New components and features
- **Standalone provider APIs** (the recommended way to bootstrap ADF in a standalone app):
- `provideCoreAuth(config?)` (core) — replaces `AuthModule.forRoot()`; provides HTTP client, OAuth client,
`AUTH_ROUTES`, auth services and interceptors.
- `provideExtensions({ authGuards?, evaluators?, components? })` (extensions) — register extension entities;
`provideAppExtensions()` — app extension bootstrap (replaces `ExtensionsModule`).
- `provideLandingPage(component)` + `LANDING_PAGE_TOKEN` (core).
- `provideScreen(key, component)` + `APP_CUSTOM_SCREEN_TOKEN` and `CustomScreen` (process-services-cloud) —
declaratively register custom task screens (replaces subclassing `ScreenRenderingService`).
- **Form button customization** — `FormCloudComponent` / `TaskFormCloudComponent` / `UserTaskCloudComponent`
gained `@Input() customSaveButtonText`, `customCompleteButtonText`, `customCancelButtonText`, `@Input() showSaveButton`
and an `@Output() formLoaded`. Several `FormModel` / `FormOutcomeModel` static constants became `static readonly`.
- **Root-level form sections** — `FormModel` and the form renderer now support a `section` as a root field type
(rendered via `<adf-form-section>` inside `.adf-container-widget`), with responsive column layout.
- **`QueryParams.excludedCategory?`** added (start-process cloud service).
- New CSS hook classes: `adf-form-renderer` (renderer root), `adf-error-messages-container-visible` /
`-hidden` (error slots now reserve space), and `adf-viewer__title-*`.
## Behavioural changes
| Area | Change |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Forms — dropdown | A form-rule-driven value change now syncs the reactive dropdown control (previously not reflected). |
| Forms — masked text | `InputMaskDirective` now marks the control as `touched` on blur, so touched-gated validation/`ng-touched` styling fires as expected. |
| Forms — start process | Malformed (non-JSON) backend error messages no longer crash `StartProcessCloudComponent`; the backend `response.body.message` is shown directly. The generic fallback i18n key changed from `...ERROR.START` to `...ERROR.START_PROCESS`. |
| Card view | `card-view-textitem` now highlights red on validation error (sets/clears a `customError` state, `subscriptSizing="dynamic"`, always-float label); `card-view-dateitem` floats its label when the property has a default value. |
| Search | Checkboxes in the search check-list facet render to the left of the label (Material default position). |
| Data table | Removed a duplicated horizontal scrollbar (the datatable root no longer carries `adf-full-width`). |
| Chips | `DynamicChipListComponent` chip visibility/"view more" overflow calculation fixed. |
| Comments | Avatars in `adf-node-comments` now resolve via the People API avatar endpoint. |
docs/upgrade-guide/upgrade811-821.md
+221
View File
@@ -0,0 +1,221 @@
---
Title: Upgrading from ADF v8.1.1 to v8.2.1
---
# Upgrading from ADF v8.1.1 to v8.2.1
This guide provides instructions on how to upgrade your v8.1.1 ADF projects to v8.2.1 (covering the 8.2.0 and
8.2.1 releases).
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The steps
below may involve code and theme changes — commit or back up your work first.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Theming layer removed](#theming-layer-removed)
- [Removed deprecated components](#removed-deprecated-components)
- [Removed deprecated auth methods](#removed-deprecated-auth-methods)
- [Clipboard tooltip](#clipboard-tooltip)
- [OAuth `secret` removed](#oauth-secret-removed)
- [Dependency changes](#dependency-changes)
- [Other API changes](#other-api-changes)
- [Accessibility-driven changes](#accessibility-driven-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": "8.2.1",
"@alfresco/adf-content-services": "8.2.1",
"@alfresco/adf-process-services": "8.2.1",
"@alfresco/adf-process-services-cloud": "8.2.1",
"@alfresco/adf-insights": "8.2.1",
"@alfresco/adf-extensions": "8.2.1",
"@alfresco/js-api": ">=9.2.1"
}
}
```
Angular, Material, TypeScript, zone.js and Nx are unchanged from 8.1.1 (Angular 19.2). Clean `node_modules` and
`package-lock.json`, then `npm install`.
## Breaking changes
### Theming layer removed
The ADF SCSS theming layer was removed (`AAE-38524`). The public theming mixins **`alfresco-material-theme($theme)`**
and **`adf-core-theme($theme, $custom-css-variables)`** no longer exist, and neither do the `_theming.scss` /
`_typography.scss` entry points (the `$alfresco-typography` config is gone; `material.theme.scss`'s
`adf-material-theme()` mixin was renamed to `globals()`). ADF now inherits colours and typography directly from
your application's Angular Material theme with **no extra ADF theming step**.
If your app did:
```scss
@import '~@alfresco/adf-core/theming';
@include alfresco-material-theme($theme); // or @include adf-core-theme($theme);
```
remove those includes. The `--theme-*` / `--adf-theme-*` CSS variables are no longer generated by ADF — if you
rely on them, define them yourself under `:root`, mapping to Angular Material's system variables (e.g.
`--theme-primary-color: var(--mat-sys-primary);`) as shown in the updated theming docs. The ADF prebuilt themes
were already removed in 8.0.0.
### Removed deprecated components
The following long-deprecated items were removed (`ACS-10178`). Remove any imports/usages:
| Removed | Selector | Package |
| ----------------------------------------------------------------------------------- | ------------------------------------ | -------------------------------------- |
| `LoginDialogComponent`, `LoginDialogComponentData`, `LoginDialogService` | `adf-login-dialog` | `@alfresco/adf-core` |
| `AppListCloudComponent` | `adf-cloud-app-list` | `@alfresco/adf-process-services-cloud` |
| `AppDetailsCloudComponent` | `adf-cloud-app-details` | `@alfresco/adf-process-services-cloud` |
| `APP_LIST_CLOUD_DIRECTIVES` (const) | — | `@alfresco/adf-process-services-cloud` |
| `FormDefinitionSelectorCloudComponent` | `adf-cloud-form-definition-selector` | `@alfresco/adf-process-services-cloud` |
| `FormDefinitionSelectorCloudService`, `FormDefinitionSelectorCloudServiceInterface` | — | `@alfresco/adf-process-services-cloud` |
### Removed deprecated auth methods
The ECM/BPM-specific auth methods deprecated in 8.1.1 were **removed** (`ACS-9768`). Migrate:
- `isEcmLoggedIn()` / `isBpmLoggedIn()` → `isLoggedIn()` (use `isECMProvider()` / `isBPMProvider()` for the provider type).
- `getEcmUsername()` / `getBpmUsername()` → `getUsername()`.
- `BasicAlfrescoAuthService.getTicketEcm()` / `getTicketBpm()` were also removed.
These were removed from `AuthenticationServiceInterface`, `BaseAuthenticationService`, `AuthenticationService`,
`BasicAlfrescoAuthService` and `OidcAuthenticationService`.
### Clipboard tooltip
`ClipboardDirective` now uses Angular Material's tooltip instead of a bespoke component:
- **`ClipboardComponent` was removed** (along with the `adf-copy-content-tooltip` selector and the
`.adf-copy-tooltip` CSS / `clipboard.theme.scss`). Tests querying `.adf-copy-tooltip` must switch to `MatTooltipHarness`.
- `ClipboardDirective` is now `standalone` with a `MatTooltip` host directive; its constructor changed (adds
`MatTooltip` and `TranslateService`). Ensure Material animations are provided.
### OAuth `secret` removed
The `secret` field was removed from the OAuth2 configuration (`ACS-10592`): from `OauthConfigModel`, the js-api
`Oauth2Config`, and `app.config.schema.json`. A client secret should never be shipped in a browser app; remove
`oauth2.secret` from your `app.config.json`. (The token endpoint no longer receives a `client_secret`.)
### Dependency changes
- **`event-emitter` → `eventemitter3`** (`^5.0.1`). The `EventEmitter` type used by `AuthenticationService` and
the ADF HTTP client (and js-api) now comes from `eventemitter3` (new exported `EventEmitterInstance` /
`EventEmitterEvents` types). The `on/off/once/emit` API is compatible, but the type import origin changed.
- **`toPromise()` → `firstValueFrom` / `lastValueFrom`** internally (mechanical; single-emit sources, no behavioural change).
- **js-api** peer requirement raised to `>= 9.2.1`.
> The `superagent` HTTP client was **not** replaced — a replacement PR was reverted before 8.2.1, so `superagent`
> remains in place with no consumer impact.
### Other API changes
- **`ColumnsSelectorComponent.changeColumnVisibility`** signature changed from `(dataColumn: DataColumn)` to
`(event: MatSelectionListChange)` (the columns list was rewritten to `mat-selection-list`).
- **`FormBaseComponent.completeTaskForm(outcome?)`** gained a second `outcomeId?: string` argument (and outcome
completion now requires the outcome's `id`); `FormCloudComponent.completeForm`/`completeTaskForm` follow suit.
Subclasses overriding these must update.
- **`DisplayRichTextWidgetComponent`** constructor changed (the `sanitizer` param was removed; parsing moved to
the new `RichTextParserService`).
- **`ReactiveFormWidget`** interface now requires a `field: FormFieldModel` member; new `MaybeReactiveFormWidget`
type and `FormFieldTypes.isReactiveWidget(...)`.
- **`MaxLengthFieldValidator`** constructor now takes optional `(supportedTypes, maxLength)`; `FORM_FIELD_VALIDATORS`
gained an entry that caps NUMBER fields at 10 digits.
- **`AmountWidgetComponent`** constructor changed (adds `CurrencyPipe`, `TranslationService`); `ADF_AMOUNT_SETTINGS`
was widened to accept `Observable<AmountWidgetSettings> | AmountWidgetSettings`; any custom `TranslationService`
must implement the new `getLocale()`.
- **`SearchFilterAutocompleteChipsComponent`** constructor now requires `SitesService` (for the new LOCATION facet).
- Base `WidgetComponent` no longer registers a host `(click)` binding — widgets that need it now declare their own.
- The screen `screen-cloud.model` import path moved under `components/screen-cloud/user-task-screen/` (deep imports must update).
- **`DataTableCellComponent`** (the base cell class): the public `computedTitle: string` property was replaced by a
`title = computed(...)` signal (backed by `protected rawComputedTitle`), and `computeTitle()` changed from
`private` to `protected`. Custom cells subclassing it should override `protected computeTitle()` and read `title()`.
- **`StartProcessCloudComponent`**: the public field `customOutcome` was split into `customOutcomeName` +
`customOutcomeId`, and `onCustomOutcomeClicked(outcome)` now takes a `FormOutcomeEvent` (was `string`);
`FormModel.selectedOutcome` is no longer `readonly`.
- **`UserTaskCloudComponent.onCompleteTask()`** gained a second optional `taskType?: UserTaskType` argument.
- **`BasicAlfrescoAuthService.getTicketEcmBase64()`** return type narrowed from `string | null` to `string`.
- **`ProcessFilterCloudModel`** — most properties were widened to `| null` and `parentId` became non-optional
(relevant to strict-typed consumers constructing the model).
### Accessibility-driven changes
A large accessibility batch (`ACS-10xxx`) added aria labels/roles and keyboard handling. Most are additive, but a
few change the DOM or public members that tests/styles may depend on:
- `LibraryDialogComponent` — `@Output() success` type narrowed to `EventEmitter<SiteEntry>`; `visibilityOption`
is now a `string` (the option value, not the option object).
- `NotificationHistoryComponent` — its `storageService` / `cd` constructor members are now `private` (were public);
the mark-as-read control changed from a `mat-menu-item` with `id="adf-notification-history-mark-as-read"` to an
icon button exposing `data-automation-id="adf-notification-history-mark-as-read"` (the `id` was removed).
- `DynamicChipListComponent` — the chip set changed `role="listbox"` → `role="list"` (chips are now `listitem`).
- Confirm dialog — the **Yes/No buttons swapped order** and initial focus moved to the accept button; e2e relying
on positional order or initial focus on "No" must update.
- Datatable header — the `$thumbnail` column screen-reader title changed from the literal `'Thumbnail'` to the
i18n key `ADF-DOCUMENT-LIST.LAYOUT.THUMBNAIL`.
- A few existing i18n key **values** changed (e.g. `BREADCRUMB.ARIA-LABEL.DROPDOWN`, and
`CORE.METADATA.ACCESSIBILITY.EDIT` is now parameterised with `{{ sectionName }}`), plus many new keys were added.
## New components and features
- **Repeatable-section form widget** — `RepeatWidgetComponent` (`adf-repeat-widget`, new
`FormFieldTypes.REPEATABLE_SECTION = 'repeatable-section'`) renders add/remove-row repeatable sections
(with `initialNumberOfRows` / `maxNumberOfRows` / `allowInitialRowsDelete` params and a confirm-on-remove dialog).
New `ContainerRowModel`; `FormFieldModel` gained `rows`, `addRow()`, `removeRow()`, `canAddRow()`.
- **Button form widget** — `ButtonWidgetComponent` (`button-widget`, new `FormFieldTypes.BUTTON = 'button'`),
auto-registered in `FormRenderingService`.
- **SSO integration API** (js-api) — `IntegrationSSOApi.getAccountInformation(repositoryId)` +
`SSOUserAccountCredentialsRepresentation`.
- **Screens on the start-process event** — `StartProcessScreenCloudComponent`
(`adf-cloud-start-process-screen-cloud`), an abstract `BaseScreenCloudComponent`, and a `TaskTypeResolverService`
(+ `UserTaskContentType`) to resolve form vs screen tasks.
- **Count APIs** — `ProcessListCloudService.getProcessListCount(...)` and `TaskListCloudService.getTaskListCount(...)`
(dedicated `/count` endpoints, used by the filter components in POST mode).
- **Custom redirects** — `StartProcessCloudComponent` gained `@Output() customOutcomeSelected` (emits the outcome
id); `FormModel.selectedOutcomeId` was added.
- **Rich-text parsing service** — `RichTextParserService` + `RICH_TEXT_PARSER_TOKEN`; `editorjs-html` moved to `dependencies`.
- **Legacy saved searches** — `SavedSearchesService` refactored onto a `SavedSearchStrategy` base with a new
`SavedSearchesLegacyService` and an optional `SAVED_SEARCHES_SERVICE_PREFERENCES` token.
- **Amount locale display** — opt-in via `AmountWidgetSettings.enableDisplayBasedOnLocale` (formats via `CurrencyPipe`
by browser locale); new `TranslationService.getLocale()`.
- **Search** — `SearchDateRangeComponent` gained `@Input() onReset$` + `reset()`; a new LOCATION (`SITE`) autocomplete
facet (filtered to accessible sites); chip autocomplete now reacts to `preselectedOptions` changes.
- Model additions: `ApplicationInstanceModel.lastModifiedAt` and `quickRunDeployment`; `QueryParams.include` widened
to `string`; new `AppConfigValues.OOI_CONNECTOR_URL` (`ooiServiceUrl`) for Microsoft 365 sessions under Basic auth.
- **`ProcessListCloudComponent`** gained `@Input() excludeByProcessCategoryName` (with a matching
`ProcessFilterCloudModel` field) so admins can filter out form-specific processes.
- New exported form internals: `RepeatableSectionModel` and `ROW_ID_PREFIX` (moved out of `form-field.model` into
`repeatable-section.model`), and `formFieldRuleHandler` (`handlers/form-field-rule.handler`) — enables conditional
(dependent) dropdowns inside repeatable sections to resolve per-row.
- `convertObjectToFormData` now accepts `Array<string | Blob>` values (multi-valued property upload).
## Behavioural changes
| Area | Change |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Forms — number | Integer/number fields reject input longer than 10 digits. |
| Forms — dropdown | Multi-select dropdowns work again (value writes are debounced by 100 ms); conditional dropdowns inside repeatable sections resolve per-row. |
| Forms — click | The form widget `event` handler fires once per click (a double-registration was removed from the base widget). |
| Forms — start process | The process card/start button render only after the form finishes loading (no button flash); setting the process definition programmatically no longer triggers a reload. |
| Search | Queries with non-latin characters are now UTF-8 base64-encoded correctly; resetting the tabbed date filter clears each tab. |
| Viewer | Changing the version inside the viewer reloads the preview; task-attached files with a display-value form field preview correctly. |
| Clipboard | Copy affordance is now a Material tooltip; copying keeps focus on the trigger (e.g. the "Copy link" button). |
| Localisation | Portuguese dates render `dd/mm/yyyy`; `TimeAgoPipe` is now impure and reacts to runtime locale changes, as do date/filesize datatable cells. |
| Auth | Under Basic auth, requests to the OOI service receive the content-services ticket (fixes starting a Microsoft 365 session). |
| Notifications / WebSocket | `WebSocketService.connectionParams` is now a function, so the auth token is re-evaluated on every (re)connect — deployment/websocket updates arrive without closing the panel. |
| Saved searches | `SavedSearchesService` now falls back to the preferences API on error (and re-throws non-404 errors during migration), fixing an empty sidebar on the first login after a cache clear. |
| Forms — start process | The default start-process error i18n key was corrected (the previous fallback key did not exist, so no error message showed). |
| Forms — button widget | `ButtonWidgetComponent` no longer uses `OnPush`, so its disabled state updates when the field object mutates in place. |
| Card view | Text/date item labels now always float (`floatLabel="always"`); the editable date item gained an `adf-property-field` class. |
docs/upgrade-guide/upgrade821-831.md
+227
View File
@@ -0,0 +1,227 @@
---
Title: Upgrading from ADF v8.2.1 to v8.3.1
---
# Upgrading from ADF v8.2.1 to v8.3.1
This guide provides instructions on how to upgrade your v8.2.1 ADF projects to v8.3.1.
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The steps
below may involve code changes — commit or back up your work first.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Removed components, tokens and pipes](#removed-components-tokens-and-pipes)
- [Enums converted to const-objects](#enums-converted-to-const-objects)
- [TypeScript target ES2022](#typescript-target-es2022)
- [Form widget base class](#form-widget-base-class)
- [Search and filter API](#search-and-filter-api)
- [Process/task filter changes](#processtask-filter-changes)
- [Context menu typing](#context-menu-typing)
- [PDF viewer](#pdf-viewer)
- [Other API changes](#other-api-changes)
- [Accessibility-driven DOM changes](#accessibility-driven-dom-changes)
- [Deprecations](#deprecations)
- [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": "8.3.1",
"@alfresco/adf-content-services": "8.3.1",
"@alfresco/adf-process-services": "8.3.1",
"@alfresco/adf-process-services-cloud": "8.3.1",
"@alfresco/adf-insights": "8.3.1",
"@alfresco/adf-extensions": "8.3.1",
"@alfresco/js-api": ">=9.3.1"
}
}
```
Angular/Material stay on 19.2 (patch bump to 19.2.19). `@ngx-translate/core` remains on **v16** (a v17 upgrade was
attempted and reverted). The declared `engines.node` floor is unchanged (`>=18.0.0`), but the version the libraries
are **built and tested on** moved from Node 22 to **Node 24** (`.nvmrc` `22.14.0` → `24.14.0`) — align your
build/CI Node version. Clean `node_modules` and `package-lock.json`, then `npm install`.
## Breaking changes
### Removed components, tokens and pipes
| Removed | Kind | Package | Migration |
| ---------------------------------------------------------------------------------- | ------------------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NodeNameTooltipPipe` (`adfNodeNameTooltip`), `ContentPipeModule`, `CONTENT_PIPES` | Pipe / module | `@alfresco/adf-content-services` | Use the new `node-tooltip.utils.ts` helpers. |
| `ADF_DOCUMENT_PARENT_COMPONENT` | Injection token | `@alfresco/adf-content-services` | `FilterHeaderComponent` now takes `@Input() pagination`/`sorting` and emits `searchResultsReady`/`filtersCleared` instead of injecting the parent document list. |
| `LANDING_PAGE_TOKEN`, `provideLandingPage()` | Token / provider | `@alfresco/adf-core` | Removed (they were added in 8.1.1 and unused). |
| `ButtonComponent` (`adf-button`), `ButtonVariant`, `ButtonColor` | Component / types | `@alfresco/adf-core` | Use Angular Material buttons directly. |
| `ProgressComponent` (`adf-progress`) | Component | `@alfresco/adf-core` | Use Material `mat-progress-bar` / `mat-progress-spinner`. |
| `ProcessAuditDirective` (`button[adf-process-audit]`) | Directive | `@alfresco/adf-process-services` | Removed (unused). |
| `CheckAllowableOperationDirective` (`[adf-check-allowable-operation]`) | Directive | `@alfresco/adf-content-services` | Removed (unused). |
| `ProcessListCloudComponent.excludeByProcessCategoryName` | `@Input` | `@alfresco/adf-process-services-cloud` | **Added in 8.2.1 and removed again in 8.3.1** — remove the binding. |
| `SortingPickerComponent` (`adf-sorting-picker`) | Component | `@alfresco/adf-core` | Removed. |
| `SearchSortingPickerComponent` (`adf-search-sorting-picker`) | Component | `@alfresco/adf-content-services` | Removed. |
| `BreadcrumbModule` | Module | `@alfresco/adf-content-services` | Removed — the breadcrumb components are standalone; import them directly. |
| `ToggleIconDirective` (`[adf-toggle-icon]`), `FileUploadErrorPipe` | Directive / pipe | `@alfresco/adf-content-services` | Removed. |
| `MultiValuePipe` | Pipe | `@alfresco/adf-core` | Made internal (no longer exported). |
| `BlankPageComponent`, `BlankPageModule` | Component / module | `@alfresco/adf-core` | Removed. |
| `displayLabelForChips` `@Input` (+ `showLabelForChips` getter) | Inputs | `@alfresco/adf-core` | Removed from `CardViewComponent`, `CardViewTextItemComponent`, `CardViewItemDispatcherComponent`. |
| `DecimalNumberModel` (class), `BpmProductVersionModel` (class) | Models | `@alfresco/adf-core` | Converted to interfaces (no longer instantiable via `new`); `BpmProductVersionModel` now lives in `@alfresco/js-api`. |
Note: the `IconModule` still exists but was **repurposed** — it no longer exports `IconComponent` (it now bundles
the new `IconDirective` + `MatIconModule`), and it is no longer marked `@deprecated`. Separately, **`IconComponent`
(`adf-icon`) itself is now `@deprecated`** ("Use material icon with `aria-hidden="true"` instead") — migrate to
`<mat-icon adf-icon>` or the new `IconDirective`.
### Enums converted to const-objects
37 exported `enum`s were converted to a `const` object plus a same-named union `type`
(e.g. `export const DateCloudFilterType = {...} as const; export type DateCloudFilterType = (typeof DateCloudFilterType)[keyof typeof DateCloudFilterType]`).
The identifiers are **preserved**, so value access (`Status.RUNNING`) and type annotations (`x: Status`) still
compile. However, code relying on `enum`-only semantics — numeric reverse-mapping, `enum` declaration merging, or
places that structurally require a TS `enum` — will need adjustment. Affected enums include `AppConfigValues`,
`FormFieldType`, `WidgetTypeEnum`, `Status`, `DateCloudFilterType`, `TaskStatusFilter`, `FormCloudDisplayMode`,
`NOTIFICATION_TYPE`, `FileUploadStatus`, `NodeAction`, `CloseButtonPosition`, and ~26 others across the libraries.
### TypeScript target ES2022
All library `tsconfig`s now target/`lib` **ES2022** (was ES2018/ES2020). Ensure your build/runtime toolchain
supports ES2022 (Angular 16+ toolchains do). Downstream bundlers should not unexpectedly down-level the output.
### Form widget base class
The base `WidgetComponent`'s `formService` changed from a **public optional constructor parameter** to a
**`protected` injected field** (`protected formService = inject(FormService)`). Custom widgets that called
`super(formService)` or accessed `.formService` publicly must migrate to `inject(FormService)` and drop the
`super(...)` argument.
### Search and filter API
- **`SearchConfiguration` and `SearchForm` now require an `id: string`.** Add an `id` to each entry in your
`search.config` / custom search configuration and form objects.
- **`BaseQueryBuilderService.updateSelectedConfiguration(index: number)` → `updateSelectedConfiguration(id: string)`** —
configurations are now selected/persisted by stable `id` (round-tripped through the `selectedConfigurationId`
query param) instead of array index. This fixes saved searches restoring the wrong set.
- **Search-header filters are now keyed by the category `id`** (not `columnKey`). `ADF_DOCUMENT_PARENT_COMPONENT`
was removed (see the table above); `FilterHeaderComponent` gained `@Input() pagination`/`sorting` and
`@Output() searchResultsReady`/`filtersCleared`.
- `SearchCheckListComponent.startValue` was widened from `string` to `string | string[]`.
### Process/task filter changes
- **`ProcessFiltersCloudComponent` and `TaskFiltersCloudComponent` no longer use `ViewEncapsulation.None`** — their
styles are now encapsulated, so global CSS overriding their internals may no longer apply. They also render filters
as router links now.
- The **task-filter query param was renamed from `filter` to `filterId`** — bookmarked/deep-link URLs using
`?filter=` on the task list will no longer activate the filter.
- `ServiceTaskIntegrationContextCloudModel` no longer extends `ServiceTaskQueryCloudRequestModel` (it is now a
standalone interface); its `errorDate` type changed from `Date` to `string`.
### Context menu typing
The context-menu overlay is now strongly typed: a new exported `ContextMenuItem` interface, and
`ContextMenuOverlayConfig.data` / the `CONTEXT_MENU_DATA` token changed from `any` to `ContextMenuItem[]`. Consumers
passing arbitrary objects as context-menu data may hit TypeScript errors and must conform to `ContextMenuItem`
(which includes a `subject.next` callback). Runtime behaviour is unchanged.
### PDF viewer
- Consumers importing pdf.js alongside ADF should use `import * as pdfjsLib from 'pdfjs-dist/build/pdf.min.mjs'`
(the settled import path); `PDFDateString` is imported from the same path.
- `PdfThumbComponent.page` and `PdfViewerThumbnailsComponent.pdfViewer` `@Input` types were widened to `any` (for
compatibility with the packaged `.min.mjs` build) — the `PdfThumbnailPage` / `PDFViewer` types are no longer referenced there.
- **JP2 (JPEG 2000) PDFs** now require the pdf.js **WASM assets served from `./wasm/`** — add the `wasm/` folder to
your app's asset copy (analogous to the existing `cmaps/`).
### Other API changes
- `StartProcessInstanceComponent` (classic process-services) renamed its public `moveNodeFromCStoPS()` method to
`populateFormData()` and the `movedNodeToPS` field to `populatedFormData`.
- `NumberCellComponent.numberValue` / `AmountCellComponent.amountValue` are now `Signal<number | null>` — they render
blank for non-numeric/empty/boolean values instead of passing the raw value through.
- The card-view text item's value `data-automation-id` changed from `card-textitem-value-<key>` to
`card-textitem-field-<key>` (update e2e selectors).
- The `IconComponent.isCustom` getter was renamed to `isSvg` (internal; component also gained `isSvg`/`fontSet` inputs
and content-projection).
### Accessibility-driven DOM changes
A large a11y batch added aria/roles/keyboard support. The ones that may break tests/styles:
- **Datatable column sorting target moved** — the sort `role="button"` / `tabindex` / keyboard handlers moved from the
outer `.adf-datatable-cell-header` to the inner `.adf-datatable-cell-header-content`. Update e2e that clicks the
outer header cell to sort.
- **Datatable cell tab stops** — cells are now tab-focusable only when `col.focus` is set (`[attr.tabindex]="col.focus ? 0 : null"`).
- The card-view text item's clickable value changed from a `<div role="button" tabindex="0">` to a native `<button>`;
its empty-value `<span class="adf-textitem-default-value">` and that CSS class were removed.
- Several containers changed from `<div>`/`<span>` to `<fieldset>` for grouping (search check-list `.checklist` →
`<fieldset class="adf-search-checklist">`; search date-range rows → `<fieldset>`).
- New ACC error locators: `data-automation-id="categories-error-message"` and `"tags-error-message"`.
- Permission manager: the `adf-authorityId-column` class was removed from the name columns; role column
`adf-expand-cell-4` → `adf-expand-cell-3`.
## Deprecations
These still work in v8.3.1 but are newly `@deprecated` and slated for removal — migrate when you upgrade:
- **`DiscoveryApiService.getBpmProductInfo()`** (`@alfresco/adf-content-services`) — `@deprecated since 8.3.0`.
- **`ProcessService.fetchProcessAuditPdfById()` / `fetchProcessAuditJsonById()`** (`@alfresco/adf-process-services`)
— marked "no longer used"; stop calling them.
- **`PROCESS_LIST_DIRECTIVES`** const (`@alfresco/adf-process-services`) — import the individual directives/components
directly instead of the barrel.
## New components and features
- **`adf-icon` directive + icon remapping** — a new `IconDirective` (`mat-icon[adf-icon]`, `@Input('adf-icon') name`)
and an `ICON_ALIAS_MAP_TOKEN` (+ `IconAliasMap` type, `DEFAULT_ICON_VALUE`) let apps remap icon names to SVG icons.
`IconComponent` also gained content projection (`<adf-icon>home</adf-icon>`, slot wins over `value`).
- **Signals on `UserPreferencesService`** — new `localeSignal`/`paginationSizeSignal`/`supportedPageSizesSignal`
signals and `locale$`/`paginationSize$`/`supportedPageSizes$` observables (additive; `.select()` still works).
- **Search** — new `BaseQueryBuilderService` streams `queryFragmentsUpdate` and `userFacetBucketsUpdate` plus a
`resetUserFacetBucket()` method; `SearchHeaderQueryBuilderService.getOperatorForFilterId(id)`;
`DocumentListComponent.@Input() isDataProvidedExternally`; `CustomResourcesService.loadFolderByNodeId(..., filters?)`;
Escape closes the cloud dropdown.
- **Process filters** — new `@Input()`s `includeSubprocesses`, `includeUnlinkedProcesses`, `includeLinkedProcesses`
(all `boolean | null`) and a `processRelatedTo` signal input on `ProcessListCloudComponent`, plus matching
`ProcessFilterCloudModel` / request-model fields; `ConstantValues.triggerableByService`.
- **Forms** — evaluate `${field.x}` / `${variable.x}` expressions in display-text/rich-text widgets (new
`FormExpressionService`, `BaseDisplayTextWidgetComponent`, `ADF_DISPLAY_TEXT_SETTINGS` token; opt-in, and HTML is
escaped in rich text); custom regex validation messages (`FormFieldModel.customValidationMessage` /
`enableCustomValidationMessage`, `ADF_CUSTOM_MESSAGE` token); skip validation for fields inside a hidden
group/section (`FormModel.enableParentVisibilityCheck` + `FormCloudComponent.@Input() enableParentVisibilityCheck`,
and `FormFieldModel.isFieldOrParentHidden()`); `provideI18N({ translations })` to register translations from code.
- **Extensibility** — the cloud filter services (`ProcessFilterCloudService`, `TaskFilterCloudService`,
`ServiceTaskFilterCloudService`) exposed key members as `protected` for subclassing.
- **JS-API** — `NodesApiService.listParents(nodeId, opts?)`; `AiAnswerObjectReference.nodeId?`.
- **Viewer** — keyboard control of the image crop tool (arrows move; Shift/Alt + arrow resize; arrow navigation
suppressed while cropping); PDF text/note annotations now render with hover/focus tooltips. New exported PDF
types: `PageChangingEvent`, `PdfThumbnailPage`, `PdfAnnotationData`, `PdfAnnotationWithTitle`.
- **Custom field-status template** — new `FieldStatusTemplateDirective` (`[adf-field-status-template]`) and
`FIELD_STATUS_TEMPLATE` token, so the text widget can render custom field-status content.
- **`ProcessListCloudComponent.@Input() enableAppChange`** — reloads preferences/process list when `appName` changes (opt-in).
- **New models/exports** — `NodeTooltipUtils` (replaces the removed tooltip pipe); `ProcessPayloadCloudData` interface;
`RelatedProcessInstance` interface + `ProcessInstanceCloud.linkedProcesses`/`subprocesses`/`linkedProcessInstanceId`/`linkedProcessInstanceType`;
`ServiceTaskListCloudService.getServiceTaskIntegrationContexts(...)` (+ `IntegrationContext` and related interfaces);
`RepeatableSectionModel` is now exported from the form widgets core barrel.
## Behavioural changes
| Area | Change |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Forms — outcomes | Name-based outcomes with a `null` id now complete the task (reverses the 8.2.1 requirement that an outcome needed both `name` and `id`). |
| Forms — dropdown | Required REST/variable-backed dropdowns with no real selection now correctly show the required error. |
| Forms — attach file | Clicking the attach-file label no longer fires the select dialog twice. |
| Card view | Double-click-to-copy now works on disabled/read-only text items; deleting a category in content metadata refreshes correctly. |
| Data table | Non-array rows/columns no longer crash the table (guarded); number/amount cells render blank for invalid values; sorting by a distinct `sortingKey` now persists in localStorage. |
| Viewer | APS-hosted file previews use the `preview` rendition; PDFs with JPEG-2000 images display (with WASM assets deployed). |
| Process list (APS) | Process-instance pagination fixed (the conflicting `start: 0` param was removed). |
| Saved searches | The selected configuration is tracked by stable `id`, so loading a saved search restores the intended set. |
| Forms — visibility | Visibility/rule conditions now work for fields inside repeatable sections; async-form auto-populated date values are formatted before parsing (fixes reuse across tasks). |
| Data table row | `DataTableRowComponent` (`adf-datatable-row`) `@Input() disabled` default changed `false` → `true` — direct consumers of the row component (outside `adf-datatable`, which always binds it) now get rows disabled by default. |
docs/upgrade-guide/upgrade831-841.md
+163
View File
@@ -0,0 +1,163 @@
---
Title: Upgrading from ADF v8.3.1 to v8.4.1
---
# Upgrading from ADF v8.3.1 to v8.4.1
This guide provides instructions on how to upgrade your v8.3.1 ADF projects to v8.4.1 (covering the 8.4.0 and
8.4.1 releases).
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. The steps
below may involve code changes — commit or back up your work first.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [ngx-translate v17](#ngx-translate-v17)
- [Tree actions template removed](#tree-actions-template-removed)
- [Data table adapter focus API removed](#data-table-adapter-focus-api-removed)
- [Form layout column-width methods](#form-layout-column-width-methods)
- [Required-field validation is stricter](#required-field-validation-is-stricter)
- [Rebranding (default logos)](#rebranding-default-logos)
- [Other API changes](#other-api-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": "8.4.1",
"@alfresco/adf-content-services": "8.4.1",
"@alfresco/adf-process-services": "8.4.1",
"@alfresco/adf-process-services-cloud": "8.4.1",
"@alfresco/adf-insights": "8.4.1",
"@alfresco/adf-extensions": "8.4.1",
"@alfresco/js-api": ">=9.4.1",
"@ngx-translate/core": ">=17.0.0"
}
}
```
Angular/Material stay on 19.2 (patch bump to 19.2.20). Clean `node_modules` and `package-lock.json`, then `npm install`.
## Breaking changes
### ngx-translate v17
`@ngx-translate/core` was upgraded to **v17** (peer `>= 17.0.0`; this re-lands the upgrade that was reverted in
8.3.1). If you configure translation yourself, apply the v17 API migration:
```ts
// Before (v16)
provideTranslateService({
loader: { provide: TranslateLoader, useClass: TranslateLoaderService, deps: [HttpClient] },
defaultLanguage: 'en'
})
// After (v17)
provideTranslateService({
loader: provideTranslateLoader(TranslateLoaderService),
fallbackLang: 'en'
})
```
- `defaultLanguage` → **`fallbackLang`**; `TranslateService.setDefaultLang()` → **`setFallbackLang()`**.
- Use the new **`provideTranslateLoader(...)`** helper for the loader (the manual `{ provide, useClass, deps }`
object is gone; `HttpClient` no longer needs wiring here).
- `translate.getTranslation(lang)` → `translate.currentLoader.getTranslation(lang)`.
- Push translations with `translate.setTranslation(lang, obj, true)` instead of emitting on `onTranslationChange`.
- Custom `TranslateLoader` implementations must satisfy the v17 interface (`getTranslation` returning
`Observable<TranslationObject>`); new `Language` / `TranslationObject` types come from `@ngx-translate/core`.
`provideI18N(...)` still works (it now uses `provideTranslateLoader` / `fallbackLang` internally).
### Tree actions template removed
`TreeComponent` (`adf-tree`) renders its per-row actions menu internally now. The
**`@Input() nodeActionsMenuTemplate` was removed** — supply actions via the existing `contextMenuOptions` input
(`{ title, model: { icon }, subject }`) and handle `contextMenuOptionSelected` instead of projecting a template.
### Data table adapter focus API removed
`ShareDataTableAdapter.allowFocusOnRows` and `setAllowFocusOnTableRows()`, and the matching optional members on the
`DataTableAdapter` interface, were **removed** (they were added in 8.3.1). Custom adapter implementations or callers
referencing them must drop them.
### Form layout column-width methods
Form column-width computation was extracted to a shared helper. Two template-invoked component method signatures changed:
- `FormRendererComponent.getColumnWidth(container)` → `getColumnWidth(container, columns, columnIndex)`.
- `FormSectionComponent.getSectionColumnWidth(numberOfColumns, columnFields)` →
`getSectionColumnWidth(numberOfColumns, columns, columnIndex)`.
Only matters if you subclass these or call the methods directly. The change fixes field `colspan` being ignored.
### Required-field validation is stricter
Required-field validation was tightened, which may newly block form submission that previously succeeded:
- A required field containing **only whitespace** now fails validation.
- A required **read-only** field with no value now fails validation (the internal
`FormFieldModel.isFieldValidatable()` gate was removed, so validators run for read-only fields too — except when
the field or its parent group/section is hidden).
The result: Start-process / Complete / Save buttons are correctly disabled in these cases (and Save/Complete are
re-enabled if the user declines the completion confirmation dialog).
### Rebranding (default logos)
The default Alfresco brand assets were replaced (this touches the libraries, not just the demo shell):
- `HeaderLayoutComponent` default logo: `./assets/images/logo.png` → `./assets/images/logo.svg` (`logo.png` deleted).
- `LoginComponent` `@Input() logoImageUrl` default: `./assets/images/alfresco-logo.svg` → `./assets/images/updated-alfresco-logo.svg`.
- New themeable `--theme-login-button-bg-color` CSS variable on the login button.
If you referenced the old default asset paths/filenames directly, update them.
### Other API changes
- `card-view-textitem` — the `[disabled]` bindings on the read-only/non-editable text input, textarea and chip
inputs were **re-added** (reverting an 8.3.x removal), so those controls are natively `disabled` again when
`isReadonlyProperty || !editable` (affects focusability/styling and tests asserting on `disabled`).
- `LogicalSearchCondition` (search) changed from an `interface` to a `type` alias — only affects code that
`implements` it or relies on declaration merging.
## New components and features
- **`LazyApi` decorator** (`@alfresco/js-api`) — a property decorator for lazily-created, cached js-api client
instances. Adopted internally across ~45 services (public property names unchanged); available for consumer use.
- **Expanded `adf-icon`** — the `IconDirective` now also resolves an icon when `name` is an alias **value** already
present in the alias map (not only an alias key).
- **Start-process custom screens** — `StartProcessScreenCloudComponent` gained `appName` and
`resolvedValues: TaskVariableCloud[]` signal inputs (plus `processDefinitionId`), propagated reactively to the
dynamic screen; the `StartProcessScreenCloud` interface gained matching optional members, and
`BaseScreenCloudComponent.setInputsForDynamicComponent()` is now a concrete no-op (no longer abstract).
- **`FormModel.showAllValidationErrors`** — a new boolean that forces all widgets into a touched state so every
pending validation error renders; this is what the form-rule `Validate form` action now toggles.
- **Date/datetime typed input** — users can now **type** into date and datetime fields (not picker-only); typed
input is preserved and an invalid value shows a `FORM.FIELD.VALIDATOR.INVALID_DATE_FORMAT` message
("Invalid date format, use the format: {{ format }}").
- **`ApplicationInstanceModel.deploymentCompletion?: number`** — new optional model field.
- **Permission list** — `PermissionDisplayModel.authorityDisplayName?` was added; the user-name column now shows a
human-readable authority display name when the backend provides one.
- New CSS hook class `adf-dropdown-widget-container` on the cloud dropdown widget wrapper.
## Behavioural changes
| Area | Change |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Forms — rich text | `${field.x}` / `${variable.x}` expressions are now evaluated inside rich-text-display **list** items (HTML-escaped). |
| Forms — visibility | Visibility conditions now re-run when a dependent field's value is changed by a form rule (not only by direct edit). |
| Forms — errors | Form error styling/colour was unified (uses the Material system error token; existing `adf-error*` classes unchanged); minor field-spacing fixes. |
| Search | The tag autocomplete facet now searches tags server-side per keystroke (via `TagService.searchTags`, sorted, capped at 15) instead of preloading all tags. |
| Dates | `TimeAgoPipe` now formats dates older than 7 days using the locale-aware `'short'` format (its `DEFAULT_DATE_TIME_FORMAT` default changed from `dd/MM/yyyy HH:mm` to `'short'`) — set `dateValues.defaultDateTimeFormat` in app config to keep the old fixed format. |
| Viewer | Previewing preview renditions for document versions now works (a rendition-id/mime-type mix-up was fixed). |
| Accessibility | Repository-info titles are now `<h2>` headings (new `adf-about-repository-info-header-*` automation ids); the filter-by-size popup uses `<fieldset>`/`<legend>` (dropped `role="menuitem"`/`role="button"`); unnecessary Tab stops were removed from the results table; new `ADF-DATATABLE.ACCESSIBILITY.*` keys added. |
docs/upgrade-guide/upgrade841-850.md
+169
View File
@@ -0,0 +1,169 @@
---
Title: Upgrading from ADF v8.4 to v8.5
---
# Upgrading from ADF v8.4 to v8.5
This guide provides instructions on how to upgrade your v8.4.1 ADF projects to v8.5.0.
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Because this
release changes theming, the HTTP transport, the Node version, and the PDF viewer packaging, budget time to
rebuild, re-theme and re-test your application.
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Node 24 and the fetch HTTP client](#node-24-and-the-fetch-http-client)
- [Material Design 3 theming](#material-design-3-theming)
- [Material `color` inputs removed](#material-color-inputs-removed)
- [PDF viewer moved to a lazy entry point](#pdf-viewer-moved-to-a-lazy-entry-point)
- [OAuth / JWKS](#oauth--jwks)
- [Card view select item](#card-view-select-item)
- [Form widget base class](#form-widget-base-class)
- [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": "8.5.0",
"@alfresco/adf-content-services": "8.5.0",
"@alfresco/adf-process-services": "8.5.0",
"@alfresco/adf-process-services-cloud": "8.5.0",
"@alfresco/adf-insights": "8.5.0",
"@alfresco/adf-extensions": "8.5.0",
"@alfresco/js-api": ">=9.5.0",
"@ngx-translate/core": ">=17.0.0"
}
}
```
Angular/Material stay on 19.2. Clean `node_modules` and `package-lock.json`, then `npm install`.
## Breaking changes
### Node 24 and the fetch HTTP client
`@alfresco/js-api` replaced its `superagent`-based HTTP client with one built on the native **`fetch`** API
(`FetchHttpClient`), and the repository's `engines.node` was raised to **`>= 24.14.0`**.
- **Upgrade your Node runtime/CI to Node 24.**
- `superagent`, `@types/superagent`, and `nock` were removed (`undici` added). The `AlfrescoApi` / `AlfrescoApiClient` /
`AdfHttpClient` public `HttpClient` interfaces are **unchanged**, so custom clients still work. Only code deep-importing
the internal `SuperagentHttpClient` breaks. `FetchHttpClient` accepts an optional `customFetch` implementation.
### Material Design 3 theming
ADF's own custom SCSS theming layer was removed in favour of **Angular Material's M3 system variables (`--mat-sys-*`)**.
This is the largest source of visual/build breakage for themed apps.
- **Define an Angular Material M3 theme in your app** (`mat.define-theme(...)` / `mat.theme(...)` +
`@include mat.all-component-themes($theme)`, per the [Material theming guide](https://material.angular.dev/guide/theming)).
ADF ships no theme mixin — it inherits colours and typography from your app's M3 theme automatically.
- **All `--adf-theme-*` and `--theme-*` CSS custom properties were removed** and replaced with `--mat-sys-*` (e.g.
`--theme-primary-color` → `--mat-sys-primary`, `--theme-warn-color` → `--mat-sys-error`,
`--adf-theme-foreground-text-color` → `--mat-sys-on-surface`, `--theme-caption-font-size` → `--mat-sys-body-small-size`).
Any consumer CSS/theme overriding the old variables silently stops working — re-point it at `--mat-sys-*`. A stylelint
rule now forbids re-introducing `--adf-*`/`--theme-*` properties.
- **The `globals()` SCSS mixin and `_globals.scss` were removed** (the styles entry point now forwards only
`flex`, `mixins`, `mat-selectors`). If you did `@include globals()`, remove it.
- **Avatar/Header CSS-variable theming removed** — `AvatarComponent` no longer reads `--adf-avatar-size`/`--adf-avatar-cursor`,
and `HeaderComponent` no longer reads `--adf-header-height`/`--adf-header-logo-height`/`--adf-header-logo-width` (they now
bind the component `@Input()`s directly). Use the inputs, not the CSS variables.
- Read-only/disabled form fields now render through a shared `.adf-readonly` class and M3 component override mixins
(`mat.form-field-overrides`, etc.). If you custom-styled disabled fields via `--mdc-*` fallbacks, re-check.
### Material `color` inputs removed
M3 buttons/icons/toolbars no longer support the M2 `color="primary|accent|warn"` palette, so the corresponding
`@Input() color: ThemePalette` was **removed** from `HeaderComponent`, `ToolbarComponent` and `IconComponent`, and
`FormBaseComponent` dropped its static `COMPLETE_BUTTON_COLOR` and `getColorForOutcome()`. Remove any `[color]`
bindings on these components and re-colour via `--mat-sys-*` classes if needed.
### PDF viewer moved to a lazy entry point
To avoid loading `pdfjs-dist` unless a PDF is actually viewed, the PDF viewer moved to a new **secondary entry point
`@alfresco/adf-core/viewer/pdf`**:
- `PdfViewerComponent`, `PdfPasswordDialogComponent`, `PdfThumbListComponent`, `PdfThumbComponent`,
`RenderingQueueServices`, and the `PDFJS_MODULE` / `PDFJS_VIEWER_MODULE` tokens were **removed from the
`@alfresco/adf-core` barrel** and now export from `@alfresco/adf-core/viewer/pdf`.
- **You must call `providePdfViewer()`** (from `@alfresco/adf-core/viewer/pdf`) in your app providers, or PDFs won't
render (the viewer logs a configuration error). Rendering is wired through the new `PDF_VIEWER_COMPONENT` token /
`PdfViewerRef` interface (still in the main barrel).
- `pdfjs-dist` is now an **optional peer dependency**, and the **pdf worker asset is no longer auto-copied** — configure
the worker asset yourself.
- An **`ng update` migration `migrate-pdf-viewer-imports` (v9.0.0)** rewrites the moved imports and injects
`providePdfViewer()` automatically.
### OAuth / JWKS
- `angular-oauth2-oidc` was upgraded **17 → 19** (align your app), and `angular-oauth2-oidc-jwks` (and its transitive
`jsrsasign`) were **removed**.
- JWT/JWKS signature validation now uses the native Web Crypto API via a new exported
**`WebCryptoJwksValidationHandler`** (`@alfresco/adf-core`). Consumers referencing the old `JwksValidationHandler`
must switch to it.
### Card view select item
`CardViewSelectItemComponent` gained multi-value support, with two API changes:
- **The public `value` field was removed** — the component now binds directly to `property.value`. Code reading
`component.value` must use `property.value`.
- `CardViewSelectItemProperties<T>.value` type widened from `string | number` to `T | T[]`.
The `multivalued` flag now lives on the shared base (`CardViewBaseItemModel.multivalued` / `CardViewItemProperties.multivalued`).
### Form widget base class
`TextWidgetComponent` and `MultilineTextWidgetComponent` now extend a new `FormattableTextWidgetComponent` base
(instead of `WidgetComponent`), and their templates moved off two-way `[(ngModel)]="field.value"` to
`[ngModel]="displayValue"` + `(onValueChange)`. Custom widgets subclassing these must call `super.ngOnInit()`, and
custom templates relying on the old two-way binding should be re-checked. Default behaviour is preserved.
## New components and features
- **Typed-value formatting in display widgets** (opt-in) — a new `FormFieldValueFormatterService`
(`register`/`format`/`hasFormatter`, with built-in formatters for people/group/dropdown/radio) and the
`ADF_TYPED_VALUE_FORMATTING_ENABLED` injection token. When enabled, read-only display widgets render friendly
labels for typed values instead of raw JSON. **Off by default** (no runtime change unless you provide the token).
- **Form tab navigation buttons** — a new `ADF_FORM_TAB_NAV_ENABLED` token (boolean or `Observable<boolean>`) plus the
form-definition flag `showBottomTabNavButtons` render Previous/Next tab buttons. `FormRendererComponent` /
`FormCloudComponent` gained `navigateToNextTab()` / `navigateToPreviousTab()` and `canNavigate*` getters; new
`FORM.PREVIOUS_TAB` / `NEXT_TAB` i18n keys.
- **Card view** — manual input for date **and** datetime fields (`allowManualInput`; `CardViewDateItemModel.format`
is now a getter/setter with a `formatChanges$` stream); `previousValue` is now sent through the update pipeline
(`CardViewUpdateService.update(property, value, options?)`, new `CardViewUpdateOptions` / `UpdateNotification.previousValue`);
multivalued select items.
- **Form data refresh** — when `[data]` is rebound, form runtime state is preserved and rules/visibility re-run; new
`FormFieldModel.restoreRuntimeValue()`/`restoreRuntimeFlags()` and a `'dataRefreshed'` form-rules event type;
`FormCloudComponent.visibleOutcomes`.
- **Task cloud** — `TaskCloudService.nextTask(appName, strategy?)`, `wasTaskCompletedByCurrentUser(...)`,
`getTaskById(..., service: 'query' | 'rb')`; `TaskListCloudService.fetchTaskList_UsingRuntimeBundleService(...)` (also
added as a required member of `TaskListCloudServiceInterface` — breaking for external implementors of that interface);
`TaskHeaderCloudComponent.@Input() processInstanceId` (now an input, click-to-copy); `ProcessInstanceCloud.type?`;
new public `updateSearchControlState()` on `PeopleCloudComponent` / `GroupCloudComponent`.
- **Icons** — a dedicated `fileLink` icon for `app:filelink` nodes (new `NodeAction.LINK`), the sidenav gains M3
surface colours, and the notification badge size is configurable via `NotificationHistoryComponent.@Input() badgeSize`
/ `app.config.json` `notification.badgeSize`.
## Behavioural changes
| Area | Change |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Forms — start button | The Start-process outcome button is now hidden on user-task forms (even read-only) and stripped when a `taskId` is present. |
| Forms — dates | Manual date/datetime typing is allowed; an unparseable value shows a shortened "Invalid date format." error. |
| Forms — read-only | Read-only/disabled fields (including people/group widgets) restyle consistently via `.adf-readonly`; group search control re-syncs its read-only state on every change. |
| Card view | Clearing an int/long text item returns empty string (not `0`); select items no longer crash on a numeric initial value. |
| Viewer | The file-type icon reflects the viewed version's content type when a rendition exists. |
| Search | Facet labels wrapped in quotes by the backend are now unquoted/matched correctly. |
| Layout | Collapsing the left sidenav now closes it correctly, fixing keyboard focus order. |
| People / group widgets | The search input is now disabled while preselect validation is loading (previously only when `readOnly`). |
| Auth config | `AppConfigService.oauth2` no longer throws when the `oauth2` config is explicitly `null` (null-coalesces to `{}`). |
docs/upgrade-guide/upgrade850-900.md
+293
View File
@@ -0,0 +1,293 @@
---
Title: Upgrading from ADF v8.5 to v9.0
---
# Upgrading from ADF v8.5 to v9.0
This guide provides instructions on how to upgrade your v8.5.0 ADF projects to v9.0.0.
## Before you begin
Always perform upgrades on a "clean" project state, back up your changes or make a project backup. Because this
release bumps the Angular major, budget time to run the Angular 20 `ng update` migrations on your own app,
rebuild, and re-test. Expect to install with `--legacy-peer-deps` (see below).
## Contents
- [Library updates](#library-updates)
- [Breaking changes](#breaking-changes)
- [Angular 20 / TypeScript 5.9](#angular-20--typescript-59)
- [Knowledge Discovery removed](#knowledge-discovery-removed)
- [`MaterialModule` removed](#materialmodule-removed)
- [Search query-builder refactor](#search-query-builder-refactor)
- [Extension auth guards are now typed](#extension-auth-guards-are-now-typed)
- [Process instance model — subprocess/linked-process fields](#process-instance-model--subprocesslinked-process-fields)
- [Task cloud — Runtime Bundle task fetch](#task-cloud--runtime-bundle-task-fetch)
- [Multiline text widget base class](#multiline-text-widget-base-class)
- [Text field default max length](#text-field-default-max-length)
- [Tree and chip DOM / accessibility changes](#tree-and-chip-dom--accessibility-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": "9.0.0",
"@alfresco/adf-content-services": "9.0.0",
"@alfresco/adf-process-services": "9.0.0",
"@alfresco/adf-process-services-cloud": "9.0.0",
"@alfresco/adf-insights": "9.0.0",
"@alfresco/adf-extensions": "9.0.0",
"@alfresco/js-api": ">=10.0.0",
"@ngx-translate/core": ">=17.0.0"
}
}
```
Bump your Angular platform to **20.x** in lockstep (`@angular/core`/`@angular/material`/`@angular/cdk` `20.x`,
`typescript` `5.9`). Clean `node_modules` and `package-lock.json`, then `npm install`.
## Breaking changes
### Angular 20 / TypeScript 5.9
ADF 9.0.0 is built against **Angular 20** and **must be consumed by an Angular 20 app** — there is no cross-version
support with Angular 19.
| Package | v8.5.0 | v9.0.0 |
| ------------------------------------- | ------ | ------------------ |
| `@angular/core`, `@angular/common`, … | 19.2.x | **20.3.x** |
| `@angular/material`, `@angular/cdk` | 19.2.x | **20.2.x** |
| `@angular/material-date-fns-adapter` | 19.2.x | **20.2.x** |
| `typescript` | 5.8.3 | **5.9.3** |
| `ng-packagr` | 19.2.x | **20.3.x** |
| `@angular-eslint/*` | 19.3.0 | **20.7.0** |
| `@typescript-eslint/*` | 6.x | **8.x** |
| `zone.js` | 0.15.0 | 0.15.0 (unchanged) |
| `rxjs` | 7.8.2 | 7.8.2 (unchanged) |
| `nx` | 22.x | 22.x (unchanged) |
- **Run the Angular 20 update on your own app** (`ng update @angular/core@20 @angular/cdk@20 @angular/material@20`)
and move to **TypeScript 5.9**. Follow the official
[Angular update guide](https://angular.dev/update-guide).
- **Expect `npm install --legacy-peer-deps`.** A transitive dependency (`@mat-datetimepicker/core`) still declares
an Angular-19 CDK peer range while ADF ships CDK 20, so npm reports a peer conflict without the flag.
- **ESLint:** `@typescript-eslint/brace-style` was removed in `@typescript-eslint` v8 — drop it from any shared
config that inherited it from ADF. Angular 20 also newly recommends `@angular-eslint/prefer-inject`
(constructor injection → `inject()`); this surfaces as warnings only.
- **CDK `PortalInjector` removed** — Angular CDK 20 removed `PortalInjector`. ADF replaced its internal usage with
`Injector.create()`; if your own code imported `PortalInjector` from `@angular/cdk/portal`, make the same swap.
### Knowledge Discovery removed
The **Knowledge Discovery / Search-AI / Knowledge Retrieval** feature (the HxI-connector agent-based AI query
feature originally added in 7.0.0) was **removed entirely** from both `@alfresco/adf-content-services` and
`@alfresco/js-api`. There is **no replacement** — remove all usages.
Removed from **`@alfresco/adf-content-services`** (the `agent`, `search-ai` and `prediction` barrels were deleted):
| Removed | Kind |
| -------------------- | --------- |
| `AgentService` | Service |
| `SearchAiService` | Service |
| `SearchAiInputState` | Interface |
| `PredictionService` | Service |
Removed from **`@alfresco/js-api`**:
- **content-rest-api:** `AgentsApi`, `SearchAiApi`; models `Agent`, `AgentEntry`, `AgentPaging`, `AgentPagingList`,
`AiAnswer`, `AiAnswerEntry`, `AiAnswerReference`, `AiAnswerObjectReference`, `KnowledgeRetrievalConfig`,
`KnowledgeRetrievalConfigEntry`, `QuestionModel`, `QuestionRequest`, `RestrictionQuery`.
- **hxi-connector-api (entire secondary API removed):** `PredictionsApi`, `Prediction`, `PredictionEntry`,
`PredictionPaging`, `PredictionPagingList`, and the `UpdateType` / `ReviewStatus` types.
- **`AlfrescoApi.hxiConnectorClient`** — the client property (and its config/auth wiring) was removed from
`AlfrescoApi` / `AlfrescoApiType`.
### `MaterialModule` removed
The deprecated **`MaterialModule`** re-export barrel was removed from **both `@alfresco/adf-core` and
`@alfresco/adf-content-services`**, and is no longer re-exported by `CoreModule` / `ContentModule`.
Import the specific `@angular/material/*` modules you actually use directly from Angular Material:
```ts
// Before
import { MaterialModule } from '@alfresco/adf-core'; // (or from @alfresco/adf-content-services)
// After — import only what you use, from Angular Material
import { MatButtonModule } from '@angular/material/button';
import { MatIconModule } from '@angular/material/icon';
// …etc
```
Apps that were transitively relying on Material modules via ADF's module exports must now import each Material
module explicitly.
### Search query-builder refactor
`BaseQueryBuilderService` (the base of `SearchQueryBuilderService` and `SearchHeaderQueryBuilderService`) was
refactored to parse the user query on demand and to support two query modes. This removes the old
"emit `updated` → subscriber calls `execute()`" indirection:
- **The `updated` `Subject<SearchRequest>` was removed.** Code subscribing to `queryBuilder.updated` must instead
react to `queryBuilder.execute()` results (`executed` / the returned `SearchRequest`).
- **The `update(queryBody?)` method was removed.** Call **`execute()`** directly.
```ts
// Before
this.queryBuilder.updated.subscribe((query) => { /* … */ });
this.queryBuilder.update();
// After
this.queryBuilder.execute(); // executes and emits results directly
```
- **The `userQuery` setter no longer trims and parenthesizes.** Previously `userQuery = 'foo'` stored `'(foo)'`;
now it stores the raw value `'foo'` and derives the compiled query via the new read-only **`parsedQuery`**
getter. Read `parsedQuery` where you previously read the wrapped `userQuery`.
- **New `searchMode: 'regular' | 'formula'`** (default `'regular'`). In `regular` mode a user term is expanded
across the configured fields (`search.app:fields`, default `["cm:name"]`); in `formula` mode the raw input is
used verbatim as an AFTS expression.
- **New read-only `wildcardsEnabled`** — driven by the new `search-wildcards-enabled` app-config flag (default
`true`). When `false`, terms match exactly (no trailing `*`) and the search-text widget's
`searchPrefix`/`searchSuffix` are not applied.
- `updateSelectedConfiguration(id)` gained two optional params — `updateSelectedConfiguration(id, resetFilters = true, shouldExecute = true)` — non-breaking for existing single-argument callers.
- `SearchTextComponent.enableChangeUpdate` now defaults to **`false`** (was `true`).
`execute(updateQueryParams = true, queryBody?)` keeps the same signature as in 8.5.0.
### Extension auth guards are now typed
`ExtensionService.authGuards` and the `setAuthGuards()` / `getAuthGuards()` signatures were narrowed from
`Record<string, unknown>` / `Array<unknown>` to **`Record<string, CanActivateFn>`** / **`Array<CanActivateFn>`**
(`@angular/router`) in `@alfresco/adf-extensions`. Code that registered auth guards with a looser type now gets a
compile error — register `CanActivateFn` guards.
### Process instance model — subprocess/linked-process fields
`ProcessInstanceCloud` replaced its two related-instance **arrays** with **counts**:
| Before (8.5.0) | After (9.0.0) |
| -------------------------------------------- | ------------------------------- |
| `linkedProcesses?: RelatedProcessInstance[]` | `linkedProcessesCount?: number` |
| `subprocesses?: RelatedProcessInstance[]` | `subprocessesCount?: number` |
Code reading `processInstance.linkedProcesses` / `processInstance.subprocesses` must switch to the count fields
(the full related-instance collections are no longer carried on the model).
### Task cloud — Runtime Bundle task fetch
`TaskCloudService.getTaskById` dropped its third `service` argument:
- **Before:** `getTaskById(appName, taskId, service: 'query' | 'rb' = 'query')`
- **After:** `getTaskById(appName, taskId)`
Endpoint selection is now controlled by the new **`ADF_TASK_RUNTIME_BUNDLE_FALLBACK_ENABLED`** injection token
(`InjectionToken<Observable<boolean> | boolean>`, from `@alfresco/adf-process-services-cloud`). When it resolves
truthy, `getTaskById` / `FormCloudService.getTask` read active tasks from the always-current **Runtime Bundle**
endpoint and transparently **fall back to the Query Service on HTTP 404** (e.g. completed/archived tasks).
Default (token absent) is unchanged — Query Service only. Any caller passing `'rb'`/`'query'` must drop the
argument and provide the token instead. The feature also adds two public exports: the
`TaskDetailsCloudModelRuntimeBundle` interface and the `resolveTaskRuntimeBundleFallback$(token)` helper.
### Multiline text widget base class
`MultilineTextWidgetComponentComponent` now **extends `WidgetComponent`** (previously `FormattableTextWidgetComponent`),
`implements OnInit`, and renders validation errors via Material `mat-error` (an `errorStateMatcher` +
`translateParameters`) instead of the shared `ErrorWidgetComponent`. Custom widgets that subclassed it and relied
on `FormattableTextWidgetComponent` members must adapt. Many other widgets were migrated to the same `mat-error`
rendering in the same change — the core `AmountWidgetComponent`, `DecimalWidgetComponent`, `NumberWidgetComponent`;
the cloud `dropdown`/`date`/`date-time`/`display-external-property` widgets; the process-services (non-cloud)
`dropdown`/`typeahead`/`functional-group`/`people` widgets; `TagActionsComponent`; and the `StartTaskComponent`
date field. **Custom CSS targeting the old `ErrorWidgetComponent` markup for any of these widgets may need updating.**
### Text field default max length
The `TEXT` field now enforces a **default maximum length of 1024 characters** when the field defines no explicit
`maxLength`, and oversized paste is blocked:
- New exported constant **`DEFAULT_TEXT_MAX_LENGTH = 1024`** (`@alfresco/adf-core`).
- `FORM_FIELD_VALIDATORS` now applies `MaxLengthFieldValidator` to `TEXT` with a `1024` fallback (and a separate
uncapped validator for `MULTILINE_TEXT`); `MaxLengthFieldValidator`'s constructor gained a 3rd
`fallbackMaxLength?` param.
- Pasting text that would exceed the resolved max length is now prevented, the field is marked touched, and a
`FORM.FIELD.VALIDATOR.NO_LONGER_THAN` error shows.
TEXT fields that previously relied on unlimited length now cap at 1024 unless the field itself defines a
`maxLength`.
### Tree and chip DOM / accessibility changes
Keyboard-accessibility rework changed the DOM of a few components (no `@Input`/`@Output` were removed, but markup,
CSS selectors and automation ids changed — update tests/CSS that target the old markup):
- **`TreeComponent` (`adf-tree`)** — the expand/collapse **chevron button was removed from the tab order**
(`tabindex="-1"`, `aria-hidden="true"`) and the label `span` is no longer interactive (lost `role="button"` /
`tabindex="0"`). Keyboard users now operate the **row**: **Enter** expands/collapses, **Space** selects/toggles.
Rows gained `aria-label`/`aria-selected`; selection is announced via `LiveAnnouncer`
(new `ADF-TREE.ARIA.SELECTED` / `DESELECTED` keys).
- **`DynamicChipListComponent`** — the chip delete affordance changed from a `<mat-icon matChipRemove>` to a real
`<button class="adf-dynamic-chip-list-delete-btn" data-automation-id="adf-dynamic-chip-list-delete-btn-<id>">`.
The old `.adf-dynamic-chip-list-delete-icon` element / `adf-dynamic-chip-list-delete-{name}` id are gone
(`@Output() removedChip` is unchanged; it now emits from the button click). A new public
`focusDeleteButton(index)` method was added, and a new `DYNAMIC_CHIP_LIST.DELETE` i18n key.
## New components and features
- **Session timeout** (opt-in, `@alfresco/adf-core`) — a new subsystem that tracks user idle activity, shows a
countdown "Are you still working?" dialog, and logs out on timeout, synchronised across browser tabs via
`BroadcastChannel`. Enable it with the new **`provideSessionTimeout(options?)`** provider and/or a
`sessionTimeout` block in `app.config.json`:
```json
{ "sessionTimeout": { "enabled": true, "idleTimeoutMs": 1800000, "dialogTimeoutMs": 60000 } }
```
New exports include `SessionTimeoutService`, `SessionTimeoutDialogComponent` (`adf-session-timeout-dialog`),
`IdleActivityTracker`, `SessionTimeoutSyncChannel`, the `SESSION_TIMEOUT_OPTIONS` token, the
`SESSION_TIMEOUT_CONFIG_KEY` / `DEFAULT_SESSION_TIMEOUT_OPTIONS` constants, and the `SessionTimeoutOptions`
interface. Defaults: 30-minute idle timeout, 60-second warning dialog. New `SESSION_TIMEOUT.*` i18n keys.
- **Clock-drift-tolerant token expiry** (opt-in) — a new `oauth2.timeSync` app-config flag makes OAuth token
expiry checks use a **server-time-corrected clock** (to avoid false logouts on VMs/Citrix with drifted clocks).
Backed by a reworked `TimeSyncService` (`getCorrectedNow()`) and a new exported `TimeSyncDateTimeProvider`;
`OauthConfigModel` gained optional `timeSync?: boolean` and `showDebugInformation?: boolean` fields, and a new
top-level **`serverTimeUrl`** app-config key (`AppConfigValues.SERVER_TIME_URL`) points at the endpoint used to
read server time. Off by default — behaviour is unchanged unless `oauth2.timeSync` is enabled.
- **Type-aware form field value adapter** — a new root-provided **`FormFieldValueAdapterService`**
(`register`/`hasAdapter`/`adapt`, with the exported `FormFieldValueAdapter` type) in `@alfresco/adf-core`, the
inbound counterpart to 8.5.0's `FormFieldValueFormatterService`. Both are gated by the existing
`ADF_TYPED_VALUE_FORMATTING_ENABLED` token. A companion `ReactivePreselectionService` now backs the cloud
People/Group widgets' preselection.
- **Repeatable-section row-count event** — a new **`'onRowCountChanged'`** form-rules event is emitted (via
`FormService.formRulesEvent`) when a repeatable section adds/removes a row, driven by the new
`FormModel.onRepeatableSectionRowCountChanged(sectionField)`. The `FormValidationService` interface gained an
optional `formRulesEvent?: Subject<FormRulesEvent>`.
- **Dropdown/radio labels in display-text expressions** — when typed-value formatting is enabled, `${field.x}`
expressions now resolve dropdown/radio values to their option **label** instead of the raw id. New
`FormFieldTypes.DISPLAY_TEXT_TYPES` / `FormFieldTypes.isDisplayTextType()` helpers.
- **Multiline text auto-grow** — the multiline text widget grows unbounded by default; setting the field param
`autoGrow: false` caps its height (scrollable). Driven by `field.params.autoGrow` (no new `@Input`).
- **Silent document-list reload** — `DocumentListService.reloadSilently()` / `reloadSilently$` reload the list
**without** resetting the current selection (used to keep the context menu open during bulk upload).
- **`UrlService` blob helpers** — new public `createObjectUrl(blob)` and `trustUrl(url)` methods (the existing
`createTrustedUrl(blob)` is now composed from them).
- **`CustomResourcesService.getRecentFiles`** gained an optional 4th `includeFields: string[] = []` param
(forwarded from `loadFolderByNodeId` for `-recent-`), so extra fields (e.g. `isFavorite`) can be requested.
- **Version list** now shows the version's **modified-by user** (`modifiedByUser.displayName`) and the
**modified date and time** (`date: 'medium'`).
## Behavioural changes
| Area | Change |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Auth — OIDC | `OidcAuthenticationService.reset()` now calls `oauthService.logOut(true)` (terminates the OAuth session) instead of reloading the IDP configuration — supports the session-timeout logout redirect. |
| Search — node selector | `ContentNodeSelectorPanelComponent` no longer leaves stale `ANCESTOR:` filters when switching sites/clearing the search; filtering now correctly scopes to the chosen site. |
| Forms — people widget | `PeopleWidgetComponent` (process-services) now debounces its user search by 300 ms instead of querying on every keystroke. |
| Forms — spinner | The Automate-form spinner overlay is now fully disposed on host destroy, so it no longer persists outside the form. |
| Forms — task fetch | Task claim/unclaim status is evaluated against the always-current Runtime Bundle when the RB-fallback token is enabled (fixes stale block-task claim status). |
| Uploads | `FetchHttpClient` now converts a Node `ReadStream`/`Buffer` to a `Blob` (with filename) before appending to `FormData`, fixing broken multipart uploads under the fetch client. |
| Uploads | The form multi-file attachment viewer now updates when a different file is selected; the "upload new version" button re-enables after use; bulk upload no longer collapses the context menu. |
| Viewer | Firefox-headless race fixed — PDF blob/MIME state is assigned atomically and MIME types are normalised (charset params stripped). |
| Accessibility — tags | Tag delete controls are now real keyboard-operable buttons; focus is restored sensibly after a tag is removed, and blank/whitespace tags are rejected. |