Application Development Framework ADF Documentation Upgrade GuideFrom 2.6.0 to 3.0.0

Upgrading from ADF v2.6 to v3.0

This guide explains how to upgrade your ADF v2.6 project to work with v3.0.

Do not skip this task, if you want your application to be updated to a 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.

Note: the steps described below might involve making significant changes to your code. If you are working with a versioning system then you should commit any changes you are currently working on. If you aren't using versioning then be sure to make a backup copy of your project before going ahead with the upgrade.

Since 3.0 is a major version release, there are breaking changes you need to take into account as well as the usual library updates. After updating the libraries, check the other sections to see if any of the changes affect your project.

Library updates

Automatic update using the Yeoman Generator

If your application has few changes from the original app created by the Yeoman generator then you may be able to update your project with the following steps:

Update the Yeoman generator to the latest version (3.0.0). Note that you might need to run these commands with sudo on Linux or MacOS:

npm uninstall -g generator-alfresco-adf-app
npm install -g generator-alfresco-adf-app

Run the new yeoman app generator:

yo alfresco-adf-app

Clean your old distribution and dependencies by deleting the node_modules folder and the package-lock.json file.
Install the dependencies:
```
npm install
```

At this point, the generator might have overwritten some of your code where it differs from the original generated app. Be sure to check for any differences from your project code (using a versioning system might make this easier) and if there are any differences, retrofit your changes. When you have done this, you should be able to start the application as usual:

npm run start

After starting the app, if everything is working fine, that's all and you don't need to do anything else. However, if things don't work as they should then recover the original version of the project and try the manual approach.

Manual update

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

"dependencies": {
    ...
    "@alfresco/adf-core": "3.0.0",
    "@alfresco/adf-content-services": "3.0.0",
    "@alfresco/adf-process-services-cloud": "3.0.0",
    "@alfresco/adf-insights": "3.0.0",
    "@alfresco/js-api": "3.0.0",
    ...

Clean your old distribution and dependencies by deleting node_modules and package-lock.json.
Reinstall your dependencies
```
npm install
```

Breaking changes

The ADF project follows the semver conventions and so we only make breaking changes (ie, not backward-compatible) in major versions. ADF 3.0 is the first major version since general availability so a number of deprecated items have been removed and also some existing items have been renamed. The sections below explain how to adapt your project to the changes in 3.0. See also our breaking changes document for more information about the changes and links to the associated pull requests.

JS-API changes

The name package of the JS-API has been modified to use the @alfresco namespace and so you should change all alfresco-js-api imports to @alfresco/js-api. See the JS-API documentation for more details on how to use the new v3.0.0 Legacy Endpoint porting.

Also, the JS-API callApi method signature has been modified. The authNames parameter has been removed because the type of authentication is configured when the JS-API is constructed. You should remove references to authNames from your code.

v2.6.1 and before:

callApi(
    path: string,
    httpMethod: string,
    pathParams?: any,
    queryParams?: any,
    headerParams?: any,
    formParams?: any,
    bodyParam?: any,
    authNames?: string[],
    contentTypes?: string[],
    accepts?: string[],
    returnType?: any,
    contextRoot?: string,
    responseType?: string
): Promise<any>;

After v3.0.0:

callApi(
    path: string,
    httpMethod: string,
    pathParams?: any,
    queryParams?: any,
    headerParams?: any,
    formParams?: any,
    bodyParam?: any,
    contentTypes?: string[],
    accepts?: string[],
    returnType?: any,
    contextRoot?: string,
    responseType?: string
): Promise<any>;

Permissions vs Allowable Operations

The hasPermission method in the ContentService was found to be actually checking the allowableOperation value. To reflect this, the method has been renamed as hasAllowableOperations and a new hasPermission method has been added (this one checks the permissions correctly as expected).

If you were using the old hasPermission method successfully in v2.6 then you should update your code to use hasAllowableOperations, which has the same behavior. If your code was having problems with the earlier incorrect behavior of hasPermission then you should find it now works correctly.

Related to this issue is the hasPermission method of the Document List Service which has been made redundant by ContentService.hasAllowableOperations and has now been removed.

Also, the former Node Permission Directive has now been renamed as the Check Allowable Operation directive to better reflect its true behavior. You should therefore replace existing references to adf-node-permission with adf-check-allowable-operation.

Deprecated items

The deprecated items listed below have been removed from ADF as of v3.0. You should update your code to use the suggested fix for each item that affects your project.

The adf-accordion and adf-accordion-group components have been removed. Replace instances of these components with the Angular mat-accordion component. See the mat-expansion-panel doc page for an example of how to do this.
Viewer component: The allowShare input has been removed. Inject the Share Directive in a custom toolbar to recreate the behavior of the Share button.
Viewer component: The handling of the sidebar has been updated to allow left and right sidebars at the same time. The following properties have changed, so you should update your code to use the new properties:
- The allowSidebar input has now been split into allowLeftSidebar and allowRightSidebar.
- The showSidebar input has now been split into showLeftSidebar and showRightSidebar.
- The sidebarTemplate input has now been split into sidebarLeftTemplate and sidebarRightTemplate.
- The sidebarPosition input has been removed (the other new inputs render it obsolete).
The createFolder event of the UploadBase class (emitted when a folder was created) has been removed. You should modify your code to use the success event instead.
Login component: Two inputs have been removed: disableCsrf and providers. Set the properties with the same names in app.config.json to get the same effect.
File Draggable Directive: The file-draggable event has been removed. Use filesDropped instead to get the same effect.
Search control component: The QueryBody, and customQueryBody inputs of the SearchControlComponent have been removed. See the Search configuration interface page to learn how to get the same functionality.
Document list component: Several inputs have been removed or replaced:
- The skipCount input has been removed. You can define the same value in pagination using the pageSize property.
- The enableInfiniteScrolling input has been removed. To choose the pagination strategy, add either the Infinite Pagination Component or the normal Pagination Component and assign your document list as the target.
- The folderNode input has been removed. Use the currentFolderId and node inputs instead.
The SettingsService class has been removed. Access the equivalent properties with the App config service
Form service: the addFieldsToAForm method has been removed.

Relocated classes

The following classes have been moved from their original libraries to the Core library. You should modify your code to import these classes from @alfresco/adf-core.

DownloadZipDialogComponent (formerly Content Services)
NodeDownloadDirective (formerly Content Services)
CommentsModule (formerly Process Services)
CommentListComponent (formerly Process Services)
CommentsComponent (formerly Process Services)

Also, CommentProcessModel was moved from Process Services to Core and renamed as CommentModel. You should update both the name of the class and the import line in your code.

Renamed items

The items listed below have been renamed (the old names have been deprecated for some time but have now been removed). If your code refers to the old names then you should replace them with the new ones.

Classes

CommentProcessModel was moved from Process Services to Core and renamed as CommentModel

Properties and methods

<adf-form>: The onError event has now been renamed as error.
<adf-viewer>: The fileNodeId input that supplies the Node Id of the file to load has been renamed as nodeId.
<adf-upload-drag-area>: The parentId input has been renamed as rootFolderId.

Component selectors

adf-filters is now adf-task-filters.
adf-node-permission is now adf-check-allowable-operation.
analytics-report-list is now adf-analytics-report-list.
analytics-report-parameters is now adf-analytics-report-parameters.
context-menu-holder is now adf-context-menu-holder.
diagram-alfresco-publish-task is now adf-diagram-publish-task.
diagram-sequence-flow is now adf-diagram-sequence-flow.
file-uploading-dialog is now adf-file-uploading-dialog.

CSS classes with "adf-" prefix added

A new style linting rule requires all CSS classes defined by ADF to have the prefix adf-. If you use modified versions of these classes then you will need to add the adf- prefix to the appropriate class names for them to be recognised.

The names of the changed classes are listed below according to the file in which they are defined. The new form of the name (ie, with the adf- prefix added) is listed but there are a few exceptions where the names were also altered in other ways. These changes are noted with an arrow "->".