alfresco-ng2-components/docs/upgrade-guide/upgrade811-821.md

Title

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
• Breaking changes
  • Theming layer removed
  • Removed deprecated components
  • Removed deprecated auth methods
  • Clipboard tooltip
  • OAuth secret removed
  • Dependency changes
  • Other API changes
  • Accessibility-driven changes
• New components and features
• Behavioural changes

Library updates

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

{
    "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:

@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.