## 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 // after getNode(nodeId: string, options?: any): Observable ``` - `[ContentService](../core/services/content.service.md)`: `folderCreate` / `folderEdit` are now `Subject`. - `[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`; `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`). ### Other breaking changes - **Bearer-excluded URL matching** is now anchored to the host + first path segment (`^https?://[^/]+/`) instead of matching anywhere in the URL. Review any custom `bearerExcludedUrls` patterns that relied on substring matching. - **DataTable multiselect checkbox** wrapper changed from a `
` to a `