While looking for a replacement for an Alfresco Workdesk solution for our client at USDA, I heard from a co-worker that Alfresco had released their next generation UI Framework, aka Alfresco Development Framework (ADF), to replace their Share framework.
After reviewing the community documentation and list of components catalog, I determined that ADF could be a suitable replacement for our client. After doing a few prototypes and then refactoring ADF as the replacement UI solution for our customer, I learned the following, which may be useful for the Alfresco development community.
This blog describes how to get ADF running and then discuss the pros and cons of the product. Subsequent blogs will follow, which will further decompose and discuss other salient features of the framework and why it is a good alternative to Share.
Prerequisites
To use Alfresco Development Framework, you must meet the following requirements.
- You need Alfresco 5.2 or above – since ADF is dependent on the Alfresco API specifications in Alfresco 5.2, the minimum requirement to use it is Alfresco 5.2.
- If you want to use Alfresco Development Framework with both ECM (Alfresco) and BPM (Activiti) – you will need Activiti 1.5.1 or higher as well. ADF is fully integrated with both with no dependencies on having one or the other.
- You also need to enable Cross-Origin Resource Sharing (CORS) on both Activiti BPM and Alfresco ECM
Why Alfresco Development Framework
The first question that everyone asks is why ADF? The most prominent answers are:
- It uses up-to-date UI technologies – Alfresco Development Framework is based on the Angular JS framework. It is always up to date with the latest version of Angular. This provides an improved, fast and flexible single-page experience. We can easily incorporate, extend and customize different Angular components and services into the application easily.
- It uses out-of-the-box components – The ADF team has already developed multiple components that can be used without any custom code. All the components are easily configurable and manageable. You can find a list of components
- It is easy to connect to Alfresco Content Service (ACS) – As ADF is fully dependent on Alfresco, its use and integration with Alfresco is easy to configure. ADF leverages Alfresco’s REST APIs to communicate with the Alfresco content repository. These REST APIs are utilized using Alfresco-js-api.
- It is easy to integrate with Alfresco Process Service (APS) – If you plan to use ADF only with Alfresco Process Service (APS, i.e., Activiti BPM) or with both ACS and APS, the configuration is still simple. Again, ADF uses Alfresco’s REST APIs to communicate with Activiti. For out-of-the-box ADF, the configuration can be done by simply changing one JSON file.
- It is easy for developers to get started – There is a lot of documentation, guides, demos, and tutorials to get anyone up and running with Alfresco Development Framework, including those with little Angular experience. You can also use the demo shell (Alfresco Content App – fully developed app) to get started.
- It is recommended over Share by Alfresco – Although Alfresco will continue to maintain Share, they recommend custom applications be developed using Alfresco Development Framework. In addition, customizing Share is cumbersome and complex compared to ADF. Unlike Share, ADF is the best solution for a simple and flexible application.
My Experience
When I first heard about Alfresco Development Framework, I was not too familiar with Angular, so I spent some time educating myself with the Angular JS 2 framework. It is quite different than version 1 of the framework, so anyone wishing to migrate an application from version 1.x to version 2.x, plan for a multi-month effort.
After my initial education and training period, things got easier. The ADF documentation and catalog gives some insight on how to get started working with ADF. For our project, we only needed to use ADF with (ACS). However, based on this experience, using it with APS or both should be nearly the same experience.
Major Alfresco Development Framework Components
Listed below are the major Alfresco Development Framework components that were used in our project and would most likely be used in other AD projects. A brief description of these is provided, which will be followed by detailed examples in subsequent blogs.
Login Component – The main login page provides basic username-password authentication, using Alfresco REST APIs to authentic the user to the content repository. Alfresco ticket authentication is used across the application and the ticket is added to every request after the user’s initial login. The login page can be customized as-needed by adding or removing some of its properties.
Document List Component – The document list is used to access, view and manage folders and documents in the Alfresco content repository. The document list table view can also be easily customized to display custom and out-of-the-box properties in the table column.
Content Action Component – This is used to add actions to a Document List. Content Actions can be used to perform many out-of-the-box repository actions like copy, move delete, download, etc. I also added custom actions by creating Angular components and executing them from the Document List.
Data Column Component – As mentioned above, this can be used to display the metadata of a folder or a document in the Document List and can be used to sort the columns and display custom properties.
Pagination Component – This component can be used to add pagination to a component. I used this in the Document List component to paginate the listed documents, and in the custom, search component to display paginated search results.
Tool Bar Component – I used this component as a container for headers, action, and titles.
Viewer Component – This is one of the major components that Alfresco ADF includes out-of-the-box. The viewer converts files to PDF for preview. This component can easily have added to the Document List.
Challenges
I faced some challenges on my first Alfresco Development Framework project.
- ADF upgrade is frequent – This is a positive most of the time, but sometimes it caused instability in UI. During the upgrade, some of the CSS customization were overwritten and messed up. For instance, I started using ADF version 2.2 and then upgraded to version 2.3. When I upgraded to version 2.4, the UI customizations were messed up. Therefore, I stayed with version 2.3.
- Proxy settings and deployment – If you deploy the application in the same webserver container as Alfresco, there are no problems. But in my case, I deployed the ADF application to a separate webserver. To resolve this, I included the ADF application in a springboot project and used zuul proxy-to-proxy the requests to access Alfresco
- SSO – Single sign on using external configuration was not easy to integrate. According to the ADF Team, this was implemented in Alfresco 6.0. After version 6, Alfresco added the ability for an external application to connect to Alfresco through single sign on. This was implemented using Keycloak and JWT tokens. If you are using Alfresco 5 with Kerberos, the default ADF configuration should work fine, but if you use any other external SSO with Alfresco 5, you will need to develop your own implementation from the Alfresco side and design a new login component on the ADF side.
Conclusion
When looking for a UI framework to integrate with and manipulate Alfresco or Activiti, ADF is the best choice. It provides a modern UI framework with many pre-built, out-of-the-box components. The steps to get started and integrate the framework are easy, which is another plus.
The Alfresco Content Application (ACA), the sample application shipped with ADF, can be used to get started. This sample application touches on most of the out-of-the-box features of ADF. I recommend starting with this application when developing with or customizing your ADF application.
I recommend ADF for anyone looking for a new user interface to work with Alfresco or Activiti. The challenges I face were resolved with some custom coding and twist. The ADF community is always available to help if there are any challenges during development and customization.
As we learn and implement this evolving technology into our internal and customer solutions, we will provide our lesson learned for the entire Alfresco ADF community.
Helpful links
- Getting started page
* https://community.Alfresco.com/community/application-development-framework
* https://community.Alfresco.com/docs/DOC-7172-creating-your-application-with-adf
- ADF (Ng2) – components
* https://github.com/Alfresco/Alfresco-ng2-components/blob/master/docs/README.md#adf-core
* https://Alfresco.github.io/adf-component-catalog/index.html
- Supportive materials
* https://angelborroy.wordpress.com/2016/07/17/a-complete-vision-of-Alfresco-developer-framework/
* https://github.com/Alfresco/Alfresco-js-api#login
- Videos
* Alfresco DevCon 2018: Play with ADF 2.0
* Tech Talk Live #100: Application Development Framework
- Webinar
* Get Started with Alfresco’s Application Development Framework (ADF)
Great job guys and USDA is very happy with the this solution to replace Alfresco Workdesk