Nine Things You Must Know about Alfresco - an Open Source ECM System

As mentioned earlier in my post that I have contributed an introductory article about Alfresco on Open Source For You which is a complete magazine on Open Source and plays an important part of Open Source culture in India.The article has got published in Open Source for You print magazine for May-2016 edition.

Book Review - Alfresco for Administrators

I have just completed reading the recently published book on Alfresco titled Alfresco for Administrators authored by Vandana Pal, published by Packt publishing. This book is a fast paced guide providing details about various things you should know while administering Alfresco. In general, it is a good book and I thought to share my review here with you. Hope it would be useful to you.

In summary

A quick read and handy book focusing on administration part of Alfresco primarily the enterprise version. This book will make you familiar with the various aspects of administration part of Alfresco. Author has done a good job to keep the things simple and explain the details in simple and easy to understand way. For example, some details such as clustering, search, various consoles in Alfresco, upgrade process, roles and permissions and so on are explained nicely in very simple words that will surely help someone new to Alfresco to understand these concepts. For best practices or tips and tricks, this book will give you pointers at high-level and you may have to explore them based on your application scenario. From the execution part of the book, I found some typo errors, inconsistencies in mentioning the same thing at various places and some text formatting issues, which as a reader I do not like while reading the book. Overall I would give 3.5 stars to this book out of 5. Good one for newbies to Alfresco and quick fast paced reference guide to seasoned Alfresco professionals. 

If you are interested in chapter by chapter review, following is the chapter wise review in full length.

Chapter-1 - Understanding Alfresco - provides an overview of Alfresco and mentions some of the key features of Alfresco, describes about Alfresco architecture and how alfresco can be used in ECM requirements.

• The way chapter goes step-by-step from overview to features to architecture to business use cases is really good. However, in my opinion, some details should have been presented in more appropriate way so as readers can benefit more. For example, it says that "Alfresco Community Edition is only for small-scale development or research purposes. It is not recommended for production systems as there are certain functional differences." Instead, it could have been represented in a better way, such as - "Any small to medium businesses can use Alfresco Community Edition in production in non-critical applications considering in mind that it needs to be self-supported with the help of community resources."
• It points to the following link - https://wiki.alfresco.com/wiki/Enterprise_EditionAlfresco for differences between community and enterprise editions. However, this wiki page is outdated and does not have any content.
• The feature section does not specifically describes the new features available in Alfresco 5. However, it provides the generic features of Alfresco as an ECM, that is good so as user can know the overall features in Alfresco. In features section, Transformation capabilities of Alfresco could also have been added.
• Under external integration section, it is only mentioned about Java based portal such as Liferay. However, you can have any custom front-end which can invoke REST calls and connect to alfresco using REST APIs.
• Alfresco architecture diagram is at very high-level. "Rest" should have been mentioned as REST I think. If you are a newbie to Alfresco then from Alfresco documentation, you will get the more appropriate and detailed understanding of Alfresco architecture. I will prefer to use that for getting Alfresco architecture understanding if you are a newbie.
• I really like the way business use case for Document management is explained with Contract Management example which gives good insight about how Alfresco can be used as Document management system.

Chapter-2 - Setting Up the Alfresco Environment - takes you through installing alfresco through an installer wizard on windows, then installing alfresco manually in Linux with MySQL database and Tomcat server. Next, it explains installing alfresco with postgreSQL database on JBoss server. You may be already familiar with all of it if you are experienced working with Alfresco. However, new comer may find the details provided here as useful.

I was very excited when I read the section header - Troubleshooting tips and best practices. This section does provide some very good tips and tricks. However, there weren't any supporting examples there. It is pretty much describing the tips in very generic way. For example it says that, Based on your application needs, there should be enough memory allocated on the server. It would have been great if an example would have been provided which describes memory allocation requirement for a sample use case application. For most of the tips, I found supporting examples missing. If there would have been example with each tip (where possible), it would have added a great value to the book and would have been very useful for the readers.

Chapter-3 - Alfresco Configuration - covers the various configurations in Alfresco. Although this chapter is having some good information, I found typo errors and formatting oversights here and there in the whole chapter as following

• Typo on first page, <TOMbCAT_HOME>. 
• Somewhere the paths to location of files in Alfresco are referenced using <TOMCAT_HOME>, somewhere they are referenced using <install_folder>. Consistency here would make reading easier from reader's perspective. 
• Formatting of entire XML code snippet was having extra double quotes as following <bean id=""googledocs""...which does not help to make the reading experience better. 
• Another, formatting related issue was about, Fonts are of code style for description of content store related properties. It should have been regular text there. Same thing goes for search engine related properties and for properties of other sections as well for making it is easy to read. 
• Another one is, In Auditig section - "Using audit, trail administrators..." should be "Using audit trail, administrators..."
• It is mentioned that - repository.properties is moved to a JAR file. Name of the JAR file could have been provided for easy read and would have surely helped.
• Then to a surprise, under Auditing section, location of repository.properties file is provided which is not a correct location. As described earlier, It is in the JAR file.

I really like the explanation of category and type for subsystems and how the folder structure looks based on the sub-system category and type name and it is very clear to understand.

Chapter-4 - Administration of Alfresco - talks about Administration of Alfresco. You will find some useful information about administering alfresco using different consoles available. I am not sure why Alfresco web client is covered here as it has already been deprecated and overall the book mainly focuses on Alfresco 5. Along with useful information, I again came across some typo/formatting issues as following.

• There is a sentence - "let's say the marketing team is your Alfresco repository" under Model and Messages Console section does not make any sense. Looks like some meaningful sentence has been formatted while editing.
• Also, the admin group name is specified wrongly under section Admin console in Alfresco Share. It should be ALFRESCO_ADMINISTRATORS instead of Alfresco_Administrator.
• Again while pointing to the code location in alfresco installed directory, I found <Alfresco_Home> is used. In earlier chapter it was used as either <TOMCAT_HOME> or <install_folder>. It should have been consistent everywhere.

If we ignore these minor mistakes then this chapter is certainly having very useful information you must know.

Chapter-5 - Search - is all about search using solr in Alfresco starting from installing solr separately, understanding the folder structure, configuring it, administering using the search admin console. I have stopped looking at the typo errors now and focusing more onto the content only. This is a good chapter and helps you understand how search works using solr in Alfresco in a better way. In my opinion, Full re-indexing process in solr could have been explained in a better way as for a newbie to follow the present way it has been explained may be bit time consuming and bit difficult to follow.

Chapter-6 - Permissions and Security - Really a very good chapter. Roles in Alfresco are explained very nicely and very easy to understand. As compared to earlier chapters, here OOTB file placed in a jar is mentioned with appropriate JAR name which is really helpful. However, there is a repetitive 

section for permissionDefinitions.xml mentioning its JAR file location. 

Also, to access alfresco server, somewhere it is mentioned as hostname:port and somewhere ipaddress:port. Even though both leads to the same, however consistency would surely have helped reader. (I mentioned I stopped looking at typo/formatting, but as these one were came across straight to my eyes so thought to add here)

Chapter-7 - High Availability in Alfresco - explains about the basics of clustering and how to achieve it in Alfresco in very simple words and you can easily understand the concept. Backup and restore process are also nicely explained. As an administrator, you will find this chapter very useful.

Chapter-8 - The Basics of the Alfresco Content Store - describes all the required details about content store such as the important directories, caching, encrypted content stores and so on. It also then provides a walk through about some of the key tables in Alfresco database schema. Any quick examples would have been great here if provided such as in which scenario you may want to troubleshoot from database and how you will do it. Later in the chapter, content life cycle in Alfresco is explained very nicely. Easy to read and understand. In my perspective, This chapter could have been placed after chapter-4.

Chapter-9 - Maintenance and Troubleshooting - provides an overview on how to monitor/configure Alfresco using JMX without server restart. Some useful points about JVM tunning, disk space maintenance, database tuning and monitoring are provided which are helpful to know for every administrator. Later in the chapter you will find details about how to get audited entries from Alfresco which is also useful.

Chapter-10 - Upgrade - explains about the upgrade path you should follow when moving to the newer version of Alfresco from the earlier version. A diagram would have added more value and could have helped reader understand the upgrade path easily. You will find the upgrade guidelines provided here as useful. Overall good and informative chapter to get introduced to upgrade process in Alfresco.

2 out-of-the-box repository REST APIs you must keep handy while working with content in Alfresco

As an Alfresco developer, you should always know some of the basic things about content, such as - How to view a content? How to download a content? How to list down all the content from a folder and so on. In Alfresco, you have out-of-the-box repository web scripts available which takes care of all of the above. You must keep yourself familiar with these web scripts.

Let's take a look at 2 very useful content related repository web scripts (which basically are useful for 4 things). In my opinion, you must keep these 2 web scripts handy with you while working on any alfresco implementation. I have used Alfresco 5.1 Community Edition here.

1. View Content

In order to view a content, you should make a GET request to the following URL.

http://localhost:8080/alfresco/service/api/node/content/workspace/SpacesStore/18d2fa04-70ba-4865-afe6-e097b75f0576
Note:You must replace server, port and nodeid in the above URL as per your implementation.

When you hit the above URL, it will display the content in your browser. You may use it for previewing the content.

You can take a look at the description document of this web script at the following URL and can also try out the different URL options supported for viewing a content as mentioned there.
http://localhost:8080/alfresco/service/description/org/alfresco/content/content.get

2. Download Content

To download a content, you will be using the same web script we used above however only additional option that you will provide is a querystring parameter a=true

http://localhost:8080/alfresco/service/api/node/content/workspace/SpacesStore/18d2fa04-70ba-4865-afe6-e097b75f0576?a=true

When you hit the above URL, it will download the content.

3. Get list of contents from a specific folder

To  get a list of all the contents of a folder, you can hit the following web script.

http://localhost:8080/alfresco/service/slingshot/doclib/doclist/documents/node/workspace/SpacesStore/e0856836-ed5e-4eee-b8e5-bd7e8fb9384c

As highlighted in above URL, when you specify documents, it fetches all the documents for a given folder.

Description document for this web script can be found at
http://localhost:8080/alfresco/service/script/org/alfresco/slingshot/documentlibrary/doclist.get

3. Get list of  the contents & folders from a specific folder

To get a list of both contents & folders from a specific folder, you can hit the following web script. It is basically the same web script we used in #3. Only difference is, instead of specifying documents we will specify all there. If you specify anything except documents then it will list down both content & folders.

http://localhost:8080/alfresco/service/slingshot/doclib/doclist/all/node/workspace/SpacesStore/e0856836-ed5e-4eee-b8e5-bd7e8fb9384c
OR
http://localhost:8080/alfresco/service/slingshot/doclib/doclist/both/node/workspace/SpacesStore/e0856836-ed5e-4eee-b8e5-bd7e8fb9384c

One important thing to take a note over here is that both the above web scripts have lifecycle mentioned as internal. Hence, they are for alfresco internal use only and there may be the chances that it may get changed in future versions of alfresco. Hence, if you want to use them for integration purpose in your project then you must keep this point in consideration before using them. However, from a developer perspective it is a must to know about these web scripts available in Alfresco so as it will be helpful to you while working on any content related issue.

Hope this will be useful to you.