--- 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`; 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`; `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` 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. |