Book Review – Learning Alfresco Web Scripts

Learning Alfresco Web Scripts

This is a review of the book – Learning Alfresco Web Scripts, written by Ramesh Chauhan and published by PACKT. I did not receive any compensation for writing this review. I did receive an electronic copy for reviewing.


Alfresco web scripts are used to integrate clients with Alfresco via RESTful web services. They are an alternative to CMIS and SOAP and provide tighter integration and extra features.

I found the book easy to follow and an easy read in general. It is suggested for new alfresco developers and offers depth for experienced developers. Some chapters could be used as a reference as well.

The book is structured as follows. It starts with an overview of Alfresco web scripts. Then it gets hands-on right away with a simple web script. It gradually adds detail to the implementation before diving into the details of the architecture and implementation. Then it moves to more practical concerns such as deployment, troubleshooting, and configuration management using Maven. It ends with guidance on extending the framework.

In technical books, I always look for tips and information that comes from experience. Reference material alone doesn’t cut it as much of it may be available online, and the printed material becomes outdated quickly. This book does have tips on when and where to use specific choices, best practice recommendations for various options, and troubleshooting tips for various errors. It also has provides some general tips such as dealing with client limitations.

The approach to the technical material is in a form somewhat similar to a tutorial. It shows code samples, discusses the related concepts, and provides steps for trying it out.

I did notice some naive statements though the intent of the author is obvious in such situations. I could only smile at the statements to the effect that “every question has an answer” and “production servers cannot be restarted”.

On a more serious note, it would have been nice to use a single scenario throughout the book to tie all the examples together into one solution at the end. This was a feedback that I got on my first book, and it made a huge improvement in its second edition.

Overall, I feel that this book a good resource for anyone integrating systems with Alfresco as a back-end system.

Restoring Tomcat6 after Fedora 14 upgrade

FedoraI had Alfresco 3.2r2 deployed in tomcat6 on Fedora 12 64-bit Linux. As it has become so easy to upgrade Fedora now, I decided to upgrade to Fedora 14. I backed up the data directory and the Alfresco webapp directory (because it had customized configuration), and then started the upgrade using preupgrade. It downloads everything that is needed for the upgrade, and the system remains available during this period. The upgrade starts on the next reboot.

The upgrade completed without any problems. However, the tomcat6 service won’t start up. There seemed to be multiple issues, such as the conf directory being empty. Updating tomcat6 using yum didn’t do much. So I removed and reinstalled tomcat6 as follows:
yum remove tomcat6
yum install tomcat6

That restored the conf folder but now I ran into class-not-found exceptions. It turned out that the Tomcat jars were present in a location different from the expected one. On further research, I discovered that the complete tomcat6 deployment consisted of several packages (tomcat6-lib, etc.), and the installed packages couldn’t be relied upon even though yum believed that they were installed/configured properly.

I decided to remove the tomcat6* packages using yum remove for each package listed by
yum list tomcat6*.

Then I installed tomcat6, which also installed the packages that it required. Tomcat6 was up and running in the first attempt after that. Alfresco also came up without any problem after I restored its webapp folder.

Book Review: Alfresco 3 WCM

Alfresco 3 WCM Book This is a review of the book – Alfresco 3 Web Content Management by Munwar Shariff, et al. Click on the cover image to see the publisher’s page for the book. The book is published by PACKT Publishing – an active supporter of open-source projects.

Disclaimers / Disclosures

  1. This review represents my independent opinion.
  2. I have not been paid for this review.
  3. The publisher has provided me with a free copy of the book for writing this review.

Approach

This review does not attempt to provide information about Alfresco or WCM outside the context of the book. The review focuses on what the book offers, what it does well, and where it could have done better. Content outline and information about the authors is present on the publisher’s page for the book.

Review

When I received my review copy I had the following context about the subject of the book. I had reviewed a few Alfresco books over the last couple of years. I had deployed Alfresco recently on 64-bit Linux. I was familiar with the earlier rudimentary WCM features of Alfresco, but I had also heard about significant recent enhancements in this area. Once I started reading the book, I also put on the general reader hat looking for the desirable features of books in general.

In this review, I first share the things I liked about the book. Later, I will share the things that could have been better; these range from possible inaccuracies to minor annoyances.

Positives

This book is filled with code examples, which will aid anyone trying to implement the corresponding features. The examples are usually accompanied by detailed, step-by-step instructions. Many examples are also accompanied by good illustrations with bubbles/annotations on screenshots. In particular, I liked the nice figures illustrating content delivery and deployment.

The book contains good detail on installation, and the configuration details for various platforms are also likely to be helpful. When I had installed Alfresco on Linux 64-bit/Tomcat 6, I would have really benefited from such information since some details had changed across versions of Alfresco, Fedora, and Tomcat . However, I have some concerns regarding a few discrepancies in this area. For example, page 29 indicates that JDK5 is used for the book, but page 21 indicates that JDK 6 required. Page 29 indicates that the examples were created with Tomcat 6, but page 78 indicates tomcat5w. This mixing of two sets of product versions may lead to some surprises while following the instructions. Though this is not an issue, I was a little surprised to see that the Eclipse release from 2007 was being recommended on page 30 while most other product releases are quite recent.

There is excellent coverage of relevant topics for Alfresco WCM. These topics include Advanced Versioning Manager, sandboxes,  virtual server configuration, defining web forms, customizing the editor, workflows, custom workflows, dynamic customization, multi-tenant environments, multi-site configuration, templates and asset reuse, deployment approaches, Alfresco Surf, in-context editing, web scripts, integration with external systems (Liferay, Drupal, J2EE web applications), Alfresco framework (security, video transcoding, image transformation, advanced search, metadata extraction), and administration (data backup, upgrading, maintenance, authorization, resetting the entire repository, migrating servers).

I like books that provide recommendations based on practical considerations and experience. This book provides such recommendation for workflows among several topics. For example, it discusses performance impact of number of workflow instances.

Areas of Improvement

The book has several minor issues related to typos, grammar, and similar concerns. As these issues may have escaped the review process, I am sharing here what I noticed. I am inserting my suggested corrections in [ ] below.

Page 26 has, “It is designed in [for] non-critical Environments.” Page 127 has, “Rendition templates simplifies [simplify]and accelerates [accelerate]”. Page 230 has, “only [a] few files.” Page 256 has this tautological sentence: “you can create as many web projects as you can [desire/wish/want].”

The text has some instances, which probably make things difficult for readers. The first figure on page 11 introducing the Alfresco WCM model is not explained at all. On page 12, the figure is introduced by “One temporary workflow sandbox per active workflow instance per web project:”  but there is no mention of a workflow in the figure and there is no further explanation regarding this.

The  section Alfresco WCM Model on page 11 is probably foundational for the whole book. It would have been nice to have an illustration of the model with a figure which tied together the concepts described in this section. The delivery models are illustrated, and the individual WCM model concepts are illustrated, but no complete WCM model illustration could be found.

The physical architecture diagram on page 25 is not explained. In this diagram, the meaning of arrow direction doesn’t seem obvious. The authoring environment is pointing to receivers and the portal cluster is also pointing to the receivers. Should one interpret it to mean that they are both pushing data to the receivers? It seems that similar looking arrows mean different things in this diagram.

The book lists some situations where WCM could be recommended. It isn’t clear though if it is not recommended when one of these considerations is contradicted. For example, it sounds like WCM is not suitable if anything more than “Submit for Approval” is needed by way of workflow.

On page 222, the zero workflow is discussed but not defined. One can start guessing based on the material what the zero workflow is, but it is not defined. The closest it gets to a definition is in the summary of the chapter, “Implementing ZERO workflow gives the flexibility to submit content using workflows without selecting any user/group.” The reader is left guessing whether that is one feature of the zero workflow or its defining characteristic.

The book has some assertions, which appear simplistic or biased. Page 10 compares Wiki-style and Publishing-style CMSs and some statements appear not to be well informed. I don’t know about all the products listed but here are some thoughts about Drupal. It uses themes and CSS, separating presentation from content. It can allow content revisions and approval workflow on a particular version while another version is live. Whitehouse.gov runs on Drupal and that should refute the “small site” argument. While I get what the authors are trying to say, I wish their arguments were a bit more nuanced. SharePoint doesn’t even get a mention in this mix.

Some assertions in the book appear to be misleading. Page 122 discusses how to dynamically populate drop-down lists, but the example shows how to statically specify the drop-down values in the schema. If this could somehow be dynamic, the text doesn’t explain it. Page 231 asserts, “This feature is very powerful even from a legal audit point of view, wherein you have an ability to reproduce the website as of a specific date.” This statement needs to be qualified by a statement that for a data-driven web-site it may be insufficient without also taking snapshots of the database.

In my experience, WCM systems require two kinds of quality assurance (QA). One kind is the QA of content production, which is accounted for by sandboxes and the approval process. However, this QA happens within one environment. The other kind of QA is needed for the customization of the WCM system. Such changes would include defining new content types, XML changes, web script changes, etc. In most organizations, such changes cannot be made directly in the production environment. There are typically development and/or QA environments for the QA of the development efforts. The book does not address this aspect of WCM.

Conclusion

This review has given more space to the things that could have been better, but most of these things are minor annoyances. However, my take on the book is that it is a handy reference for the exact steps and examples when you are implementing Alfresco WCM. In order to make the best use of this book you may need the knowledge of Alfresco fundamentals and a general understanding of WCM concepts from other resources.

Book Review: Alfresco 3 Web Services

Alfresco 3 Web Services book This is a review of the book – Alfresco 3 Web Services by Ugo Cei and Piergiorgio Lucidi. Click on the cover image to see the publisher’s page for the book. The book is published by PACKT Publishing – an active supporter of open-source projects.

Disclaimers / Disclosures

  1. This review represents my independent opinion.
  2. I have not been paid for this review.
  3. The publisher has provided me with a free copy of the book for writing this review.

Approach

This review does not attempt to provide information about Alfresco or web services outside the context of the book. The review focuses on what the book offers, what it does well, and where it could have done better. Content outline and information about the authors is present on the publisher’s page for the book.

Review

I browsed through the book as soon as I received my review copy to get a feel for its contents. It appeared to a be a handy reference for building applications or integrations with Alfresco using its web service interfaces. While this impression held well as I went through the text, I made some additional observations.

At a high level, this book is organized into three parts – SOAP-based access to Alfresco, REST-based access to Alfresco, and CMIS. I would have loved to see this organization made explicit as Parts 1, 2, and 3. Currently, the description of this organization is hidden in a small paragraph in the preface, which many readers may miss. An introductory chapter relating the high-level concepts and introducing Alfresco would have made the book significantly more reader-friendly. I felt that the book assumes certain knowledge of content management concepts and of Alfresco, but this assumption is not made explicit in “Who this book is for”.

The book does well when it comes to getting into the details of features and capabilities. These details are made accessible to the reader using examples and real products as diverse as Alfresco SDK, FreeMarker, Apache Chemistry, Google Web Toolkit, and MyLyn WikiText parser. The book uses a Book Shop model for a large number of examples, but it also refers to other smaller examples depending on the context.

It also does a good job of introducing the concepts and standards related to SOAP, REST, web scripts, FreeMarker templating, Atom, AtomPub, and CMIS. CMIS deservedly gets a lion’s share in the text as it is a standard means of interaction with any content repository implementing this interface. As many of the content management heavyweights have backed CMIS, it is likely to be supported widely. The discussion on CMIS includes AtomPub and Web Services bindings, CMIS query language, and an example of building a complete CMIS  client application.

The bookshop example is used as a key example in the book. The details of the example appear somewhat contrived to enable explanation of the relevant concepts. There is nothing wrong with an example being contrived in this manner; actually, it serves well to illustrate how to accomplish the desired effects. I just expect the text to make it clear that the example is a contrived one. The book, however, refers to it as a “real case”. I am wondering why I would implement a bookshop web site on Alfresco in real life. There could be a plausible reason but it was not explained. In my mind, I would need some content management requirements to use Alfresco, and I would probably limit the role of Alfresco to that extent in the commercial web site. Further, the example was mostly focused on metadata, and I kept wondering why I wouldn’t just use a database rather than a content repository.

I am not belaboring the bookshop example for its own sake as I admitted that it does well to illustrate the interface details. In my mind, it represents a missed opportunity for the book. In general, the book could have provided more advice on when to do something in addition to how to do it.

Conclusion

Overall, I found the book to be a handy resource for anyone working with Alfresco or content management web services. If you know the specific things that you need to do it can be an excellent resource showing you how to do it. If you need to make choices before implementation, you may need to utilize additional resources. If you are new to Alfresco and content management, you may want to look at additional resources first.

Alfresco Coming of Age?

I have worked with Documentum way longer than with Alfresco. Couple of years ago I started dabbling with Alfresco and started using it as a personal content repository at home. It was ridiculously easy to set up and exceptionally stable on Linux even with that early version. At that time, most Documentum professionals I talked to wouldn’t give a serious thought about it.

How times have changed! I think that recession may also have helped Alfresco like it is helping organizations such as Walmart and Kroger. These stores near my home have renovated and look overstocked. And they are not dealing in just the traditional stuff. The Walmart store seems to be stocking all the stuff that I would usually go to Home Depot for! But this is not a post about recession so let me not digress.

Let me not take anything away from Alfresco. It is earning the reputation based on its virtues – the recession may just be hastening its arrival on the grand stage. Quite a few professionals still mention it with caveats about its suitability for non-critical systems. I feel that it is just a matter of time.

Within the last few months I have seen two Documentum vendors become Alfresco partners. There are probably more but these are the ones I have known well and worked with. With the discretionary spending drying up it seems that service providers are being forced to diversify. The Alfresco market should definitely help them get the sales pipeline filling up again, even if at lower rates.

Then there are respected Documentum professionals such as Laurence Hart (Pie) and Johnny Gee who have started exploring Alfresco and sharing their opinions. I am sure there are many others in the Documentum community in a similar situation. I haven’t gone out trying to identify any trends – these are just the thoughts triggering from the events in my usual environment. When Documentum professionals get seriously involved with Alfresco, I can envision cross-pollination of ideas and experiences resulting in creative and effective solutions for customers.

Book Review: Alfresco Developer Guide

Alfresco Developer Guide

This is a review of the book – Alfresco Developer Guide by Jeff Potts. Click on the cover image to see the publisher page for the book. The book is published by PACKT Publishing – an active supporter of open-source projects.

Disclaimers / Disclosures

  1. This review represents my independent opinion.
  2. I have not been paid for this review.
  3. The publisher has provided me with a free copy of the book for writing this review.

Approach

This review does not attempt to provide information about the Alfresco platform outside the context of the book. The review focuses on what the book offers, what it does well, and where it could have done better. Content outline and information about the author is present on the publisher’s page for the book.

Review

While Alfresco by Munwar Shariff got you started with Alfresco, Alfresco Developer Guide by Jeff Potts gets you going. The first book provides good overview of the breadth of features and Alfresco Developer Guide dives deep into customization for Alfresco-based solutions. Content management is a general requirement but its applications vary significantly. Without accommodating the specific needs of the business, a content management system (CMS) would usually be little more than a glorified file system.

As I started reading the book, it quickly became evident that the author had significant hands-on experience with customizing Alfresco. The book has detailed examples with code and screenshots. The step-by-step directions with practical advice and recommendations make it easy to follow. The book uses Alfresco 2.2 Enterprise and 3.0 Labs versions. In one sentence, I would characterize this book as an illustrated handbook for customizing Alfresco.

The book starts with a description of the Alfresco Platform. This includes overview of content management, the architecture of Alfresco-based solutions, the example used throughout the book, and various kinds of customizations that can be done with Alfresco. It is followed by directions for setting up an Alfresco development environment using Eclipse. Detailed discussion of customization starts with creating custom models – which includes types, associations, and aspects. The UI changes and programmatic access to go with custom content model are also discussed. Automated processing of content with actions, behaviors, transformers, and extractors is discussed next. Web client customization discusses how to adapt the UI for specific needs. The book also discusses implementation of RESTful API using Web Scripts. Workflows are an important feature of content management systems. The book discusses implementation of advanced workflows using jBPM. jBPM enables you to implement complex workflows within Alfresco platform. Web Content management is a popular and common application of content management systems. The book discusses web content management on Alfresco using Alfresco WCM. The book concludes with a discussion on security, including incorporating Alfresco in a Single-Sign-On solution. The appendix includes API reference and examples.

Given my experience with EMC Documentum, I couldn’t help but compare the details with how I do things with Documentum. This book provided the depth to make such a comparison possible. One would normally use this book as a reference to jump to the task at hand and follow a step-by-step example. If you need to understand the breadth, you can skip over example details and read it in a flow. However, in my opinion, the best value provided by this book is in terms of best practices and practical advice which is hard to find in product documentation.

The author does not skimp on sharing practical advice. A fundamental advice is around separation of solution files from Alfresco files. The author also discusses various options for packaging and deployment of customizations. The troubleshooting tools and practices discussed would benefit any Alfresco developer. Modeling best practices are also very important since the custom content model is usually the foundation of a custom solution on Alfresco. When creating a solution for a large organization, advice about handling large directories for user/group synchronization would be handy. Other tips such as dealing with cross-domain scripting limitation and implementing Single-Sign-On also add value.

I think that it is a great book for people who are already working with Alfresco or another content management system. Readers new to the content management space may need a gentler introduction to the concepts and to Alfresco before they can derive maximum value out of this book.

Conclusion

Even if you had the expertise to write this book, you might want to keep a copy handy if you frequently implement solutions using Alfresco. If you are new to Alfresco this book is even more valuable. If you are new to content management in general then you may want to ramp up with some other resources before making the best use of this book.