Enterprise 2.0 Application Technologies

Sencha Touch

2012-01-17T11:17:00.000-08:00

This blog is outlining my experiences developing a mobile web based application developed with Sencha Touch and packaged with PhoneGap.

I have been developing a quick app for my iphone using Sencha Touch API (currenty 1.1). I have found it quite intuitive and the outcome is that I get a web based app that can be run nicely on Android as well as iOS devices. And I get to develop on my Win based machine in Java. Easy to test without emulator using normal browser too.

The idea is to write code via HTML5 that can be useful on touch based devices such as iPhone, iPad and Android based phones and tabs. Rather than learning languages and frameworks specific to these technologies it is possible to stick to common HTML5 skills that still support touch device like gestures and form factors.

In addition to deploying as a device capable web site, I intend to wrap it up with PhoneGap to deploy it as native binaries onto multiple devices (Android, iOS, BB) with access to native APIs.

The technology I am starting with

I'm not cool enough to develop on a Mac Book, so I'm building on Win 7 Laptop. For my editor, I've been trying out Sublime Text 2. Nice that it opens a folder tree and has smart syntax highlighting for JavaScript, and knows about all the HTML5 stuff (CSS, JSON, HTML, JavaScript) but a full fledged IDE would have things like code complete and syntax checking right in the IDE, so I am also old schooling it and using Eclipse IDE.

I have setup Eclipse IDE (Classic edition) augmented with Android SDK and the emulators, with the ADT Android Developer Tools eclipse plugin. However, for just Sencha touch the android stuff is not needed. But soon i will be looking at PhoneGap to create binaries ready to deploy to devices. And I'm also developing with Android SDK specifically.

I am also building the server side. I have been looking at node.js as a possibility. But I am also looking at Java based solutions as well (I'm showing my age I guess). For the Java based solutions, I am looking at deploying a J2EE (war) app and using Spring MVC as a core framework on the server side.

To deploy as a server based web app (and I also intend to have server side components as well), I have constructed a maven driven web app from a maven archetype (see this great blog article), and assuring it has the web app nature for using eclipse with help and great gratitude from this blog. This process of getting Eclipse to work with Maven for a web app based project was more complex and error prone than I'd like. My desire was to use the IDE to code and build, and see the results immediately synchronized on the integrated web server. But Eclipse doesn't build natively with Maven goals like NetBeans does, and the integrated web server plugins aren't as smart as they should on when to sync, deploy and run. I may rethink this choice as I go along.

To help provide the server stuff I need (remember Im on a Windows platform) I downloaded XAMPP and am running separate a Tomcat instance as an independent deployment target different from the Eclipse integrated tomcat server where I can test changes during development.

For the hosted solution and since I'm deploying to a java based app server (tomcat), I am deploying to jelastic I can test it on my real devices. I also have Android emulators integrated into Eclipse and also iPadian emulating an ipad but I haven't tried that avenue yet.

The real devices I have to test on incude:

galaxy 10.1 tab
iphone 3GS (old I know)

For basic application architecture I have two MVC frameworks!

One MVC on the client (Sencha Touch with MVC pattern) and
One MVC on the server (Spring MVC).

Overkill? we shall see. We will get into the MVC model client and server side in another blog.

For Sencha Touch I am following the MVC pattern as described by the sencha forms tutorial. Also, I have followed a great talk and tutorial from this German developer Nils Dehl where he creates a shopping list app.

For persistence, I have two choices: old school main stream relational (MySQL) or NoSQL approach with MondoDB. I will start out with mondo db and see what happens. The idea is that the data model is going to be json based and object oriented. Structured, hierarchic data can be managed using objects and indexes. For the app I want to build, it may work well. But it seems heretical (not necessarily a bad thing)..

Next article I will get into the app design...

Getting started with Spring Roo, GWT and STS

2011-07-29T17:31:00.000-07:00

Time to get started. I'm going to run through the introductory materials on building a Spring Roo application with the Google Web Toolkit front end. I will be using the Spring Tools Suite as the IDE (based on Eclipse).

I will start by following some initial advice:

on the Google side: here is a google code blog
on the Spring side: here is the springroo start and the Beginning with Roo: The tutorial from Spring Framework reference documentation
another blog (gwtsts.blogspot.com) by Cengiz Öner describing this effort has multi-part instructions

Installation

What I have

Java 6 SDK r26 from here
SpringSource Tool Suite: Version: 2.7.1.RELEASE: Build Id: 201107091000
Using Google Suite Plugin Version 2.3.3.r36v201107211953
Spring Roo (latest production release) 1.1.4 RELEASE

I got Spring Tool Suite bundled with Google Integration from here

After running STS, go to the dashboard and select the 'extensions' tab (bottom). Find and Check Google Plugin for Eclipse and press 'Install' (bottom left)

Restart STS and thats it (for now)

Overview of Spring Pizza Shop Demo

Lets use the Spring Framework Roo tutorial to get started.This tutorial walks us through creating a Roo project including entities controllers and the UI/scaffold. I will try to emphasise use of the STS tool as well as focusinging on using GWT as the front end. To begin with, we will follow the tutorial fairly closely.

Here is the project UML from the spring tutorial that we will create

This is the Roo Pizza Shop demo

First Step Basic Roo Configuration

Spring Roo builds upon Spring framework 3.0 with JPA 2.0. It uses a command line tool to create basic elements of a project, from persistence setup, to creating entities, to creating Spring MVC controllers, to generating Scaffold ui (in our case using GWT).

We can use spring STS to create a new spring Roo project project

From the Dashboard, select Create a Spring Roo Project
Fill out dialog: Project Name: pizza, top level package: com.springsource.roo.pizzashop
Accept all other defaults and press Next (and then Finish). This will create the Roo project and open the roo shell. Actually, STS is executing the roo shell to create the project directory and the roo command:
roo> project --topLevelPackage com.springsource.roo.pizzashop

We see the ROO command shell at the bottom with a command promt inviting us to execute roo commands.

The window has a top part showing a console with roo commands as well as a prompt, but don't be fooled. The roo prompt we use in StS is below (a single line edit).
The spring ROO project leverages Maven2 and its unique project structure.

One cool roo command you will use right away is hint. This will give you possible options to do from the point in your project. In this case,

type HINT and press enter, Roo Shell will respond with a suggestion to do 'persistence setup'
type' persitence setup' and press ctrl+space. In StS, this will use code assist to allow you to select possible next options for the command (the command line, you press the TAB key). In this case we will select --provider HIBERNATE and --database HYPERSONIC_IN_MEMORY
The complete roo command is:
persistence setup --provider HIBERNATE --database HYPERSONIC_IN_MEMORY
Roo will generate the JPA configuration files and initial spring context

Next: Create an Entity

Now we are ready to create some entities and fields

Press Hint again, and Roo will advise you to type ent and press TAB to get the next option (from STS, ctrl+space). This will allow us to create an entity with a specific class name: Topping
Type entity then press (ctrl+space) . This will produce --class
Type ~.domain.Topping for the class name (the tilda will indicate the project's package root (remember we specified com.springsource.roo.pizzashop)
Now ctrl+space doesn't give us more hints since all required options are satisfied, but type double dash (--) and then ctrl+space will give us a bunch more options.
type or select --testAutomatically to generate test classes for the new entity and press enter (the ccomplete roo command: entity --class ~.domain.Topping --testAutomatically)

Roo creates a whole bunch of files and aspects. Notice the actual entity "SRC_MAIN_JAVA\com\springsource\roo\pizzashop\domain\Topping.java" is created. You can see it in the packag tree. However, STS starts with an inital filter in the package tree to 'Focus on Active Task'.

Click the filter icon in the top toolbar of the Package view to reveal the entire project. Now navigate to src/main/java. See the com.springsource.roo.pizzashop.domain package and the created Topping.java class just created.

Next: Create Fields for Our Entity

Now lets add a field. Use the roo command to type field string --fieldName name --notnull --sizeMin 2
THis will add a field, and update/add to the generated aspects based on the annotaitions.

Opening this class, all you see is

Notice the classs annotations that roo adds @RooJavaBean, @RooToString and @RooEntity. These annotations generate aspects with extensions .aj for inter type definitions. Spring also adds JSR 303 bean validation annotations on the field based on the options we specified: @NotNull and @Size(min = 2).

The principle that Roo introduces here is the heavy leveraging of AspectJ's Inter-Type Declaration (ITD). The ITD code generates as a separately complied file, but is encorporated into the class byte code of the advised class. Generally we don't need to bother about what is generated here. But lets look anyway. For instance, the @RooJavaBean annotaion creates the class Topping_Roo_JavaBean.aj. Peeking at it, we see:

File: Topping_Roo_Entity.aj

We see that the name field produced a getter and a setter for the field. As we add new fields, this aspect will be updated. Using aspects this way allows the domain class to remain particularly pure.

As another example, lets look at what was generated for the @RooToString annotation:

File: Topping_Roo_ToString.aj

Pretty nifty, huh! this is the Secret Sauce of Roo as described in Ben Alex' Blog on Roo's Architecture

Finally, lets' look at what Roo does with the @RooEntity declairation

File: Topping_Roo_Entity.aj

Rather than creating a data access object (DAO) or service, Roo assumes that each entity created has its own implementation of persistence. The @RooEntity annotation generates a ITD (Inter-type Declairation) for the entity advising it to add many methods to support persistence, inclding id generation, versioning, access to the entity manager, various transactional methods:

persist,
remove,
flush,
merge,
clear

and various finder methods

count
find by id
findAll
and pagable findAll

Next: Some More entitles and fields

As Roo creates objects, it keeps track of the last object you created. The next command defaults to this target, so there is no need to specify it explicitly. For example, when we created the field, we didn't need to specify what class to create the field for. It assumed we meant the last entity we worked with.. The spring Roo console shows what entity we last worked with in its prompt, much like a command shell might with a prompt showing the current directory path.

Now lets create another entity and some fields similar to the ones we created before. Here are the Roo commands:

That's it. As long as we follow the defaults, things are easy. This is the approach taken by Ruby on Rails: convention over configuration. The command line invokes templated commands to create objects quickly.

Our project should look basically like this (as seen from the project view)

Next: Some Relationships for our Entities

We are still in JPA land. JPA allows us to create relationships as well as if POJO java classes using well known collections. Roo supports a one-to-one or many-to-one reference, a one-to-many 'set' (and also ways to create many-many). In the above, we have a one-many relationship from Pizza to Topping (a pizza has many toppings) and a one-one relationship (reference) to a base. We'll use the Roo command shell to create these too. The tutorial shows there are two relationships from Pizza, a 'reference' to a base (m:1) where a Pizza has one base, and a set of toppings (m:m relationship to toppings), where a pizza has a set of toppings.

The above commands assume you are creating the relationship fields to the last entity you created: Pizza as it would show you in a command prompt. If not, make sure to append --class ~.domain.Pizza to the above commands (at least the first one) to assure the relationships are created for the Pizza class.
And we can finish up with PizzaOrder

Notice the last command creates another relationship, this time an PizzaOrder has a set of Pizzas ordered, which Roo will create a m:m relationship for of type Set pizzas. As you can see, creating entities, fields and relationships with Roo comes down to running a set of commands to generate the appropriate Java code and Aspects according to Roo convention. In fact, you can save these commands as a 'seed' text file that will create a project for you, generating the project structure, configruation, classes and aspects required.

Next: Lets Test

We can now run the integration tests using the roo command perform tests.

perform tests

Finally: Look at the test classes generated

Testing my RESTful controllers with Spring RESTtemplate

2011-07-08T05:17:00.000-07:00

I have been playing with Spring's RESTtemplate as an approach to integration testing on my project.

Overview of Testing a RIA with Spring and Spring VMC

I feel I should create a set of blog posts related to how I am doing testing with this technology stack. Sometimes this aggregation is helpful. In my team, we are testing at the following levels:

unit testing of everyting - pure tests, typically single class only, with mock (using Mockito)
integration testing of our services - out of container (web server) testing, but with db
integration testing of our controllers - in container testing, with db
functional testing of our ui (TBD) - full in container testing

This blog will focus on integration testing.

Integration testing, different from unit testing, tests the code as it is wired up to other components, the server and the data base as well.

Testing the controller layer in Spring MVC

To set the stage, I am using spring 3 with Spring MVC for my application. In particular, I am leveraging a lot of Ajax, accessing the controller from the browser and transporting JSON. I am using the Jackson JSON mapping implementation to marshal to from beans to JSON.

I need to create good integration tests of my controller classes so I can run JUnit tests that connect with the deployed web app and interact RESTfully like the client UI, passing JSON objects back and forth.

A helpful blog post I have used for guidance: is ralf.schaeftlein s blog detailing an approach to integration testing of restful MVC controllers with JSON. Exactly what I was interested in.
The basic steps seem to be:

create a unit test with java4 leveraging Spring 3 Integration Test Annotations
configure your application context XML to define your mappers that will convert between JSON and beans
write your tests pojo style

Integration Testing with Spring uses annotations to supply a spring context to your test code. Further, the annotations specify what transaction manager to use and if a rollback should be performed after the test is complete. The tests itself are written with JUnit4. Here is a snippet showing the annotations required placed on your test class.

In this case, I am testing my Data Repository, which is essentially my Data Access Object (DAO) for you old schoolers. I will post why Repositories and not DAO in a future blog.
My application context file configures spring with the required setup for my application to run this test. First, the usual name spaces:

Then, we use automatic annotation discovery of out project

Here is wshere we configure the restTemplate to be used for this integration test of our controller
Finally the required configuration for our persistence. Notice we are using JPA configuration here

Finnaly the test code.

We write an integration test for our controller that connects remotely to the deployed application, sends beans mapped from Pojo to json for the call, and then maps back json to Pojo to assert results.

A shout out to a framework for html5

2011-07-08T05:11:00.000-07:00

One of my readers sent me a link to Strobe, (http://www.strobecorp.com/) an open source platform built from the ground up to leverage html5, but still leverage MVC. Although my ship has already left down the river of Spring, I can longingly look at its innovation and see what we can adopt for ourselves. I know I will loose a few hours this weekend on playing with this one.

Thanks

PS, I also seem to be wasting my time playing with knew language ides: ever check out Clojure. Yes, it talks with a lisp as well.

Crossing the chasm to the new paradigm

2011-07-08T04:07:00.000-07:00

I titled this post in homage to Moore, the author of Crossing the Chasm. He clearly described how marketing strategies for high-tech are different from other product categories. He heavily leverages the technology adoption life-cycle bell curve where Rogers et. al. segments people into 5 categories:

innovators,
early adopters,
early majority,
late majority and
laggards

(although the last category seems a bit offensive :)). Moore emphasizes that getting from early adopter to early majority is like crossing a chasm: the former 'visionaries' have very different expectations then the later 'pragmatists'. To mix authors (like metaphors), a 'tipping point' seems to be required to make the shift.
So it is for developers: new ideas, languages and techniques come by all the time. Some jump in 'where angels dare to tread'. I seem to be the former. At least I like to think of myself as such. Others wait. Some are clearly risk averse, but I think for some, it is hard to let go of the 'it works, why change it' paradigm. Perhaps they are right. They are pragmatists, and by nature practical. But innovators and early adopters seem to reap benefits. Since the technology wave moves incesntly and swiftly, it is best to keep on its cusp, like a surfer, using its power and momentum to guide you on, lest you be left paddling to catch up, far behind.
But many on my team aren't of the innovator ilk. Nor is my company. I work for a very large software company that should be on the leading edge, if not the bleeding edge of innovation adoption. But we're not. We suffer from a stifling bureaucracy (like most large companies or governments, dare I say), and a hefty dose of 'not built here' syndrome. Interestingly enough, by boss isn't a 'laggard' in any stretch of the imagination. He, however, bears the brunt of having to argue for the wacky ideas of his reports in front of very risk averse corporate gatekeepers. Sometimes he wins, sometimes not.
But, within the team, it was surprising to me how shocked people were when I said,

"we are not going to write JSP any more."

I'm sure some of the readers of this blog post (all 1 of you) might be shocked as well. But sometimes we need to be shocked. This is a broad and sweeping statement, but it is powerful, because it hints at our reliance on rendering the UI on the server. And we shouldn't. This is heresy, and would have been foolish in the past. From early cgi and perl (remember those days) to the development of J2EE, the browser was considered a dumb reader of html, not a smart client platform like thick client apps or client server. Applets were to be that, not the browser. If not Applets, then flash, if not flash then... well, ... the browser.
What is the browser today? Its not dumb. It's not just a reader. It is an operating system. It is a platform that has capabilities to run sophisticated programs delivered to it. HTML5, CSS3 and JavaScript are the languages it speaks. If you know the lingo, you can unleash a vast array of capabilities that just a couple of years before were left to the native or thick client world.
So, my aha moment came when I realized that what we needed to do was to go back to the client server days. In those days, you had vast power of the desktop, its graphical and multimedia power and local storage capability. You connected to the server for data. Yes, business rules and shaping of data occurred on the server. Certainly secure selection and delivery of data as well. It enforces transactionality and validity. It handles persistence and auditing. But its is never in the business of rendering the user interface--that's the client's job.
Rendering UI on the server was the compromise required to deliver applications over the web. And it was worth it too. Not to wory about the client footprint, not to have to wait for support to install and configure the next version. immediate access to everything a mouse click away. It rocked our world. It changed our world. Thanks Tim for that. But he was thinking hyperlinked books after all, not applications. It was amazing what we can do even with its obvious limitations. And Tim has moved on too.

But we no longer need to make this compromise. We can benefit from the zero footprint immediate access to all the worlds knowledge and applications but still leverage graphics, multimedia, processing power and even local storage of the desktop.

Fun with HTML5

2011-07-06T23:26:00.000-07:00

I guess I'm a bit late to the game. However, perhaps not too late. HTML5 offers a host of solutions for the kind of application I want to build: rich client, local storage, animated, etc. I walked through several HTML5 demos and examples over the weekend.

I can deliver a rich client experience for an application needing local only storage with nothing but HTML5, JavaScript and CSS3. But for real 'client server' or mashups with shared information, we still need connectivity to the server (Ajax based, RESTful, transport in JSON).

New Technology Stack

2011-07-03T07:13:00.000-07:00

In my real life, I actually have to deliver software :). So most of my blogs are about the technologies I am using today as well as best practices I am actually practicing (or trying to practice) in my real life.

This blog will focus on the following technology stack for now:

Also I will be looking at:

Some techniques and tools include

Sun NetBeans IDE
SpringSource Tool Suite
Test Driven Development
Continuous Integration
Maven

Back again and focusing on Enterprise 2.0

2011-07-03T06:19:00.000-07:00

Why did I rename this blog Enterprise 2.0 Appplication Tecchnologies?

I am not abandoning ECM and SOA, but I am expanding to incorporate a more generalized concern.

To me, enterprise 2.0 is bringing the promise of web 2.0 to enterprise applications. Not just in providing a better social experience, but providing a better user experience in general, with more user centered and natural user interfaces.

Since Sun quoted "the network is the computer", many (myself included) have been trying to find a way to build enterprise applications that have a rich client experience but are not locked into a heavy installation footprint. Conventional web development has allowed us to build Software as a Service (SaaS), minimizing client and installation requirements and maximizing availability. But on the other hand, these applications are typically designed for the least-common-denominator, heavy on server side processing, have very unnatural user experiences, are constructed with a cacophony of languages, and tend to be a slave to bandwidth and availability of the network.

An ignorant corporate sponsor might ask "Why can't we have the rich user experience of the desktop while leveraging the ubiquity of the web?"

Well, now we can. Through the power of JavaScript and HTML5 the browser can support truly rich client experiences, while still leveraging the advantages of the web and being available anytime, anywhere on any device. Constructing access to information and actions using the power of REST and semantic net, different user experiences can be developed to share and leverage the knowledge of the enterprise in different ways. And still the enterprise applications can leverage well tested legacy services, be secure and achieve the availability and performance requirements demanded by the corporation.

However, I am still concerned with requiring constant connectivity. Most of even the best internet applications that deal with transitional data require continuous high bandwidth connectivity to the services. Especially for the mobile worker (an ever increrasing demographic), being able to work 'off-line' sometimes is essential.

So, my search for the answer to the question "Why can't we have the rich user experience of the desktop while leveraging the ubiquity of the web?" includes the following:

Rich client experience supporting many user types and many devices, including the use of graphics, multimedia and alternate input technologies
Secure access to semantically rich resources and services that are flexible and can be leveraged from many different clients
Connectivity to other legacy systems and services, supporting synchronous and asynchronous models
Mechanisms that allow users to share and collaborate and work off-line as well as on line

We want secure access to corporation's transactional information and services available at any time, from anywhere on any device, while allowing users to organize their own experiences and collaborate with others the way they want to.

The purpose of this blog is to try to address these concerns and others through technology available today, relevant to my own direct work requirements as well as the purely theoretical.

Moving On

2010-02-04T07:52:00.000-08:00

I am shifting my focus in my career from Enterprise Content Management with Service Oriented Architectures to more Service Oriented Architectures and Rich Internet Application development. I will be focusing on the Oracle Fusion Middleware stack, not Alfresco, jBPM and ServiceMix. I will be developing applications using Oracle JDeveloper tools with Oracle's Application Development Framework (ADF).

So, I will continue to use this blog, but I will be shifting articles to talk about these technologies.

Looking at Alfresco Share 3.2 Community - Part 3 - Customizing forms

2009-07-07T08:00:00.001-07:00

This blog will look at how to display custom types and aspects in Share in the edit metadata feature. The previous blog article showed how to associate content with predefined aspects and show them in the edit metadata form.

This example requires Alfresco 3.2 Labs (currently Preview).

Resources:
* Alfresco forms engine wiki page
* Alfresco forms engine examples wiki page

Also see my previous blog entries showing how forms are used in Alfresco Share 3.2

I will use the example project structure offered by Jeff Potts' great article - Extending the Alfresco Content model to extend the content model in Alfresco. For the share customization, I will base my project on the Share extension project example in my blog.

Creating the new Custom content type

For this example, I will create a custom content type and modify the edit metadata form shown in Alfresco Share. The content type I will create will center around a custom type called MarketingContent, with an additional Aspect called Brandable. This custom metadata will add the ability to identify the 'brand' to which the Marketing content should be associated, and will require a custom single-select drop down.

Step 1 - Setup the project to extend Alfresco with custom content

1. Download Jeff Potts' custom content example source
2. Import into Eclipse - assume you already downloaded the Alfresco SDK and imported SDK AlfrescoRemote
3. Fix project references as needed
4. Update build.properties for ant build (alfresco.sdk.remote.home and alfresco.web.root)

Step 2 - Modify project for new custom content model

Four files to modify:
* PROJECT_HOME/src/alfresco/extension/someco-model-content.xml
* PROJECT_HOME/src/alfresco/extension/scModel.xml
* PROJECT_HOME/src/alfresco/extension/web-client-config-custom.xml
* PROJECT_HOME/src/alfresco/extension/webclient.properties

someco-model-content.xml (renamed to 'orbitz-model-content.xml')

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>

<beans>
<!-- Registration of new models -->
<bean id="extension.dictionaryBootstrap" parent="dictionaryModelBootstrap" depends-on="dictionaryBootstrap">
<property name="models">
<list>
   <value>alfresco/extension/orbModel.xml</value>
</list>
</property>
</bean>
</beans>

scModel.xml (renamed to 'orbModel.xml')

<?xml version="1.0" encoding="UTF-8"?>
<!-- Definition of new Model -->
<model name="orb:orbitzmodel" xmlns="http://www.alfresco.org/model/dictionary/1.0">

<!-- Optional meta-data about the model -->
<description>Orbitz Marketing Model</description>
<author>Ed Wentworth</author>
<version>1.0</version>

<!-- Imports are required to allow references to definitions in other models -->
<imports>
  <!-- Import Alfresco Dictionary Definitions -->
  <import uri="http://www.alfresco.org/model/dictionary/1.0" prefix="d" />
  <!-- Import Alfresco Content Domain Model Definitions -->
  <import uri="http://www.alfresco.org/model/content/1.0" prefix="cm" />
</imports>

<!-- Introduction of new namespaces defined by this model -->
<namespaces>
  <namespace uri="http://www.orbitz.com/model/content/1.0" prefix="orb" />
</namespaces>
<constraints>
  <constraint name="orb:brands" type="LIST">
      <parameter name="allowedValues">
          <list>
              <value>Orbitz</value>
              <value>CheapTickets</value>
              <value>eBookers</value>
          </list>
      </parameter>
      <parameter name="caseSensitive"><value>true</value></parameter>
  </constraint>
</constraints>

<types>
  <!-- Enterprise-wide generic document type -->
  <type name="orb:doc">
      <title>Orbitz Document</title>
      <parent>cm:content</parent>
      <mandatory-aspects>
        <aspect>cm:generalclassifiable</aspect>
      </mandatory-aspects>
  </type>

  <type name="orb:marketing_content">
      <title>Orbitz Marketing Content</title>
      <parent>orb:doc</parent>
      <properties>
          <property name="orb:effective_from">
              <type>d:date</type>
          </property>
          <property name="orb:effective_to">
              <type>d:date</type>
          </property>
      </properties>
  </type>
</types>

<aspects>
  <aspect name="orb:brandable">
      <title>Orbitz Brandable</title>
      <properties>
          <property name="orb:brand">
              <type>d:text</type>
              <mandatory>true</mandatory>
              <constraints>
                  <constraint ref="orb:brands"/>
              </constraints>
          </property>          
      </properties>
  </aspect>

</aspects>
</model>

web-client-config-custom.xml

<alfresco-config>

<!--  add webable aspect properties to property sheet -->
<config evaluator="aspect-name" condition="orb:brandable">
  <property-sheet>
      <show-property name="orb:brand" display-label-id="brand" />
  </property-sheet>
</config>

<!-- show related documents association on doc property sheet -->
<config evaluator="node-type" condition="orb:doc">
  <property-sheet>
  </property-sheet>
</config>

<!-- show related documents association on whitepaper property sheet -->
<config evaluator="node-type" condition="orb:marketing_content">
  <property-sheet>
      <show-property name="orb:effective_from" display-label-id="effective_from" />
      <show-property name="orb:effective_to" display-label-id="effective_to" />
  </property-sheet>
</config>

<!--  add orbitz types to add content list -->
<config evaluator="string-compare" condition="Content Wizards">
  <content-types>
      <type name="orb:doc" />
      <type name="orb:marketing_content" />
  </content-types>
</config>

<config evaluator="string-compare" condition="Action Wizards">
  <!-- The list of aspects to show in the add/remove features action -->
  <!-- and the has-aspect condition -->
  <aspects>
      <aspect name="orb:brandable"/>
  </aspects>

  <!-- The list of types shown in the is-subtype condition -->
  <subtypes>
      <type name="orb:doc" />
      <type name="orb:marketing_content" />
  </subtypes>  

  <!-- The list of content and/or folder types shown in the specialise-type action -->
  <specialise-types>
      <type name="orb:doc" />
      <type name="orb:marketing_content" />
  </specialise-types>  
</config>

<config evaluator="string-compare" condition="Advanced Search">
  <advanced-search>
      <content-types>
          <type name="orb:doc" />
          <type name="orb:marketing_content" />
      </content-types>
      <custom-properties>
          <meta-data aspect="orb:brandable" property="orb:brand" display-label-id="brand" />
      </custom-properties>
  </advanced-search>
</config>
</alfresco-config>

webclient.properties

#orb:marketing_content
effective_from=Effective From
effective_to=Effective To

#orb:brandable
brand=Brand

Step 3 - Deploy

Make sure that build.properties is properly configured

Run ant deploy

Step 4 - Test Model
As a prerequisite, you should go to Share client and create a new site (i.e. 'Merchandising')

In Alfresco Explorer client - Upload content as type 'Marketing Content'
Apply 'Brandable' aspect
Modify content propertis -- should look like picture below

In order for this form to render, we need to modify the forms configuration to let Share know how to render our custom type and aspect. For details on this, see the forms wiki and forms examples wiki pages.

Step 5: Configure share to render the orb:market_content type and orb:brandable aspect

Create a file named 'web-framework-config-custom.xml' and deploy it to the share/WEB-INF/classes/alfresco/web-extension directory with the contents:

<alfresco-config>

 <config evaluator="node-type" condition="orb:marketing_content">
    <forms>
       <form>
          <field-visibility>
             <!-- inherited from cm:content -->
             <show id="cm:name" />
             <show id="cm:title" force="true" />
             <show id="cm:description" force="true" />
             <show id="mimetype" />
             <show id="cm:author" force="true" />
             <show id="size" for-mode="view" />
             <show id="cm:creator" for-mode="view" />
             <show id="cm:created" for-mode="view" />
             <show id="cm:modifier" for-mode="view" />
             <show id="cm:modified" for-mode="view" />
           
             <!--  specific for orb:marketing_content -->
             <show id="orb:effective_from" />
             <show id="orb:effective_to" />

             <!--  aspect orb:brandable -->             
             <show id="orb:brand" />
           
          </field-visibility>
          <appearance>
             <field id="orb:effective_from" label="Effective From"/>
             <field id="orb:effective_to" label="Effective To"/>
             <field id="orb:brand" label="Brand">
                <control template="controls/selectone.ftl">
                   <control-param name="options">Orbitz,CheapTickets,eBookers</control-param>
                </control>
             </field>
          </appearance>
       </form>
    </forms>
 </config>
</alfresco-config>

As we see here, we needed to copy all of the default properties from cm:content as well as add our unique properties for orb:marketing_content, and add the orb:brands aspect. This gives us very fine-grained control, but we can see there could be a lot of repeated configurations if we use types with aspects in complex ways.

Step 5: Run the example

Now we can go ahead and restart share and log in and select 'edit metadata' of our content previously checked in with the type orb:marketing_content and set with the orb:brandable aspect.

Now we should see the following:

We customized the selectone.ftl control template to provide our list of brands. One can consider an extension to this control would be to look up this list from a data web-script.

We should create our own selectone lookup from an external source in an ajax way. We will do so in a further blog article.

Looking at Alfresco Share 3.2 Community - Part 2 - Edit Custom Metadata

2009-06-30T10:46:00.001-07:00

This series of blog entries is intended to walk through the new features of Alfresco Share 3.2 Labs. In the previous blog entry, I built the community version from source, and looked at the new Admin Console feature. This blog, I will look at how Share exposes Custom metadata, and allows users to assign aspects to uploaded content.

Viewing and Editing Custom Metadata

I have Alfresco 3.2 Labs running on my Windows XP Laptop, built from source updated June 23, 2009, and I have deployed both Alfrsco.war and share.war to an instance of Tomcat 6.

In previous versions of Share, it wasn't possible to view or edit custom metadata. Share 3.2 Labs addresses this deficit. Further, it leverages Surf's new forms architecture to render the metadata form dynamically. We will look at this in detail later. First, I will walk through the user interface for metadata.

In order to show Share's ability to view custom metadata, we need to create a new Site and Upload some content. Here are the steps briefly:

Log into Share (as admin/admin) --> The User Dashboard renders with the 'My Sites' dashlet.
Click on 'Create Site' in the My Sites dashlet (or select 'create site' from the 'Sites' drop down in the top menu) --> The Create Site popup will render.
Enter the Name, URL name, and Description (optional) of this new site. (In my example I created a site with Name=Merchandising, URL name=Merchandising).
Press 'Ok' when complete and the new site will be created, returning you to the user dashboard.
Select the new site from the 'My Sites' dashlet, or the top menu's Sites dropdown --> the Site dashboard will render.
Navigate to the 'Document Library' page to upload new content --> the Document Library page renders.
Click on 'Upload' button to upload some content to the default documents folder.

Now that we have content, we should be able to view the metadata.

Here I am looking at Document Library in the merchandising site, where have uploaded an XML file and a couple of image files...

Hovering over one of the files in the list renders the actions that can be performed on that file.
Actions include:

Download
Edit Metadata
Upload new Version
More > (we will look at some of these later)

This list of actions is very configurable. We may show how to do this in a later blog.
The 'Edit Metadata' action is what we want. Select the 'Edit Metadata' action for the uploaded document.

Here I selected edit metadata for an XML ddocument named 'Article.EnableCookies.xml'...

This looks pretty normal. It is the same popup as with previous version of Share allowing edit of basic metadata properties like Name, Title, Description and tags. But notice in the Upper right corner 'Full metadata Edit page...'. Selecting this will render a full screen rendering all of the document's metadata.

Here I am showing the full metadata page of the xml file I uploaded...

In this example, two new fields are rendered: the Mimetype, and the Author.

This full page renders the metadata form in 'Edit' mode using the new forms engine. The form is rendered by obtaining a form configuration from the remote alfresco repository. This form configuration is dynamically generated from the available metadata on the content item being viewed. The form archtiecture is capable of rendering the following types of controls (see more detail in the forms service wiki:

mimetype -- <select> <option> from a list of mime types (i.e. application/pdf, ...)
size -- display file size
textarea -- <textarea> field configurable to r rows and c columns
slectone -- <select> field with <option> tags dynamically rendered
textfiled -- <input type="text"> field
category -- picker selecting one or more categories to associate with the content
endocding -- <select> field to choose <option> from list of encoding types (i.e. UTF-8, ISO-8859-1, ...)
association -- picker selecting one or more other content items to associate this content item too
checkbox -- <input type="checkbox"> field
readonly -- <input type="text"> rendered as read only
date -- renders a date picker setting value to an <input type="text"> field
period -- selecting x days, weeks, etc.

Associating Aspects

To really show the custom metadata feature, we will look at another great feature added to Share 3.2, the ability to associate new aspects to documents. When we associate a new aspect, new properties can be added to the document and the edit metadata full form should reflect those changes. To do this, let us add the 'dublin core' aspect to the document we just looked at.

Hover over the document --> the actions should render
Select the 'more' option --> the more options should render
Select the 'manage aspects' option --> the manage aspects popup will render
Select the '+' by the 'Dublin Core' aspect in the 'Available to Add' list --> The 'Dublin core' should be removed from the 'Available to Add' and added to the 'Currently Selected' list
Select the 'Apply changes' button to save the changes

Now we can look at the edit metadata again and see the new metadata properties added via the Dublin Core aspect

Here we see the edit metadata full page with the dublin core properties

The next blog entry will look at customizing share to display our own content types and aspects.

Looking at Alfresco Share 3.2 Community

2009-06-26T06:35:00.000-07:00

Building Alfresco Labs 3.2 from Community

This blog and others to follow will walk through the new features of Alfresco Share 3.2 Labs. First, I will walk through some of the key features. Then I will open up the box and look in side at a few choice features. Finally, I will show examples of the extensibility of this new version of Share.

Building from source was fairly straight forward. I use Tortoise SVN as my svn client (on my Windows XP laptop). I 'updated' to the latest code (as of 23 June 09). I used ant to build, with my environment setup as recommended in the Alfresco SVN Development environment wiki.

When attempting to deploy to tomcat using 'ant build-tomcat' and 'ant incremental-tomcat', the ant task complained that I needed to use tomcat 6. I downloaded Apache tomcat 6.0.20. I noticed that tomcat 6 doesn't create a 'shared' folder by default, which is used by alfresco for extension. But I found a wiki page for configuring tomcat 6 that explains how to configure tomcat 6 for this purpose.

Because I have multiple versions of alfresco on this machine, I didn't want to sacrifice the default db (mysql database named alfresco). I had problems with configuring other db vendor, however. I followed the configuring db wiki page for 3.2 and tried boty Derby and HSQL as alternatives. However, various problems occurred. HSQL and Derby didn't seem to have corrected hibernate mappings and/or sql build scripts. So I chose to create another db instance on mysql named alfresco2. I'm sure with a little more patience, I would have succeeded. But I'm impatient.

In order to configure to this new db (and as described on the database configuration wiki page), I found that there is now a file 'alfresco-global.properties' that you can copy from your TOMCAT_HOME/webapps/alfresco/WEB-INF/classes directory (named 'alfresco-global.properties.sample') to TOMCAT_HOME/shared/classes directory, renamed to 'alfresc-global.properties'. I noted that this did NOT go into an 'alfresco/extensions' subdirectory as in the past with 'custom-repository.properties'.

Starting up tomcat on my windows xp with the default configurations caused a problem with out of heap space and, later PermGen. I changed the startup parameters to add more heap and PermGen (-Xms256M -Xmx512M -XX:MaxPermSize=256m) and finally I was in business.

First Impressions of Share 3.2

After logging in to share (i.e. http://localhost:8080/share) with the default user account admin/admin, the admin user dashboard is rendered first. Nothing new here. However in the header, right justified I saw a 'Admin Console' button. Clicking it, I see you can now create new users and groups from Share directly!

Here I logged in as admin/admin...

Admin Console

It seems there is a new role for Share users, that of 'Manager'. This role is described in the forums. The 'Manager' role has permisions to expose the new 'admin console.'

The Admin Console is accesssed by clicking the 'Admin Console' button on the top menu. This console is configured with an extensible list of console 'tools'. The console opens up showing the first tool: Groups.

Groups Tool

Here, I clicked on the 'Admin Console' button...

The 'Groups' tool allows a user to drill down through the hierarchy of groups, and create new groups, edit them and remove them. To represent the hierarchy, the user interface represents levels of groups by showing child groups in a new list panel created to the right of the group list panel with the selected group. The successive levels of group lists all have similar functionality (recursively rendered) to add, edit and remove groups and their children. This UI approach is a bit odd, but effective.

Clicking 'new group' opens the 'Create Group' form, prompting the user to enter the required fields for: Identifier and Display name. Once entered, the buttons 'Create Group', 'Create and Create Another' are enabled. The 'Create Group' creates a group with the given Identifier and Display name, and returns back to the 'Groups' tool main page. The 'Create and Create Another' creates a group as the 'Create Group' button but clears the form to enter another group. The labels of these buttons might be a bit confusing at first.

Here I clicked the 'New group' button ...

I tried creating a new group and the group called 'testg', but it wasn't added to the list immediately. Reopening the admin console later, I saw the group I created listed correctly (see https://issues.alfresco.com/jira/browse/ALFCOM-3110).

In the Groups tool of the Admin Console, hovering over an item indicates other actions that can be performed on that item, including 'edit' and 'delete'.

Users tool

The users tool of the 'Admin Console' allows the manager to create new users and edit users. The search box requires at least one character entered before search works. (Perhaps adding a note on this screen or disabling/enabling the 'search' button might help.) This search text seems to be a partial match to find anything with the text entered 'in' the user's name.

Here I typed 'a' and pressed 'Search'...

A new user can be created from the users tool main page by clicking the 'New User' button upper right, or an existing user details can be viewed, and later edited, by clicking on the user name in the list.

Here I clicked on the 'Jane Smith' name in the users list...

From the user profile view page there are two buttons: Edit User and Delete User. From the Edit User page, you can enter basic information, assign the user to groups, set a quota, change passwords and select photos.

Next blog entry -- look at edit metadata feature.

Alfresco Regional Meetup

2009-05-12T14:32:00.000-07:00

On Wednesday April 29, 2009, The Chicago area hosted a regional alfresco meetup where I was in attendance. There were a few Alfrewsco speakers and a few community speakers. Among the speakers were Jeff Potts talking about Drupal integration, and Michael Uzquiano talking about WCM roadmap and Share. Also, Yong Qu presented a bit on integration to email clients.

I also presented some of our work on Alfresco Share developing a custom contribution client for our marketing content. For those interested, my PowerPoint presentation is located here.

Working with jBPM workflows in Alfresco - Part 3 : Alfresco scripts

2009-04-07T18:47:00.001-07:00

In the previous blog entry: Working with jBPM Workflows in Alfresco - Part 1 : jBPM, we saw how to create a simple jBPM workflow and test it.

In a blog entry before that: Working with jBPM Workflows in Alfresco - Part 2 : Embedded Alf - SDK, we saw how to run our workflow in Alfresco Embedded using the SDK.

In this blog entry, we will add some Alfresco scripts into our workflow that make use of Alfresco APIs.

Step 1 - Logging in JavaScript via Alfresco logger

Starting simple, lets modify our process definition to print out a log message every time we transition to a new state. This is a handy technique if we're not sure our logic is going the way we think it should. Here is the updated processs definiton:

<?xml version="1.0" encoding="UTF-8"?>

<process-definition  xmlns="urn:jbpm.org:jpdl-3.2"  name="publishContentBasic">
  <start-state name="start">
      <transition name="to_requested" to="requested">
          <action class="org.alfresco.repo.workflow.jbpm.AlfrescoJavaScript">
              <script>
                  logger.log("Going to requested state");
              </script>
          </action>
      </transition>
  </start-state>

  <state name="requested">
      <transition to="processing" name="to_processing">
          <action class="org.alfresco.repo.workflow.jbpm.AlfrescoJavaScript">
              <script>
                  logger.log("Going to processing state");
              </script>
          </action>
      </transition>
  </state>

  <state name="processing">
      <transition to="succeeded" name="to_succeeded">
          <action class="org.alfresco.repo.workflow.jbpm.AlfrescoJavaScript">
              <script>
                  logger.log("Going to succeeded state");
              </script>
          </action>
      </transition>
      <transition to="failed" name="to_failed">
          <action class="org.alfresco.repo.workflow.jbpm.AlfrescoJavaScript">
              <script>
                  logger.log("Going to failed state");
              </script>
          </action>
      </transition>
  </state>

  <state name="succeeded">
      <transition to="end" name="to_end">
          <action class="org.alfresco.repo.workflow.jbpm.AlfrescoJavaScript">
              <script>
                  logger.log("Going to end state");
              </script>
          </action>
      </transition>
  </state>

  <state name="failed">
      <transition to="end" name="to_end">
          <action class="org.alfresco.repo.workflow.jbpm.AlfrescoJavaScript">
              <script>
                  logger.log("Finishing");
              </script>
          </action>
      </transition>
  </state>

  <end-state name="end"></end-state>
</process-definition>

Here we see the new process containing an action element in the transition element calling out the org.alfresco.repo.workflow.jbpm.AlfrescoJavaScript class. This class provides a java script environment with the Alfresco JavaScript API default objects instantiated and ready to use. One of which is the logger.
This action wraps a <script> element containing the javascript to run.

To view the results, first change the log4j.properties config to show the javascipt log messages (and reduce some of the noise).

# Set root logger level to DEBUG and its only appender to CONSOLE.
log4j.rootLogger=WARN, CONSOLE

# CONSOLE
log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=%d{HH:mm:ss,SSS} [%t] %-5p %C{1} : %m%n

# LIMIT CATEGORIES
log4j.logger.org.jbpm=INFO
#log4j.logger.org.jbpm.graph=DEBUG
log4j.logger.com.sample=DEBUG
# Hibernate debugging levels and their output
log4j.logger.org.hibernate=WARN
#Log all SQL DML statements as they are executed
#log4j.logger.org.hibernate.SQL=TRACE
#Log all JDBC parameters
#log4j.logger.org.hibernate.type=TRACE
#Log all SQL DDL statements as they are executed
#log4j.logger.org.hibernate.tool.hbm2ddl=DEBUG  
#Log the state of all entities (max 20 entities) associated with the session at flush time
#log4j.logger.org.hibernate.pretty=DEBUG  
#Log all second-level cache activity
#log4j.logger.org.hibernate.cache=DEBUG  
#Log transaction related activity
#log4j.logger.org.hibernate.transaction=DEBUG  
#Log all JDBC resource acquisition
#log4j.logger.org.hibernate.jdbc=TRACE  
#Log HQL and SQL ASTs and other information about query parsing
#log4j.logger.org.hibernate.hql.ast=DEBUG  
#Log all JAAS authorization requests
#log4j.logger.org.hibernate.secure=DEBUG  
#Log everything (a lot of information, but very useful for troubleshooting)
#log4j.logger.org.hibernate=DEBUG  
#log4j.logger.org.hibernate.tools=DEBUG  

log4j.logger.org.alfresco=INFO

log4j.logger.org.alfresco.repo.jscript=DEBUG

The last line: log4j.logger.org.alfresco.repo.jscript=DEBUG does the trick. Now run the PublishContentBasicProcessAlfTest as a JUnit test and see the results. You should get something like the following in the log:

20:42:22,574 [main] DEBUG ScriptResourceHelper : Imports resolved, adding resource '_root
20:42:22,761 [main] DEBUG ScriptLogger : Going to requested state
20:42:22,765 [main] DEBUG RhinoScriptProcessor : Time to execute script: 189ms
20:42:22,893 [main] DEBUG ScriptResourceHelper : Imports resolved, adding resource '_root
20:42:22,899 [main] DEBUG ScriptLogger : Going to processing state
20:42:22,901 [main] DEBUG RhinoScriptProcessor : Time to execute script: 6ms
20:42:22,936 [main] DEBUG ScriptResourceHelper : Imports resolved, adding resource '_root
20:42:22,942 [main] DEBUG ScriptLogger : Going to succeeded state
20:42:22,943 [main] DEBUG RhinoScriptProcessor : Time to execute script: 5ms
20:42:23,004 [main] DEBUG ScriptResourceHelper : Imports resolved, adding resource '_root
20:42:23,010 [main] DEBUG ScriptLogger : Going to end state
20:42:23,011 [main] DEBUG RhinoScriptProcessor : Time to execute script: 5ms

Lets do something more interesting. Supposing we wanted to create and/or update some content. The Alfresco JavaScipt API cookbook has an interesting example which I will steal for this purpose. Add the following javascript to the script element of the 'to_requested' transition:

<script>
    logger.log("Going to requested state");
    logger.log("trying to create file and make it versionable");
    
    var doc = userhome.createFile("checkmeout.txt");
    doc.addAspect("cm:versionable");
    doc.content = "original text";
    logger.log("created versionable doc with content '"+doc.content+"'");

    var workingCopy = doc.checkout();
    workingCopy.content = "updated text 1";

    doc = workingCopy.checkin();

    workingCopy = doc.checkout();
    workingCopy.content = "updated text 2";

    doc = workingCopy.checkin("a history note", true);
    logger.log("checked doc out and in a couple of times");
</script>

In this example, we create a new item of content with some text and make it versionable. Then we check it out and updated it. And again checkout and update it, and on check in we use a comment.

Note: be careful as to what syntax you use in the script element. Since this appears in XML, we must escape any characters that can cause this script body to parse incorrectly (such as < and > characters). I had to remove the // comment lines to make this work correctly.

Step 2 - Running a Java class with Alfresco

Now we will configure to run alfresco java foundation API services.

END

Working with jBPM workflows in Alfresco - Part 2: Embedded Alf - SDK

2009-04-07T09:32:00.001-07:00

This part focuses on extending the previous blog post: Working with Workflows in Alfresco - Part 1: jBPM to run as an Embedded Alf SDK project, and to configure and use Alfresco scripts as actions in the workflows.

Step 1 - Install SDK
Make sure you install the SDK according to the documentation on the Alfresco Wiki
Import the SDK projects into the same workspace you are using for this tutorial

Step 2 - Configure Project to Run with Embedded Alfresco

Go to project properties > Java buid path > Projects tab and select 'add' to add SDK AlfrescoEmbedded
From the SDK FirstFoundationClient, copy alfresco.extensions package from the 'source' source folder and paste into the 'src/main/config' source directory of your project (i.e. 'orchestration-example'). This will include the files 'custom-alfresco-shared.xml', 'custom-repository-context.xml' and 'custom-repository.properties'
From the SDK FirstFoundationClient, copy the org.alfresco.sample package and paste into the src/main/java source folder of your project. This will give us something to test running as Alfresco Embedded
Update the 'custom-repository.properties' to point dir.root to your Alfresco installation
Remove the JBPM library from project properties, as it will conflict with the Alfresco version of these dependencies
I recommend that you modify the log4j.properties to set the root logger to INFO, CONSOLE not DEBUG, CONSOLE or you will be watching the log messages for half the day

Step 3 - Test it out
Run the FirstFoundationClient as Java Application. There should be no 'red ink' and the line near the end of the log messages should read something like 'Alfresco started (Labs): Current version 3.0.0 (Stable 1526) schema 1002 - Installed version 3.1.0 (142) schema 1008'
If you see this line, likely you were able to run using Alfresco Embedded SDK

Step 4 - Create an Embedded Alf test
To test within the Alfresco context using Embedded approach, your workflow must be deployed, and you must run your test code, like the FirstFoundationClient example within a transaction service callback.
We will create a base test class, extending TestCase of JUnit 3 to simplify writing tests like this.

package com.sample;

import junit.framework.TestCase;

import org.alfresco.repo.transaction.RetryingTransactionHelper.RetryingTransactionCallback;
import org.alfresco.service.ServiceRegistry;
import org.alfresco.service.transaction.TransactionService;
import org.alfresco.util.ApplicationContextHelper;
import org.apache.log4j.Logger;
import org.springframework.context.ApplicationContext;

public abstract class EmbeddedAlfTestBase extends TestCase {

Logger logger = Logger.getLogger(EmbeddedAlfTestBase.class);
protected ServiceRegistry serviceRegistry;
protected TransactionService transactionService;
protected ApplicationContext ctx;

public void setUp() throws Exception {
ctx = ApplicationContextHelper.getApplicationContext();
serviceRegistry = (ServiceRegistry) ctx.getBean(ServiceRegistry.SERVICE_REGISTRY);
transactionService = serviceRegistry.getTransactionService();
}

public void tearDown() throws Exception {
}

public void runTestInEmbeddedAlf(RetryingTransactionCallback<Object> testWork) throws Exception {
transactionService.getRetryingTransactionHelper().doInTransaction(testWork);
}
}

This code gets the application context and gets some services from Spring, including the serviceRegistry and the transactionService. The helper method, runtestInEmbeddedAlf takes a class of type RetryingtransactionCallback and runs it it using the transactionService's RetryingTransactionHelper doInTransaction(callback) method.

We will subclass this base test class and write our process test.

Create a class PublishContentBasicProcessAlfTest, copying from PublishContentBasicProcessTest created in the previous blog entry.
Change it to extend from EmbeddedAlfTestBase class
Rename testSimpleProcess to a signature 'public void doTestSimpleProcess(ServiceRegistry serviceRegistry) throws Exception'
Create a new testSimpleProcess like the following:

    public void testSimpleProcess() throws Exception {
RetryingTransactionCallback<Object> publishContentWFExistsCB = new RetryingTransactionCallback<Object>() {
 public Object execute() throws Exception {
     doTestSimpleProcess(serviceRegistry);
     return null;
 }
};
this.runTestInEmbeddedAlf(publishContentWFExistsCB);
}

Now run 'PublishContentBasicProcessAlfTest' as a JUnit test.
This should run as an alfresco project properly. But we are not leveraging Alfresco's services yet.

Step 5 - Test in Alf Using Workflow Service (foundation services)

What we are going to do:

Authenticate and deploy in setUp for test
Start workflow using workflow service
Signal workflow using workflow service

Create a class PublishContentBasicProcessAlfTest extends EmbeddedAlfTestBase
To start, we will create a setUp() method to set us up for testing, like authenticating and deploying the service

    private WorkflowService workflowService;

public void setUp() throws Exception {
super.setUp();
workflowService = serviceRegistry.getWorkflowService();

authenticate("admin","admin");

deployDefinition(PROCESS_DEF_FILE);
}

We get the workflow service from the service registry (obtained in the setUp of the EmbeddedAlfTestBase class). Then we authenticate, and then deploy our process definition 'publichContentBasic/processdefinition.xml'.
Lets look at the methods we need to create:

authenticate method

    private void authenticate(String user, String password) {
  AuthenticationService authenticationService = serviceRegistry.getAuthenticationService();
  authenticationService.authenticate(user, password.toCharArray());

}

We get the AuthenticationService, and call authenticate. We need to do this first or else we wont be able to deploy our workflow.

deployDefinition method

    private WorkflowDeployment deployDefinition(String processDefName) {
   //Deploy definition
   String engineId = ENGINE_ID;
   InputStream workflowDefinition = getClass().getResourceAsStream("/"+processDefName);
   String mimeType = XML_MIMETYPE;
   return workflowService.deployDefinition(engineId, workflowDefinition, mimeType);
}

We use the deployDefinition method of the workflow service. THis requires us to pass an engineId. this Id for jbpm is 'jbpm'. The mime type is 'text/xml'. The stream is obtained as a resource from this class loader by reading the 'publishContentBasic/processdefinition.xml' file.

Now we start the test like we did before, using the transactionservice and its callback:

    public void testSimpleProcess() throws Exception {
    RetryingTransactionCallback<Object> publishContentWFExistsCB = new RetryingTransactionCallback<Object>() {
        public Object execute() throws Exception {
            doTestSimpleProcessInAlf();
            return null;
        }
    };
    this.runTestInEmbeddedAlf(publishContentWFExistsCB);

}

public void doTestSimpleProcessInAlf() throws Exception {

}

Ok. Now that we've got the test method ready. Lets put something in it. The first thing we have to do is start our workflow:

    public void doTestSimpleProcessInAlf() throws Exception {


    NodeRef content = null;
    String wfAssigneeName = "admin";
    String workflowName = ENGINE_ID+"$"+PROCESS_DEF_NAME;

    WorkflowPath wfPath = startWorkflow(content, wfAssigneeName, workflowName);
    assertNotNull(wfPath);

    assertEquals(
            "Instance is in start state",
            wfPath.node.name,
            "start");

This calls the startWorkflow helper method with the content to go in the workflow package (currently null for testing purposes). We also need a name to assign the workflow to. We use 'admin'. And, finally we need the workflow name to start. Alfresco uses a naming convention prepending the engine id and a '$' to the beginning of BPM engine objects. The value for jbpm is 'jbpm'.

startWorkflow method

    private WorkflowPath startWorkflow(NodeRef content, String wfAssigneeName, String workflowName) throws Exception {
     //Start workflow
     NodeRef wfPackage = workflowService.createPackage(content );
  
     PersonService personService = serviceRegistry.getPersonService();
     NodeRef assigneeNodeRef = personService.getPerson(wfAssigneeName );

     Map<QName, Serializable> workflowProps = new HashMap<QName, Serializable>(16);
     workflowProps.put(WorkflowModel.ASSOC_PACKAGE, wfPackage);
     workflowProps.put(WorkflowModel.ASSOC_ASSIGNEE, assigneeNodeRef);

     // get the moderated workflow

     WorkflowDefinition wfDefinition = workflowService.getDefinitionByName(workflowName );
     if (wfDefinition == null) {
         // handle workflow definition does not exist
         throw new Exception("noworkflow: " + workflowName);
     }

     // start the workflow
     WorkflowPath wfPath = workflowService.startWorkflow(wfDefinition.getId(), workflowProps);
     return wfPath;
 }

In this code, we create the package for the workflow that should contain the content we are workflowing. This is a content manager after all :). Next we get the user we will assign this workflow too. Since this process has no 'tasks', nothing will be noticable to the user. For this kind of process orchestration, the 'admin' user will do nicely. Perhaps in a real system, we want to create a special user just for back office processing like this?

Next we get the definition from the service using the given name 'jbpm$publishContentBasic'. Finally, we use the service to start the workflow, passing the definition and the workflow package. The startWorkflow service returns a WorkflowPath object. This corresponds to the workflow token of the execution of the workflow.

We can test this now to make sure we can deploy and start our workflow.

Next, we will signal the workflow to transition to the next state. This code snippet should be added to the end of the doTestSimpleProcessInAlf method

        // Move the process instance from its start state to the first state.
      wfPath = signalTransition(wfPath, null);
      assertEquals(
              "Instance is in reqested state",
              wfPath.node.name,
              "requested");

Here we call the 'signalTransition' helper method passing the current path (token) and a transition name to take. Our helper method takes the first transition from the current state if no transition name is supplied.
signalTransition method

    private WorkflowPath signalTransition(WorkflowPath wfPath, String transitionName) throws Exception {
     String wfPathId = wfPath.id;
     WorkflowTransition[] wfTransitions = wfPath.node.transitions;
     String wfTransitionId = null;
     if (transitionName == null || transitionName.trim().length()==0) {
         WorkflowTransition wfTransition = wfTransitions[0];
         wfTransitionId = wfTransition.id;
     } else {
         int i = 0;
         for (i = 0; i<wfTransitions.length; i++) {
             if (wfTransitions[i].title.equals(transitionName)) break;
         }
         if (i > wfTransitions.length) throw new Exception("Failed to find transition with nanme '"+transitionName+"'");
         WorkflowTransition wfTransition = wfTransitions[i];
         wfTransitionId = wfTransition.id;
     }
    
     wfPath = workflowService.signal(wfPathId, wfTransitionId);
     return wfPath;
 }

Ok. This pattern can be repeated to transition to the next states to complete our test

        //move to processing state
        wfPath = signalTransition(wfPath, null);
        assertEquals(
                "Instance is in processing state",
                "processing",
                wfPath.node.name);

        //move to succeeded state
        wfPath = signalTransition(wfPath, "to_succeeded");
        assertEquals(
                "Instance is in processing state", 
                "succeeded", 
                wfPath.node.name);

        // Move the process instance to the end state. The configured action 
        // should execute again. The message variable contains a new value.
        wfPath = signalTransition(wfPath, null);
        assertEquals(
                "Instance is in end state", 
                "end", 
                wfPath.node.name);
    }

This completes the code to use the workflow service foundation client approach to deploy, start and signal our workflow.

Here is the complete code of the PublishContentBasicAlfTest

package com.sample;

import java.io.InputStream;
import java.io.Serializable;
import java.util.HashMap;
import java.util.Map;

import org.alfresco.repo.transaction.RetryingTransactionHelper.RetryingTransactionCallback;
import org.alfresco.repo.workflow.WorkflowModel;
import org.alfresco.service.cmr.repository.NodeRef;
import org.alfresco.service.cmr.security.AuthenticationService;
import org.alfresco.service.cmr.security.PersonService;
import org.alfresco.service.cmr.workflow.WorkflowDefinition;
import org.alfresco.service.cmr.workflow.WorkflowDeployment;
import org.alfresco.service.cmr.workflow.WorkflowPath;
import org.alfresco.service.cmr.workflow.WorkflowService;
import org.alfresco.service.cmr.workflow.WorkflowTransition;
import org.alfresco.service.namespace.QName;

public class PublishContentBasicProcessAlfTest extends EmbeddedAlfTestBase {

    private static final String XML_MIMETYPE = "text/xml";
    private static final String PROCESS_DEF_FILE = "publishContentBasic/processdefinition.xml";
    private static final String PROCESS_DEF_NAME = "publishContentBasic";
    private static final String ENGINE_ID = "jbpm";

    private WorkflowService workflowService;

    public void setUp() throws Exception {
        super.setUp();
        workflowService = serviceRegistry.getWorkflowService();        

        authenticate("admin","admin");
        
        deployDefinition(PROCESS_DEF_FILE);
    }
    
    public void tearDown() throws Exception {
        super.tearDown();
    }
    
    public void testSimpleProcess() throws Exception {
        RetryingTransactionCallback<Object> publishContentWFExistsCB = new RetryingTransactionCallback<Object>() {
            public Object execute() throws Exception {
                doTestSimpleProcessInAlf();
                return null;
            }
        };
        this.runTestInEmbeddedAlf(publishContentWFExistsCB);
        
    }

    public void doTestSimpleProcessInAlf() throws Exception {
        
        
        NodeRef content = null;
        String wfAssigneeName = "admin";
        String workflowName = ENGINE_ID+"$"+PROCESS_DEF_NAME;
        
        WorkflowPath wfPath = startWorkflow(content, wfAssigneeName, workflowName);
        assertNotNull(wfPath);

        assertEquals(
                "Instance is in start state", 
                wfPath.node.name, 
                "start");

        // Move the process instance from its start state to the first state.
        wfPath = signalTransition(wfPath, null);
        assertEquals(
                "Instance is in reqested state", 
                wfPath.node.name, 
                "requested");

        //move to processing state
        wfPath = signalTransition(wfPath, null);
        assertEquals(
                "Instance is in processing state",
                "processing",
                wfPath.node.name);

        //move to succeeded state
        wfPath = signalTransition(wfPath, "to_succeeded");
        assertEquals(
                "Instance is in processing state", 
                "succeeded", 
                wfPath.node.name);

        // Move the process instance to the end state. The configured action 
        // should execute again. The message variable contains a new value.
        wfPath = signalTransition(wfPath, null);
        assertEquals(
                "Instance is in end state", 
                "end", 
                wfPath.node.name);
    }

    private WorkflowPath startWorkflow(NodeRef content, String wfAssigneeName, String workflowName) throws Exception {
        //Start workflow
        NodeRef wfPackage = workflowService.createPackage(content );
        
        PersonService personService = serviceRegistry.getPersonService();
        NodeRef assigneeNodeRef = personService.getPerson(wfAssigneeName );
    
        Map<QName, Serializable> workflowProps = new HashMap<QName, Serializable>(16);
        workflowProps.put(WorkflowModel.ASSOC_PACKAGE, wfPackage);
        workflowProps.put(WorkflowModel.ASSOC_ASSIGNEE, assigneeNodeRef);
    
        // get the moderated workflow
    
        WorkflowDefinition wfDefinition = workflowService.getDefinitionByName(workflowName );
        if (wfDefinition == null) {
            // handle workflow definition does not exist
            throw new Exception("noworkflow: " + workflowName);
        }
    
        // start the workflow
        WorkflowPath wfPath = workflowService.startWorkflow(wfDefinition.getId(), workflowProps);
        return wfPath;
    }

    private WorkflowDeployment deployDefinition(String processDefName) {
        //Deploy definition
        String engineId = ENGINE_ID;
        InputStream workflowDefinition = getClass().getResourceAsStream("/"+processDefName);
        String mimeType = XML_MIMETYPE;
        return workflowService.deployDefinition(engineId, workflowDefinition, mimeType);
    }

    private WorkflowPath signalTransition(WorkflowPath wfPath, String transitionName) throws Exception {
      String wfPathId = wfPath.id;
      WorkflowTransition[] wfTransitions = wfPath.node.transitions;
      String wfTransitionId = null;
      if (transitionName == null || transitionName.trim().length()==0) {
          WorkflowTransition wfTransition = wfTransitions[0];
          wfTransitionId = wfTransition.id;
      } else {
          int i = 0;
          for (i = 0; i<wfTransitions.length; i++) {
              if (wfTransitions[i].title.equals(transitionName)) break;
          }
          if (i > wfTransitions.length) throw new Exception("Failed to find transition with nanme '"+transitionName+"'");
          WorkflowTransition wfTransition = wfTransitions[i];
          wfTransitionId = wfTransition.id;
      }
      
      wfPath = workflowService.signal(wfPathId, wfTransitionId);
      return wfPath;
  }

    private boolean authenticate(String user, String password) {
        AuthenticationService authenticationService = serviceRegistry.getAuthenticationService();
        authenticationService.authenticate(user, password.toCharArray());
        return authenticationService.authenticationExists(user);
    }
}

In the next blog post, we will use alfresco scripts in the workflow definition we have just created. And finally, for orchestration, we will interact with JMS.

Working with jBPM workflows in Alfresco - Part 1: jBPM

2009-04-07T07:24:00.000-07:00

The following set of blog articles will track my usage of jBPM in Alfresco to help orchestrate external content processing for publishing, and integrate with Review and Approval Advanced workflows.

My starting point is Jeff Potts articles and blogs on advanced workflows. Also read his book!
Also, read the Alfresco wiki documentation on workflows
jBoss jBPM documentation

Step 1 - Design
In order to collaborate with external publishing processes, we have chosen to use JMS topics. This approach offers robustness and flexibility in communication. The workflow described here will be an 'orchestration' workflow. Its responsibility is to call out external processes and monitor progress. This workflow will be associated to content, however, the content will be in the form of a 'work order' that is created when a user requests to publish a set of content. The user may view the workflow on this work order to see the progress of the external processes orchestrated by the workflow. Later on, we will integrate with the publish review and approve workflow where user tasks will be created to coordinate user activity.

Alfresco will be the container for the orchestration workflows. Actions in the workflow will be responsible for creating and sending messages to JMS topics to choreograph external publishing processes. A simulator will be used to act as the publisher processes for testing purposes. ActiveMQ is used as the JMS provider in these examples. There will also be a message handler created with the responsibi8lity of subscribing to topics that the publisher processes use to provide feedback and communicate status to the workflow. The following diagram represents this intended configuration.

Component descriptions:

Alfresco - contains jbpm implementation and content being workflowed
jBPM - library for jBPM accessed via the workflowService
process definition - jBPM process defining the process steps to orchestrate the publishing process
content event producer action - BPM action invoked from process to publish a content event message to the content topic
content event message - jms message indicating which content to publish and where to publish too
content event topic - jms topic storing the content event messages to be processed by the publisher
content event consumer - consumes content event messages and calls publishing services to invoke the publishing processes
publish process - implements the publishing functionality and calls publisher event producer to
publish event producer - creates and publishes publish event messages to the publish event topic indicating status of publishing
publish event consumer handler - consumes publish event messages and signals corresponding transitions on the publish process definition via the jbpm library

Step 2 - Environment Setup

Install Alfresco SDK: follow instructions on the alfresco wiki
Install ActiveMQ: follow the instructions on the ActiveMQ site
Install jBPM (3.2.x): follow the instructions on the JBoss jBPM site: I installed jbpm-3.2.2 for best compatibility with Alfresco
Install jBPM Process Designer

Note: compatibility problems. As of Alfresco 3.1, the jBPM 3.2.2 is supported. The only issue I had with this version is that there are no hibernate tasks for the Mail Node.

Step 3 - Create the Eclipse Project
For this project, I created a project called 'orchestration -example' using the jboss - jbpm process project' wizard.

Step 4 - Create the process
The following image shows the workflow configuration created to orchestrate and monitor the publishing process.
Workflow states:

Start - initial state when workflow is created
Requested - state indicating that a request was made to the publisher (the content event msg was sent to the content topic)
Processing - state indicating that the publisher has received the request and is processing
Succeeded - the publish process completed normally
Failed - the publish process failed
End - workflow has ended

Using this workflow, the state can be queried to indicate the status of the publishing process.
Here is the first version of this process definition:

<?xml version="1.0" encoding="UTF-8"?>

<process-definition  xmlns="urn:jbpm.org:jpdl-3.2"  name="publishContentBasic">
<start-state name="start">
<transition name="to_requested" to="requested">
  <action name="action" class="com.sample.action.MessageActionHandler">
      <message>Going to the first state - requested!</message>
  </action>
</transition>
</start-state>

<state name="requested">
<transition to="processing" name="to_processing"></transition>
</state>

<state name="processing">
<transition to="succeeded" name="to_succeeded"></transition>
<transition to="failed" name="to_failed"></transition>
</state>

<state name="succeeded">
<transition to="end" name="to_end">
<action name="action" class="com.sample.action.MessageActionHandler">
      <message>About to finish - succeeded!</message>
  </action>
</transition>
</state>

<state name="failed">
<transition to="end" name="to_end">
  <action name="action" class="com.sample.action.MessageActionHandler">
      <message>About to finish - failed!</message>
  </action>
</transition>
</state>

<end-state name="end"></end-state>
</process-definition>

This first configuration of the process is basic and simple. It will be embellished later with processing and business logic. This example uses the com.sample.action.MessageActionHandler class that is created by default using the 'create jbpm project' option in Eclipse.

Step 5 - The first test
In this first pass, we are using jBPM out of the box, without Alfresco. This mode allows us to configure and test our process in as much isolation as possible. Later we will use the Alfresco SDK to run as an Embedded Alfresco when we need Alfresco workflow services.

package com.sample;

import junit.framework.TestCase;

import org.jbpm.graph.def.ProcessDefinition;
import org.jbpm.graph.exe.ProcessInstance;

public class PublishContentBasicProcessTest extends TestCase {

public void testSimpleProcess() throws Exception {

  // Extract a process definition from the processdefinition.xml file.
  ProcessDefinition processDefinition = ProcessDefinition.parseXmlResource("publishContentBasic/processdefinition.xml");
  assertNotNull("Definition should not be null", processDefinition);

  // Create an instance of the process definition.
  ProcessInstance instance = new ProcessInstance(processDefinition);
  assertEquals(
          "Instance is in start state",
          instance.getRootToken().getNode().getName(),
          "start");
  assertNull(
          "Message variable should not exist yet",
          instance.getContextInstance().getVariable("message"));

  // Move the process instance from its start state to the first state.
  // The configured action should execute and the appropriate message
  // should appear in the message process variable.
  instance.signal();
  assertEquals(
          "Instance is in reqested state",
          instance.getRootToken().getNode().getName(),
          "requested");
  assertEquals(
          "Message variable contains message",
          "Going to the first state - requested!",
          instance.getContextInstance().getVariable("message"));

  //move to processing state
  instance.signal();
  assertEquals(
          "Instance is in processing state",
          "processing",
          instance.getRootToken().getNode().getName());

  //move to succeeded state
  instance.signal("to_succeeded");
  assertEquals(
          "Instance is in processing state",
          "succeeded",
          instance.getRootToken().getNode().getName());

  // Move the process instance to the end state. The configured action
  // should execute again. The message variable contains a new value.
  instance.signal();
  assertEquals(
          "Instance is in end state",
          "end",
          instance.getRootToken().getNode().getName());
  assertTrue("Instance has ended", instance.hasEnded());
  assertEquals(
          "Message variable contains message",
          "About to finish!",
          instance.getContextInstance().getVariable("message"));
}
}

Next Part, on to running workflows in Alfresco Embedded mode and running alfresco scripts in the workflow.

This

Extending Share 3 - Adding new pages to share

2009-01-08T10:02:00.000-08:00

In a previous blog article 'Extending Share 2 - Adding a New Content button to Document Library', we walked through the process of modifying Document Library to add a new toolbar component that included a button titled 'New Content'. In this article, We will walk through the process of creating a new page for Share that can be included for a site, adding to the existing pages including wiki, blog, discussion, document library, calendar etc. that can be selected from the site navigation bar. As an example, the new page we add will present a new view of document library content, leveraging some existing components form the Document Library page such as the tree navigation component.

This blog article will add these new pages into the share extension project structure discussed in the previous blog article 'Extending Share 1 - Creating a share extension project' that provides a clean way to isolate our changes from the existing share code. The new page will be able to be added to existing or new sites by using the 'Customize Site' feature of the site dashboard and selecting the new page.

Step 1 - Setting up the project

We will start with creating a project structure similar to that referenced in the previous blog article 'Extending Share 1 - Creating a share extension project' and the latest Alfresco SDK.

1. Create a new project (i.e. 'someco-share-extension') with the following source directories :

source/java - contains java code to be packaged in someco-share-ext.jar
config/alfresco/web-extension - contains 'web-framework-config-custom.xml'
config/alfresco/web-extension/site-data - contains custom model objects like pages, template-instances, and components
config/alfresco/web-extension/site-webscripts containing folder /com/someco to contain webscripts in a unique namespace
config/alfresco/templates - contains custom templates containing folder /com/someco to contain templates in unique namespace
source/web - contains web assets and delivered to the war, used for javascript and css as included by html templates
lib - contains required library elements (includes junit.jar for testing
test - contains java test code and configuration

I created each of these folders as a 'source directory' in Eclipse. Source directories in Eclipse automatically copy files to the classpath. This project depends on SDK Embedded to allow embedded testing (unit testing of custom data web scripts) (see the 'Unit Testing Web Scripts' blog article for using the SDK to run embedded unit tests of data web scripts.

2. Create the 'web-framework-config-custom.xml' file in the to contain a reference to our new page so that it can be included by customizing a site.

3. Copy the ant build.xml file from the source in the previous 'Extending Share' blog article into the root of the project. This build script has some handy tasks. Some of which were derived from the great works by Jeff Potts and his great new book Alfresco Developers Guide from Packt Publishing. Make sure to change the project name in the build.xml file as appropriate (i.e. 'someco-share-extension').

The 'deploy' tasks will call the 'package' task and copy the created jar to the APP_TOMCAT_HOME/WEB-INF/lib directory (should be configured to point to the expanded share war file directory in tomcat), and copy the contents of the 'source/web' and 'config/alfresco/*' folders to the APP_TOMCAT_HOME/WEB-INF/classes/alfresco directory.
The 'package' task will call the 'compile' taks and create a jar (someco-share-ext.jar) including our java code in the source/java folder, web scripts in the 'config/someco/site-webscripts' and templates in the 'config/someco/templates' folders.

Make sure APP_TOMCAT_HOME environment variable is configured to point to the directory where share war is deployed. In Eclipse, you can add this to the ant configuration (windows > preferences > ant > runtime, 'properties' tab as env.APP_TOMCAT_HOME).

4. Create (or copy) the build.properties file to the project root directory containing the following:

#directory names

dir.name.assemble=assemble
dir.name.bin=bin
dir.name.build=build
dir.name.classes=classes
dir.name.config=config
dir.name.source=source
dir.name.devenv=devenv
dir.name.dist=dist
dir.name.distro=distro
dir.name.docs=docs
dir.name.generated=generated
dir.name.java=java
dir.name.lib=lib
dir.name.test.results=
dir.name.test.results=test-results
dir.name.test.resources=test-resources
dir.name.web=web

file.name.jar=someco-share-ext.jar

dir.junit.lib=lib

Now we are ready to start creating our custom configuration. You can adjust these to make the ant build work with your own project structure.

Step 2 - Creating the page and template instance

To start out, we will create a new page called 'Content Grid' that is intended to display a list of content in a way similar to Document Library but as a grid showing meta-data and a content extract in columns. This extension follows the model object structure as outlined in the Alfresco Surf Platform - Developers Guide page, and analyzed in the 'Learning Surf 2 - Examining Slingshot configuration' blog article.

The custom model objects we create will be added to the 'config/alfresco/web-extension' source directory. The contents of this directory will be copied into the Share war directory using the ant deploy task in the Ant build file.

1. Create 'contentgrid.xml' file in the 'pages' folder of the 'source/alfresco/web-extension/site-data' source directory, with the following content:

<?xml version='1.0' encoding='UTF-8'?>
<page>
<title>Content Grid</title>
<description>Document library with Tree view</description>
<template-instance>contentgrid</template-instance>
<authentication>user</authentication>
</page>

This defines a page with the title 'Content Grid'. It refers to a template instance called 'contentgrid' defined next.

2. Create the 'contentgrid.xml' template instance in the 'template-instances' folder of the 'config/alfresco/web-extension/site-data' source folder with the following contents:

<?xml version='1.0' encoding='UTF-8'?>
<template-instance>
<template-type>org/alfresco/simple-contentgrid</template-type>
<properties>
<hasBreadcrumb>true</hasBreadcrumb>
<hasTreeview>true</hasTreeview>
<hasPackager>true</hasPackager>
</properties>
</template-instance>

This file tells Surf to use the template found from path org/alfresco/contentgrid path of the config/alfresco/templates folder.

Step 3 - Creating the template type

The template we will create first will be a simple test template with no functionality, to test our configuration and deployment. This template is a gutted out version of the documentlibrary.ftl found in the config/alfresco/templates source folder in the org/alfresco package. It includes a standard set of included global regions with a simple body announcing that the template has rendered.

1. Create 'simple-contentgrid.ftl' freemarker template in the org/alfresco path of the 'config/alfresco/templates' source folder with the following contents:

<#import "/org/alfresco/import/alfresco-template.ftl" as template />
<@template.header>
<link rel="stylesheet" type="text/css" href="${url.context}/templates/documentlibrary/documentlibrary.css" />
<script type="text/javascript">//<![CDATA[
(function()
{
// If no location.hash exists, convert a location.search to a location.hash and replace the page
var loc = window.location;
if (loc.hash === "" && loc.search !== "")
{
 var url = loc.protocol + "//" + loc.host + loc.pathname + "#" + loc.search.substring(1);
 window.location.replace(url);
}
})();
//]]></script>
<script type="text/javascript" src="${url.context}/templates/documentlibrary/documentlibrary.js"></script>
<script type="text/javascript" src="${url.context}/modules/documentlibrary/doclib-actions.js"></script>
</@>

<@template.body>
<div id="hd">
<@region id="header" scope="global" protected=true />
<@region id="title" scope="template" protected=true />
<@region id="navigation" scope="template" protected=true />
</div>
<div id="bd">
This is the Content Grid template
</div>
<p>&nbsp;</p>
<p>&nbsp;</p>
</@>

<@template.footer>
<div id="ft">
<@region id="footer" scope="global" protected=true />
</div>
</@>

2. Modify 'web-framework-config-custom.xml' file in the 'config/alfresco/web-extensions' folder to add a reference to the new page we just created to allow this page to be added when customizing the site. It should read:

<alfresco-config>


<config evaluator="string-compare" condition="SitePages" replace="true">
<pages>
   <page id="calendar">calendar</page>
   <page id="wiki-page">wiki-page?title=Main_Page</page>
   <page id="documentlibrary">documentlibrary</page>
   <page id="contentgrid">contentgrid</page>
   <page id="discussions-topiclist">discussions-topiclist</page>
   <page id="blog-postlist">blog-postlist</page>
</pages>
</config>

</alfresco-config>

When Share is started, the new page will not be configured to display with any sites. The new page can be added to existing sites by using the 'customize site' feature. If you wish this new page to be automatically added to new sites, add it to the 'presets.xml' file.

3. Run the ant deploy task to copy the configuration components to the deployed share war (APP_TOMCAT_HOME/webapps/share)

4. Start alfresco and share by starting tomcat

5. Login to share

6. Create the new site (or select it if already created)

7. Select the 'Customize Site' button and click 'Add Page' and select the 'Content Grid' page. The 'Content Grid' page should be added to the navigation bar.

8. Press this option to see the page we just created with the simple-contentgrid.ftl template. The message 'This is the Content Grid template' should be displayed.

Step 4 - Mapping the page components
Now we can advance to a more interesting page template. The previous simple-contentgrid.ftl only demonstrated that we could add a page and it would render, now we will create a page template that will be similar to the Document Library template, but display our custom grid view UI.
1. create contentgrid.ftl in the /org/alfresco directory of the /config/alfresco/templates source folder, with containing the following:

<#import "/org/alfresco/import/alfresco-template.ftl" as template />
<@template.header>
<link rel="stylesheet" type="text/css" href="${url.context}/templates/documentlibrary/documentlibrary.css" />
<script type="text/javascript">//<![CDATA[
(function()
{
 // If no location.hash exists, convert a location.search to a location.hash and replace the page
 var loc = window.location;
 if (loc.hash === "" && loc.search !== "")
 {
    var url = loc.protocol + "//" + loc.host + loc.pathname + "#" + loc.search.substring(1);
    window.location.replace(url);
 }
})();
//]]></script>
<script type="text/javascript" src="${url.context}/templates/documentlibrary/documentlibrary.js"></script>
<script type="text/javascript" src="${url.context}/modules/documentlibrary/doclib-actions.js"></script>
</@>

<@template.body>
<div id="hd">
 <@region id="header" scope="global" protected=true />
 <@region id="title" scope="template" protected=true />
 <@region id="navigation" scope="template" protected=true />
</div>
<div id="bd">
 <div class="yui-t1" id="divDocLibraryWrapper">
    <div id="yui-main">
       <div class="yui-b" id="divDocLibraryDocs">
          <@region id="toolbar" scope="template" protected=true />
          <@region id="gridview" scope="template" protected=true />
       </div>
    </div>
    <div class="yui-b" id="divDocLibraryFilters">
       <@region id="filter" scope="template" protected=true />
       <@region id="tree" scope="template" protected=true />
       <@region id="tags" scope="template" protected=true />
    </div>
 </div>
</div>
<p>&nbsp;</p>
<p>&nbsp;</p>
</@>

<@template.footer>
<div id="ft">
 <@region id="footer" scope="global" protected=true />
</div>
</@>

This template contains several regions, some global and some template specific. The template specific regions must have component configuraton xml files to indicate what ui webscript will be used to render in that region. The components follow a naming convention: ..

Writing Webscripts 1 - Unit Testing Web Scripts

2008-12-19T14:15:00.000-08:00

There is a big push in the agile community to develop code using a Test Driven Development approach. This could be anything from 'test first' extreme programming to assuring a certain coverage metric is achieved with unit tests that accompany delivered code. Either case, the test driven approach yields better code in a shorter period of time, is more self documented, better factored, and is not as prone to chaos effects when changed. Should web scripts be subject to unit testing? I believe it is important to test at least the data web scripts using a testing harness like xUnit that can be run during builds or in continuous integration. There are examples of this type of test within the Alfresco 3.0 source tree.

This blog entry will focus on creating a project in Eclipse that leverages the Alfresco SDK (currently 3c) to test and deploy web scripts to the Alfresco repository. These unit tests will run with Embedded Alfresco configuration to be as self-contained as possible. Although these tests will not be unit tests in the strictest sense of the word, they will help facilitate more rapid development of code with the appropriate tests within an IDE. These tests can also be run as part of continuous integration.

The sourcecode for this article is available from this site.

Step 1 - Download and Install SDK with Eclipse
Follow the Alfresco SDK wiki page to install the SDK. Essentially, you will execute the following steps:

Download alfresco-sdk-3c
Import into Eclipse
Add dependency libraries to SDK AlfrescoEmbedded
Validate with SDK FirstFoundationClient

Step 2 - Setup the project
In order to run unit tests that test data web scripts properly, we need to set up a project that can lauch Alfresco as an Embedded server, with sufficient configuration files to allow us to test our data web scripts.

Here is a summary of the steps I followed:

Copy SDK FirstFoundatoinClient as a starting point.
Set project dependency to SDK AlfrescoEmbedded
Modify dir.root of custom-repository.properties
Test run as application main of FirstFoundationClient

To create the project 'unit-test-webscripts', I copied the SDK's FirstFoundationClient in Eclipse and renamed it to 'unit-test-webscripts'. This project should already reference the SDK AlfrescoEmbedded project, and be configured to run Alfresco as Embedded, but it will need to be altered to run web scripts this way.

Modify the 'custom-repository.properties' file to reference the alfresco data root directory that you have configured when running Alfresco. It will be necessary to reference the same dir.root as alfresco when it is run standalone to share a database instance on the same machine, and allow you to test in either embedded mode or remote mode. I also added the line 'index.recovery.mode=FULL' to force the indexer to recover any out of sync references.

At this point, you should be able to run the 'main' method of the FirstFoundationClass of this project with eclipse' 'Run as Application' to make sure all is well.

NOTE: This step failed for me with a class not found error until I included a library reference to: alfresco-jlan-embed.jar in the java build path of the SDK AlfrescoEmbedded project and exported it.

After running, you should see in the console the line 'Alfresco started' to indicate the test was completed. The result of the run should be a new content item created in the repository with the name 'Foundation API sample (current Time in Milliseconds)' within the 'Company Home' folder. Start tomcat where alfresco is deployed and log in to view the Company Home folder. You should see the new files added. Make sure to stop tomcat before running embedded tests.

Step 3 - Configure to Run Web scripts via embedded alfresco

Once the project is copied and we can run the test class, we can now configure it to run our test webscripts. To summarize the steps:

Create a source folder 'test' to contain configuration files and unit test code
Create a folder 'alfresco' within the 'test' source folder to which we will copy the necessary spring context files
copy web-scripts-application-context.xml from $TOMCAT_HOME/webapps/alfresco/WEB-INF/classes/alfresco to test/alfresco
copy webscript-framework-application-context.xml from $TOMCAT_HOME/webapps/alfresco/WEB-INF/classes/alfresco to test/alfresco
copy web-scripts-application-context-test.xml from $TOMCAT_HOME/webapps/alfresco/WEB-INF/classes/alfresco to test/alfresco
comment out web Script messages bean 'webscripts.resources' of webscript-framework-application-context.xml
copy web-scripts-config.xml from $TOMCAT_HOME/webapps/alfresco/WEB-INF/classes/alfresco to test/alfresco
comment out bean 'webscript.org.alfresco.repository.dictionary.getchildassoc.get' from web-scripts-application-context.xml since class 'org.afresco.repo.web.scripts.dictionary.GetChildAssociationDef' no longer exists in jars
comment out bean 'webscript.org.alfresco.repository.dictionary.getchildassocs.get' from web-scripts-application-context.xml since class 'org.afresco.repo.web.scripts.dictionary.GetChildAssociationDefs' no longer exists in jars
create required directory source/alfresco/templates/webscripts
create required directory source/alfresco/webscripts
copy webscript-framework-config.xml from $TOMCAT_HOME/webapps/alfresco/WEB-INF/classes/alfresco to test/alfresco
create required directory source/alfresco/templates/activities
create directory source/alfresco/extension/templates/webscripts where our webscritps will go
copy 'status.ftl' from $TOMCAT_HOME/webapps/alfresco/WEB-INF/classes/alfresco to test/alfresco/extension/templates/webscripts to the new extension/templates/webscripts directory to provide a default status template

Now the project is set up to run our webscripts.

Step 4 - Write the unit test and webscript

Add our data webscript to test into the source/alfresco/extension/templates/webscripts folder

Create 'test.get.desc.xml' with the following contents:

<webscript>
<shortname>test</shortname>
<description>Return runas user name</description>
<format>argument</format>
<url>/someco/test</url>
<authentication runas="RunAsOne">user</authentication>
<transaction>required</transaction>
</webscript>

This description describes the webscript 'someco/test' that will run as the user RunAsOne.
Create 'test.get.html.ftl' with the following contents:

${userName!"<notset>"}

This template will display the value of userName.
Create 'test.get.js' with the following code:

model.userName = person.properties.userName;

This script will set the value of userName with the current userName we are running as.
Thats it for the webscript. Now create the unit test into the test/org/someco directory called 'RunAsTest' to test the data webscript:

package org.someco;

import org.alfresco.model.ContentModel;
import org.alfresco.repo.web.scripts.BaseWebScriptTest;
import org.alfresco.service.cmr.security.AuthenticationService;
import org.alfresco.service.cmr.security.PersonService;
import org.alfresco.util.PropertyMap;
import org.alfresco.web.scripts.TestWebScriptServer.GetRequest;
import org.alfresco.web.scripts.TestWebScriptServer.Response;

public class RunAsTest extends BaseWebScriptTest {
  private AuthenticationService authenticationService;
  private PersonService personService;

  private static final String USER_ONE = "RunAsOne";

  private static final String URL_GET_CONTENT = "/someco/test";

  @Override
  protected void setUp() throws Exception
  {
      super.setUp();

      this.authenticationService = (AuthenticationService) getServer().getApplicationContext().getBean(
              "AuthenticationService");
      this.personService = (PersonService) getServer().getApplicationContext().getBean("PersonService");

      // Create users
      createUser(USER_ONE);
  }

  private void createUser(String userName)
  {
      if (this.authenticationService.authenticationExists(userName) == false)
      {
          this.authenticationService.createAuthentication(userName, "PWD".toCharArray());

          PropertyMap ppOne = new PropertyMap(4);
          ppOne.put(ContentModel.PROP_USERNAME, userName);
          ppOne.put(ContentModel.PROP_FIRSTNAME, "firstName");
          ppOne.put(ContentModel.PROP_LASTNAME, "lastName");
          ppOne.put(ContentModel.PROP_EMAIL, "email@email.com");
          ppOne.put(ContentModel.PROP_JOBTITLE, "jobTitle");

          this.personService.createPerson(ppOne);
      }
  }

  @Override
  protected void tearDown() throws Exception
  {
      super.tearDown();
  }

  public void testRunAs() throws Exception
  {
      Response response = sendRequest(new GetRequest(URL_GET_CONTENT), 200, "admin");
      assertEquals(USER_ONE, response.getContentAsString());
  }

}

This test creates 'UserOne', runs the 'someco/test' webscript, and checks the result code as 200 (success) and to see if the user name this script 'run as' was returned in the response.

Step 5 - Run the unit test

In order to see results, you should copy the log4j.properties file from $TOMCAT_HOME/webapps/alfresco/WEB_INF/classes into your source directory and configure log4j.properties to show debugging information for running web scripts by setting 'log4j.logger.org.alfresco.web.scripts=debug' and 'log4j.logger.org.alfresco.repo.web.scripts=debug' as recommended in the logging session of the 3.0 Web scripts Framework page of alfresco wiki.

To run the test, simply select the test/com/someco/RunAsTest class in Eclipse and select the 'run as' JUnit test. The test should pass and the console should show something like 'Processed script url (get) /someco/test in 517.601ms' as its last line.

Step 6 - Deploy the web script

Once confirmed, the web script tested can be deployed either by uploading it to the Company Home/Data Dictionary/Web Scripts Extensions space or add the web scripts to the $TOMCAT_HOME/webapps/alfresco/WEB-INF/classes/alfresco/extension/templates/webscripts folder and restarting alfresco.

Extending Share 2 - Adding a New Content button to Document Library

2008-12-08T13:53:00.001-08:00

In the Extending Share 1 blog entry, we created a share extension project. Now we will write code to add a 'new content' button to the document library section of Share, based on the code created in the learning surf 1-6 blog entries.

NOTE: the complete sourceocde for this project can be downloaded from here.

Step 1 - Create a new form component

We will create a ui web script to open a create content form. In the 'config/alfresco/site-webscripts' source folder in package 'com.orbitz.components.documentlibrary', add the following files:

create-content.get.desc.xml

<webscript>
<shortname>create-content</shortname>
<description>Create Content module primarily for Document Library</description>
<url>/components/documentlibrary/create-content</url>
</webscript>

create-content.get.html.ftl

<div id="${args.htmlid}-dialog" class="create-folder">
<div class="hd">${msg("title")}</div>
<div class="bd">
<form id="${args.htmlid}-form" action="" method="post" accept-charset="utf-8">
<div class="yui-g">
<h2>${msg("header")}:</h2>
</div>
<div class="yui-gd">
<div class="yui-u first"><label for="${args.htmlid}-name">${msg("label.name")}:</label></div>
<div class="yui-u"><input id="${args.htmlid}-name" type="text" name="name" tabindex="1" />&nbsp;*</div>
</div>
<div class="yui-gd">
<div class="yui-u first"><label for="${args.htmlid}-title">${msg("label.title")}:</label></div>
<div class="yui-u"><input id="${args.htmlid}-title" type="text" name="title" tabindex="2" /></div>
</div>
<div class="yui-gd">
<div class="yui-u first"><label for="${args.htmlid}-description">${msg("label.description")}:</label></div>
<div class="yui-u"><textarea id="${args.htmlid}-description" name="description" rows="3" cols="20" tabindex="3" ></textarea></div>
</div>
<div class="yui-gd">
<div class="yui-u first"><label for="${args.htmlid}-content">${msg("label.content")}:</label></div>
<div class="yui-u"><textarea id="${args.htmlid}-content" name="content" rows="3" cols="20" tabindex="3" ></textarea></div>
</div>
<div class="bdft">
<input type="button" id="${args.htmlid}-ok" value="${msg("button.ok")}" tabindex="4" />
<input type="button" id="${args.htmlid}-cancel" value="${msg("button.cancel")}" tabindex="5" />
</div>
</form>
</div>
</div>

</code></pre>

create-content.get.properties

## Titles
title=New Content
header=New Content Details

## Labels
label.name=Name
label.title=Title
label.description=Description
label.content=Content

To test the new form,

Deploy the web script by running the 'deploy' an task. (Make sure that share was started at least once so that the share war is expanded in the webapps/share directory of tomcat, and that the APP_TOMCAT_HOME and TOMCAT_HOME is properly set. This will copy the web scripts to the share directory.
Start tomcat
Check the ui web script by going to the url http://localhost:8080/share/service/components/documentlibrary/create-content?htmlid which should render the form (without any CSS, though).

Step 2 - Create a new toolbar for Document Library adding the 'New Content' button

The document library toolbar will be modified to render the 'New Content' button linked to an action handler that will open the create-content form via the simple dialog mechanism. To do this, we will create a new toolbar component '/orbitz/components/documentlibrary/toolbar' that will augment the existing '/components/documentlibrary/toolbar' with minimal code replication. This is a bit dangerous since it is entirely possible that the document library toolbar will change over time, so perhaps overriding it in this way is not the best approach, however, I have tried to minimize the exposure to code change as much as possible. if others have a better approach, I would gladly accept it. The source for this new component will also be in the 'config/alfresco/site-webscripts' source folder in the 'com.orbitz.components.documentlibrary' package, with the following files:
toobar.get.desc.xml
This component description alters the url to '/orbitz/component/documentlibrary/toolbar' which will have to be mapped for the 'toolbar' the region of the documentlibary template.

<webscript>
<shortname>DocLib Toolbar</shortname>
<description>Document Library: Toolbar Component</description>
<url>/orbitz/components/documentlibrary/toolbar</url>
</webscript>

toolbar.get.head.ftl
This is a copy of the original 'toolbar.get.head.ftl' with the addition of DocListOrbitzToolbar Assets including 'orbitz.toolbar.css' and 'orbitz.toolbar.js' which provide custom styles and behavior for the 'New Content' button.

<!-- DocListOrbitzToolbar Assets -->
<link rel="stylesheet" type="text/css" href="${page.url.context}/components/documentlibrary/orbitz.toolbar.css" />
<script type="text/javascript" src="${page.url.context}/components/documentlibrary/orbitz.toolbar.js"></script>
<!-- DocListToolbar Assets -->
<link rel="stylesheet" type="text/css" href="${page.url.context}/components/documentlibrary/toolbar.css" />
<script type="text/javascript" src="${page.url.context}/components/documentlibrary/toolbar.js"></script>
<!-- Simple Dialog Assets -->
<script type="text/javascript" src="${page.url.context}/modules/simple-dialog.js"></script>
<!-- File-Upload Assets -->
<link rel="stylesheet" type="text/css" href="${page.url.context}/modules/flash-upload.css" />
<script type="text/javascript" src="${page.url.context}/modules/flash-upload.js"></script>
<link rel="stylesheet" type="text/css" href="${page.url.context}/modules/html-upload.css" />
<script type="text/javascript" src="${page.url.context}/modules/html-upload.js"></script>
<script type="text/javascript" src="${page.url.context}/modules/file-upload.js"></script>

toolbar.get.html.ftl
This is a copy of the original 'toolbar.get.html.ftl' with a new javascript block instantiating 'alfresco.DocListOrbitzToolbar' as well as 'Alfresco.DocListToolbar'. This new javascript object will be defined in the new javascript file 'orbitz.toolbar.js' referenced in 'toolbar.get.head.ftl' above. Also, the 'new-content' button is added beneath the 'new folder' button.

<script type="text/javascript">//<![CDATA[
new Alfresco.DocListToolbar("${args.htmlid}").setOptions(
{
siteId: "${page.url.templateArgs.site!""}"
}).setMessages(
${messages}
);
new Alfresco.DocListOrbitzToolbar("${args.htmlid}").setOptions(
{
siteId: "${page.url.templateArgs.site!""}"
}).setMessages(
${messages}
);
//]]></script>
<div id="${args.htmlid}-body" class="toolbar">

<div id="${args.htmlid}-headerBar" class="header-bar flat-button">
<div class="new-folder hideable DocListTree"><button id="${args.htmlid}-newFolder-button" name="newFolder">${msg("button.new-folder")}</button></div>
<div class="new-content hideable DocListTree"><button id="${args.htmlid}-newContent-button" name="newContent">${msg("button.new-content")}</button></div>
<div class="separator hideable DocListTree">&nbsp;</div>
<div class="file-upload hideable DocListTree"><button id="${args.htmlid}-fileUpload-button" name="fileUpload">${msg("button.upload")}</button></div>
<div class="separator hideable DocListTree">&nbsp;</div>
<div class="selected-items hideable DocListTree DocListFilter DocListTags">
<button class="no-access-check" id="${args.htmlid}-selectedItems-button" name="doclist-selectedItems-button">${msg("menu.selected-items")}</button>
<div id="${args.htmlid}-selectedItems-menu" class="yuimenu">
<div class="bd">
<ul>
 <li><a rel="" href="#"><span class="onActionCopyTo">${msg("menu.selected-items.copy")}</span></a></li>
 <li><a rel="" href="#"><span class="onActionMoveTo">${msg("menu.selected-items.move")}</span></a></li>
 <li><a rel="delete" href="#"><span class="onActionDelete">${msg("menu.selected-items.delete")}</span></a></li>
 <li><a type="document" rel="" href="#"><span class="onActionAssignWorkflow">${msg("menu.selected-items.assign-workflow")}</span></a></li>
 <li><a rel="permissions" href="#"><span class="onActionManagePermissions">${msg("menu.selected-items.manage-permissions")}</span></a></li>
 <li><hr/></li>
 <li><a rel="" href="#"><span class="onActionDeselectAll">${msg("menu.selected-items.deselect-all")}</span></a></li>
</ul>
</div>
</div>
</div>
<div class="rss-feed"><button id="${args.htmlid}-rssFeed-button" name="rssFeed">${msg("link.rss-feed")}</button></div>
</div>

<div id="${args.htmlid}-navBar" class="nav-bar flat-button">
<div class="folder-up hideable DocListTree"><button class="no-access-check" id="${args.htmlid}-folderUp-button" name="folderUp">${msg("button.up")}</button></div>
<div class="separator hideable DocListTree">&nbsp;</div>
<div id="${args.htmlid}-breadcrumb" class="breadcrumb hideable DocListTree"></div>
<div id="${args.htmlid}-description" class="description hideable DocListFilter DocListTags"></div>
</div>

</div>

toobar.get.properties
This is a copy of the original toolbar.get.properties with only a new couple of new properties:

button.new-content
message.new-content

## Buttons
button.delete=Delete
button.new-folder=New Folder
button.new-content=New Content
button.up=Up
button.upload=Upload

## Links
link.rss-feed=RSS Feed

## Drop-down Menus
menu.selected-items=Selected Items...
menu.selected-items.copy=Copy to...
menu.selected-items.move=Move to...
menu.selected-items.delete=Delete
menu.selected-items.assign-workflow=Assign Workflow...
menu.selected-items.manage-permissions=Manage Permissions...
menu.selected-items.deselect-all=Deselect All

## Pop-up Messages
message.new-folder.success=Folder '{0}' created
message.new-content.success=Content '{0}' created
message.new-folder.failure=Could not create '{0}'
message.new-content.failure=Could not create '{0}'
message.multiple-delete.success=Successfully deleted {0} item(s)
message.multiple-delete.failure=Could not delete items
title.multiple-delete.confirm=Confirm Multiple Delete
message.multiple-delete.confirm=Are you sure you want to delete the following {0} items?
message.multiple-delete.please-wait=Please wait. Files being deleted...

## Toolbar Modes
description.path=
description.path.more=
description.all=All Documents in the Document Library
description.all.more=
description.editingMe=Documents I'm Editing
description.editingMe.more=(working copies)
description.editingOthers=Documents Others are Editing
description.editingOthers.more=(working copies)
description.recentlyModified=Documents Recently Modified
description.recentlyModified.more=
description.recentlyAdded=Documents Added Recently
description.recentlyAdded.more=
description.tag=Documents and Folders Tagged with
description.tag.more={0}

Step 3, create the javascript to support the toolbar

Within the 'source/web' source folder 'components.documentlibrary' package, the new javascript and css assets referenced in 'toolbar.get.head.ftl' are defined:

orbitz.toolbar.js

This javascript creates a new object: 'Alfresco.DocListOrbitzToolbar' instantiated in 'toolbar.get.html.ftl' that decorates the 'newContent' button as a YUI button mapped to the 'onNewContent' action handler to open the new-content form using the SimpleDialog mechanism

/**
* DocumentList Toolbar component.
*
* @namespace Alfresco
* @class Alfresco.DocListToolbar
*/
(function()
{
/**
* YUI Library aliases
*/
var Dom = YAHOO.util.Dom,
Event = YAHOO.util.Event,
Element = YAHOO.util.Element;

/**
* Alfresco Slingshot aliases
*/
var $html = Alfresco.util.encodeHTML;

/**
* DocListToolbar constructor.
*
* @param {String} htmlId The HTML id of the parent element
* @return {Alfresco.DocListToolbar} The new DocListToolbar instance
* @constructor
*/
Alfresco.DocListOrbitzToolbar = function(htmlId)
{
// Mandatory properties
this.name = "Alfresco.DocListOrbitzToolbar";
this.id = htmlId;

// Initialise prototype properties
this.widgets = {};
this.modules = {};
this.selectedFiles = [];
this.currentFilter =
{
filterId: "",
filterOwner: "",
filterData: ""
};

// Register this component
Alfresco.util.ComponentManager.register(this);

// Load YUI Components
Alfresco.util.YUILoaderHelper.require(["button", "menu", "container"], this.onComponentsLoaded, this);

// Decoupled event listeners
//YAHOO.Bubbling.on("pathChanged", this.onPathChanged, this);
//YAHOO.Bubbling.on("folderRenamed", this.onPathChanged, this);
//YAHOO.Bubbling.on("filterChanged", this.onFilterChanged, this);
YAHOO.Bubbling.on("deactivateAllControls", this.onDeactivateAllControls, this);
//YAHOO.Bubbling.on("selectedFilesChanged", this.onSelectedFilesChanged, this);
YAHOO.Bubbling.on("userAccess", this.onUserAccess, this);

return this;
};

Alfresco.DocListOrbitzToolbar.prototype =
{
/**
* Object container for initialization options
*
* @property options
* @type object
*/
options:
{
/**
* Current siteId.
*
* @property siteId
* @type string
*/
siteId: "",

/**
* ContainerId representing root container
*
* @property containerId
* @type string
* @default "documentLibrary"
*/
containerId: "documentLibrary",

/**
* Number of multi-file uploads before grouping the Activity Post
*
* @property groupActivitiesAt
* @type int
* @default 5
*/
groupActivitiesAt: 5,

/**
* Flag indicating whether navigation bar is visible or not.
*
* @property hideNavBar
* @type boolean
*/
hideNavBar: false
},

/**
* Current path being browsed.
*
* @property currentPath
* @type string
*/
currentPath: "",

/**
* Current filter to choose toolbar view and populate description.
*
* @property currentFilter
* @type string
*/
currentFilter: null,

/**
* FileUpload module instance.
*
* @property fileUpload
* @type Alfresco.module.FileUpload
*/
fileUpload: null,

/**
* Object container for storing YUI widget instances.
*
* @property widgets
* @type object
*/
widgets: null,

/**
* Object container for storing module instances.
*
* @property modules
* @type object
*/
modules: null,

/**
* Array of selected states for visible files.
*
* @property selectedFiles
* @type array
*/
selectedFiles: null,

/**
* Set multiple initialization options at once.
*
* @method setOptions
* @param obj {object} Object literal specifying a set of options
* @return {Alfresco.DocListToolbar} returns 'this' for method chaining
*/
setOptions: function DLTB_setOptions(obj)
{
this.options = YAHOO.lang.merge(this.options, obj);
return this;
},

/**
* Set messages for this component.
*
* @method setMessages
* @param obj {object} Object literal specifying a set of messages
* @return {Alfresco.DocListToolbar} returns 'this' for method chaining
*/
setMessages: function DLTB_setMessages(obj)
{
Alfresco.util.addMessages(obj, this.name);
return this;
},

/**
* Fired by YUILoaderHelper when required component script files have
* been loaded into the browser.
*
* @method onComponentsLoaded
*/
onComponentsLoaded: function DLTB_onComponentsLoaded()
{
Event.onContentReady(this.id, this.onReady, this, true);
},

/**
* Fired by YUI when parent element is available for scripting.
* Component initialisation, including instantiation of YUI widgets and event listener binding.
*
* @method onReady
*/
onReady: function DLTB_onReady()
{

// New Content button: user needs "create" access
this.widgets.newContent = Alfresco.util.createYUIButton(this, "newContent-button", this.onNewContent,
{
disabled: true,
value: "create"
});

// Finally show the component body here to prevent UI artifacts on YUI button decoration
//Dom.setStyle(this.id + "-body", "visibility", "visible");
},


/**
* YUI WIDGET EVENT HANDLERS
* Handlers for standard events fired from YUI widgets, e.g. "click"
*/



/**
* New Content button click handler
*
* @method onNewContent
* @param e {object} DomEvent
* @param p_obj {object} Object passed back from addListener method
*/
onNewContent: function DLTB_onNewContent(e, p_obj)
{
var actionUrl = YAHOO.lang.substitute(Alfresco.constants.PROXY_URI + "slingshot/doclib/action/folder/site/{site}/{container}/{path}",
{
site: this.options.siteId,
container: this.options.containerId,
path: this.currentPath
});

var doSetupFormsValidation = function DLTB_oNF_doSetupFormsValidation(p_form)
{
// Validation
// Name: mandatory value
p_form.addValidation(this.id + "-createContent-name", Alfresco.forms.validation.mandatory, null, "keyup");
// Name: valid filename
p_form.addValidation(this.id + "-createContent-name", Alfresco.forms.validation.nodeName, null, "keyup");
p_form.setShowSubmitStateDynamically(true, false);
};

if (!this.modules.createContent)
{
this.modules.createContent = new Alfresco.module.SimpleDialog(this.id + "-createContent").setOptions(
{
width: "30em",
templateUrl: Alfresco.constants.URL_SERVICECONTEXT + "components/documentlibrary/create-content",
actionUrl: actionUrl,
doSetupFormsValidation:
{
   fn: doSetupFormsValidation,
   scope: this
},
firstFocus: this.id + "-createContent-name",
onSuccess:
{
   fn: function DLTB_onCreateContent_callback(response)
   {
      var file = response.json.results[0];
      YAHOO.Bubbling.fire("folderCreated",
      {
         name: file.name,
         parentPath: file.parentPath,fileCopied
         nodeRef: file.nodeRef
      });
      Alfresco.util.PopupManager.displayMessage(
      {
         text: this._msg("message.new-content.success", file.name)
      });
   },
   scope: this
}
});
}
else
{
this.modules.createContent.setOptions(
{
actionUrl: actionUrl,
clearForm: true
});
}
this.modules.createContent.show();
},
/**
* Deactivate All Controls event handler
*
* @method onDeactivateAllControls
* @param layer {object} Event fired
* @param args {array} Event parameters (depends on event type)
*/
onDeactivateAllControls: function DLTB_onDeactivateAllControls(layer, args)
{
var widget;
for (widget in this.widgets)
{
if (this.widgets.hasOwnProperty(widget))
{
this.widgets[widget].set("disabled", true);
}
}
},

/**
* User Access event handler
*
* @method onUserAccess
* @param layer {object} Event fired
* @param args {array} Event parameters (depends on event type)
*/
onUserAccess: function DLTB_onUserAccess(layer, args)
{
var obj = args[1];
if ((obj !== null) && (obj.userAccess !== null))
{
var widget, widgetPermissions, index;
for (index in this.widgets)
{
if (this.widgets.hasOwnProperty(index))
{
   widget = this.widgets[index];
   if (widget.get("srcelement").className != "no-access-check")
   {
      widget.set("disabled", false);
      if (widget.get("value") !== null)
      {
         widgetPermissions = widget.get("value").split(",");
         for (var i = 0, ii = widgetPermissions.length; i < ii; i++)
         {
            if (!obj.userAccess[widgetPermissions[i]])
            {
               widget.set("disabled", true);
               break;
            }
         }
      }
   }
}
}
}
},

/**
* Gets a custom message
*
* @method _msg
* @param messageId {string} The messageId to retrieve
* @return {string} The custom message
* @private
*/
_msg: function DLTB__msg(messageId)
{
return Alfresco.util.message.call(this, messageId, "Alfresco.DocListOrbitzToolbar", Array.prototype.slice.call(arguments).slice(1));
}

};
})();

This script at first will be configured to run the web script to create a new folder:

var actionUrl = YAHOO.lang.substitute(Alfresco.constants.PROXY_URI + "slingshot/doclib/action/folder/site/{site}/{container}/{path}",

In the following steps, we will create our own script that will create a new file.

orbitz.toolbar.css

This css defines the images and style used for the 'newContent' button:

.toolbar .new-content button
{
background: transparent url(images/content-new-16.png) no-repeat 12px 4px;
padding-left: 32px;
}

.toolbar .new-content .yui-button-disabled button
{
background-image: url(images/content-new-disabled-16.png);
}

these images are copies of the slingshot project's 'source/web/components/images/edit-blog-16.png' image.

Step 4 - Create the component to map to the 'toolbar' region of the document library template

Finally in the 'config/alfresco/site-data' source folder in the 'components' package, we override the existing 'toolbar' region in the 'documentlibrary' template to reference the /orbitz/components/documentlibrary/toolbar' component:

template.toolbar.documentlibrary.xml

<?xml version='1.0' encoding='UTF-8'?>
<component>
<scope>template</scope>
<region-id>toolbar</region-id>
<source-id>documentlibrary</source-id>
<url>/orbitz/components/documentlibrary/toolbar</url>
</component>

Step 5 - Deploy and Test
First, we need to make sure the 'share' war is installed and expanded in the tomcat host. I use the Alfresco project build.xml's

ant incremental-slingshot-tomcat-exploded

But for a war distribtuion, just make sure it is run at least once.

To use the build.xml, make sure to set APP_TOMCAT_HOME and TOMCAT_HOME environment variables as recommended in the previous blog article: Extending Share 1 - Creating a Share Extension Project

To build and deploy the share webapp expanded in the tomcat directory. Now we can deploy our extension code from the 'deals-share-extension' project's build.xml file:

ant deploy

This will create the 'deals-share-ext.jar' jar file and copy to the share/WEB-INF/lib directory, copy the configuration files from the config/alfresco/** source folders to the share/weB-INF/classes directory, and copy the web assets from the source/web source folders to the share root directory.

We can test our toolbar code directly using the url: http://localhost:8080/share/service/orbitz/components/documentlibrary/toolbar?htmlid , but this will not render with CSS, and without CSS, the YUI components wont work.

Now we can test within the Share:

Launch share http://localhost:8080/share, opens to the share dashboard
Create and/or select a Site, opens to the site dashboard
Select the 'document library' section should render our new toolbar with the 'New Content' button
Press the 'New Content' button and the 'create-content' form should open
Enter the new content's name, title, description and content int he form and press 'ok' and the dialog should close, but instead of a file created, we should see a new folder created. In the next steps we will create the web script necessary to create a new file.

Step 6 - Creating a custom web script action

Now we need to create a webscript service to use instead of the slingshot/doclib/action/folder service. for this blog, I will extend the action services to implement the following url pattern:

POST slingshot/doclib/action/file/site/{site}/{container}/{path}

To do this, we will add a new webscript service to the remote alfresco.war by uploading it to the Data Dictionary space. Later, we can separate this to our own amp module. As a starting point, we will copy the folder.post.* files to create file.post.* files in Remote API/config/alfresco/templates/webscripts/org/alfresco/slingshot/documentlibrary/action directory to create the following files:

file.post.desc.xml
file.post.json.ftl
file.post.json.js

Now we can modify these files to do the work of creating a file instead of a folder. for 'file.post.desc.xml' we modify the url pattern to the following:

<webscript>
<shortname>folder</shortname>
<description>Document List Action - Create folder</description>
<url>/slingshot/doclib/action/file/site/{site}/{container}</url>
<url>/slingshot/doclib/action/file/site/{site}/{container}/{path}</url>
<format default="json">argument</format>
<authentication>user</authentication>
<transaction>required</transaction>
</webscript>

file.post.json.ftl will be changed, it imports the action.lib.ftl to create a standard results response json format. But I will combine the import. Its contents are the following:

<#macro resultsJSON results>
<#escape x as jsonUtils.encodeJSONString(x)>
{
"totalResults": ${results?size},
"overallSuccess": ${overallSuccess?string},
"successCount": ${successCount},
"failureCount": ${failureCount},
"results":
[
   <#list results as r>
   {
      <#list r?keys as key>
         <#assign value = r[key]>
         <#if value?is_number || value?is_boolean>
      "${key}": ${value?string}<#if key_has_next>,</#if>
         <#else>
      "${key}": "${value}"<#if key_has_next>,</#if>
         </#if>
         </#list>
   }<#if r_has_next>,</#if>
   </#list>
]
}
</#escape>
</#macro>
<@resultsJSON results=results />

file.post.json.js needs to be modified to handle a file instead of a folder.

The main changes I will make to this script:

get a 'content' field from the json request object from the create-content form that we added previously.
```
 if (!json.isNull("content"))
{
content = json.get("content");
}
```
Rename variables folderName, folderDescription, folderTitle, folderPath to fileName, fileDescription, fileTitle, fileDescription and filePath respectively.

Create a file node instead of a folder node

var fileNode = parentNode.createFile(fileName);

set the content on the newly created fileNode variable arfter the fileNode.save(); method

      fileNode.save();
// Add uifacets aspect for the web client
fileNode.content = content;

Change messaging to reflect saving a file, not a folder.

The completed file.post.json.js looks like this:

/**
* Document List Component: action
*
* For a single-asset action, template paramters address the asset.
* For multi-asset actions, template parameters address the source or destination node,
* and a JSON body addresses the assets involved in the action.
* (note: HTTP DELETE methods must use URI)
*
* @param uri {string} site/{siteId}/{containerId}/{filepath} : full path to file or folder name involved in the action
* @param uri {string} node/{store_type}/{store_id}/{id}/{filepath} : full path to file or folder name involved in the action
*/

/**
* Main script entry point
* @method main
*/
function main()
{
// Params object contains commonly-used arguments
var params = {};
var files, rootNode;

if (url.templateArgs.store_type != undefined)
{
   params = getNodeRefInputParams();
}
else if (url.templateArgs.site != undefined)
{
   params = getSiteInputParams();
}
if (typeof params == "string")
{
   status.setCode(status.STATUS_BAD_REQUEST, params);
   return;
}

// Resolve path if available
var path = url.templateArgs.path;
// Path might be null for the root folder
if (!path)
{
   path = "";
}
// Remove any leading or trailing "/" from the path
// Fix-up parent path to have no leading or trailing slashes
if (path.length > 0)
{
   var aPaths = path.split("/");
   while (aPaths[0] === "")
   {
      aPaths.shift();
   }
   while (aPaths[aPaths.length-1] === "")
   {
      aPaths.pop();
   }
   path = aPaths.join("/");
}
params.path = path;

// Multiple input files in the JSON body?
files = getMultipleInputValues("nodeRefs");
if (typeof files != "string")
{
   params.files = files;
}

// Check runAction function is provided the action's webscript
if (typeof runAction != "function")
{
   status.setCode(status.STATUS_BAD_REQUEST, "Action webscript must provide runAction() function.");
   return;
}

// Actually run the action
var results = runAction(params);
if ((results !== null) && (results !== undefined))
{
   if (typeof results == "string")
   {
      status.setCode(status.STATUS_INTERNAL_SERVER_ERROR, results);
   }
   else if (typeof results.status == "object")
   {
      // Status fields have been manually set
      status.redirect = true;
      for (var s in results.status)
      {
         status[s] = results.status[s];
      }
   }
   else
   {
      /**
       * NOTE: Webscripts run within one transaction only.
       * If a single operation fails, the transaction is marked for rollback and all
       * previous (successful) operations are also therefore rolled back.
       * We therefore need to scan the results for a failed operation and mark the entire
       * set of operations as failed.
       */
      var overallSuccess = true;
      var successCount = 0;
      var failureCount = 0;
      for (var i = 0, j = results.length; i < j; i++)
      {
         overallSuccess = overallSuccess && results[i].success;
         results[i].success ? ++successCount : ++failureCount;
      }
      model.overallSuccess = overallSuccess;
      model.successCount = successCount;
      model.failureCount = failureCount;
      model.results = results;
   }
}
}


/**
* Get and check existence of mandatory input parameters (Site-based)
*
* @method getSiteInputParams
* @return {object|string} object literal containing parameters value or string error
*/
function getSiteInputParams()
{
var params = {};
var error = null;
var template = url.template;

try
{
   var siteId, containerId, sideNode, rootNode;

   // Try to get the parameters from the URI
   siteId = url.templateArgs.site;
   containerId = url.templateArgs.container;

   // SiteId
   if (template.indexOf("{site}") != -1)
   {
       if ((siteId === null) || (siteId.length === 0))
       {
           return "'site' parameter is missing.";
       }

      // Find the site
      siteNode = siteService.getSite(siteId);
      if (siteNode === null)
      {
           return "Site '" + siteId + "' not found.";
      }

      // ContainerId
      if (template.indexOf("{container}") != -1)
      {
          if ((containerId === null) || (containerId.length === 0))
          {
              return "'container' parameter is missing.";
          }

         // Find the component container
         var rootNode = siteNode.getContainer(containerId);
         if (rootNode === null)
         {
           rootNode = siteNode.createContainer(containerId);
           if (rootNode === null)
           {
                  return "Component container '" + containerId + "' not found in '" + siteId + "'.";
              }
         }
      }

      // Populate the return object
      params =
      {
          usingNodeRef: false,
          siteId: siteId,
          containerId: containerId,
          siteNode: siteNode,
          rootNode: rootNode
      }
   }
}
catch(e)
{
   error = e.toString();
}

 // Return the params object, or the error string if it was set
 return (error !== null ? error : params);
}

/**
* Get and check existence of mandatory input parameters (nodeRef-based)
*
* @method getNodeRefInputParams
* @return {object|string} object literal containing parameters value or string error
*/
function getNodeRefInputParams()
{
var params = {};
var error = null;

try
{
   // First try to get the parameters from the URI
   var storeType = url.templateArgs.store_type;
   var storeId = url.templateArgs.store_id;
   var id = url.templateArgs.id;

   var nodeRef = storeType + "://" + storeId + "/" + id;
   var rootNode = null;

   if (nodeRef == "alfresco://company/home")
   {
      rootNode = companyhome;
   }
   else if (nodeRef == "alfresco://user/home")
   {
      rootNode = userhome;
   }
   else
   {
      rootNode = search.findNode(nodeRef);

       if (rootNode === null)
       {
           return "'" + nodeRef  + "' is not a valid nodeRef.";
       }
    }

   // Populate the return object
   params =
   {
      usingNodeRef: true,
      nodeRef: nodeRef,
      rootNode: rootNode
   }
}
catch(e)
{
   error = e.toString();
}

 // Return the params object, or the error string if it was set
 return (error !== null ? error : params);
}

/**
* Get multiple input values
*
* @method getMultipleInputValues
* @return {array|string} Array containing multiple values, or string error
*/
function getMultipleInputValues(param)
{
var values = [];
var error = null;

try
{
   // Was a JSON parameter list supplied?
   if (typeof json == "object")
   {
      if (!json.isNull(param))
      {
         var jsonValues = json.get(param);
         // Convert from JSONArray to JavaScript array
         for (var i = 0, j = jsonValues.length(); i < j; i++)
         {
            values.push(jsonValues.get(i));
         }
      }
   }
}
catch(e)
{
   error = e.toString();
}

 // Return the values array, or the error string if it was set
 return (error !== null ? error : values);
}


/**
* Obtain the asset node for the given rootNode and filepath
*
* @method getAssetNode
* @param p_rootNode {object} valid repository node
* @param p_assetPath {string} rootNode-relative path to asset
* @return {object|string} valid repository node or string error
*/
function getAssetNode(p_rootNode, p_assetPath)
{
var assetNode = p_rootNode;
var error = null;

try
{
   if (p_assetPath && (p_assetPath.length > 0))
   {
      assetNode = assetNode.childByNamePath(p_assetPath);
   }

   if (assetNode === null)
   {
      return "Asset '" + p_assetPath + " not found.";
   }
}
catch(e)
{
     error = e.toString();
}

 // Return the node object, or the error string if it was set
 return (error !== null ? error : assetNode);
}

/**
* Create file action
* @method POST
* @param uri {string} /{siteId}/{containerId}/{filepath}
* @param json.name {string} New file name
* @param json.title {string} Title metadata
* @param json.description {string} Description metadata
* @param json.content {string} Content of file
*/

/**
* Entrypoint required by action.lib.js
*
* @method runAction
* @param p_params {object} common parameters
* @return {object|null} object representation of action result
*/
function runAction(p_params)
{
var results;

try
{
// Mandatory: json.name
if (json.isNull("name"))
{
 status.setCode(status.STATUS_BAD_REQUEST, "File name is a mandatory parameter.");
 return;
}
var fileName = json.get("name");

var parentPath = p_params.path;
var filePath = parentPath + "/" + fileName;

// Check file doesn't already exist
var existsNode = getAssetNode(p_params.rootNode, filePath);
if (typeof existsNode == "object")
{
 status.setCode(status.STATUS_BAD_REQUEST, "File '" + filePath + "' already exists.");
 return;
}

// Check parent exists
var parentNode = getAssetNode(p_params.rootNode, parentPath);
if (typeof parentNode == "string")
{
 status.setCode(status.STATUS_NOT_FOUND, "Parent folder '" + parentPath + "' not found.");
 return;
}

// Title and description
var fileTitle = "";
var fileDescription = "";
if (!json.isNull("title"))
{
 fileTitle = json.get("title");
}
if (!json.isNull("description"))
{
 fileDescription = json.get("description");
}
if (!json.isNull("content"))
{
 content = json.get("content");
}
// Create the folder and apply metadata
var fileNode = parentNode.createFile(fileName);
// Always add title & description, default icon
fileNode.properties["cm:title"] = fileTitle;
fileNode.properties["cm:description"] = fileDescription.substr(0, 100);
fileNode.properties["app:icon"] = "space-icon-default";
fileNode.save();
// Add uifacets aspect for the web client
fileNode.content = content;
fileNode.addAspect("app:uifacets");

// Construct the result object
results = [
{
 id: filePath,
 name: fileName,
 parentPath: parentPath,
 nodeRef: fileNode.nodeRef.toString(),
 action: "createFile",
 success: true
}];
}
catch(e)
{
status.setCode(status.STATUS_INTERNAL_SERVER_ERROR, e.toString());
return;
}

return results;
}

/* Bootstrap action script */
main();

This service uses the action.lib.js and action.lib.ftl libraries to simplify coding of similar functions, including: checkin, checkout, cancel-checkout, copy-to, move-to, file or folder delete and others. The action.lib.js is included in the folder.post.json.js script and provides a main() entry point to do common setup, clean up and host shared functions. The main entry point calls the runAction() function defined in the specific action script 'folder.post.json.js', effectively implementing a strategy pattern.

Step 7 - upload, build and test
Log into the alfresco server as admin. Navigate to Company Home > Data Dictionary > Web Scripts > org > alfresco

Create a new directory 'doclib' and copy the three files in to this directory: 'file.post.desc.xml', 'file.post.json.ftl', and 'file.post.json.js'.
Navigate to http://localhost:8080/alfresco/service/index and select 'refresh webscripts' button.

To view the new service, use the url http://localhost:8080/alfresco/service/index/uri/slingshot/doclib/action/file/site/%7Bsite%7D/%7Bcontainer%7D which should show the service correctly added.

Step 8 - alter 'New Content' button action to invoke new service
Now we have to use this new service we have created when we press the 'new content' button orbitz-toolbar.js onNewContent action line to read:

         var actionUrl = YAHOO.lang.substitute(Alfresco.constants.PROXY_URI + "slingshot/doclib/action/file/site/{site}/{container}/{path}",

this will call our new slingshot service to create a file, which in turn will call the new remote api service we added to alfresco.

Step 9 - deploy and test
Now, you should be able to press 'New Content' in share Document Library and create a new content item.

Extending Share 1 - Creating a Share extension project

2008-12-04T18:08:00.001-08:00

This post builds on the Learning Surf 1-6 blog entries (titled Learning Surf 1-6) to build a project to extend Alfresco's Share with custom capabilities. My previous blog posts walked through the Surf framework by creating a new button 'New Content' added to the 'Document Library' section of Share which allows content to be created and edited in-line in a popup form.

To recap the steps in the 'Learning Surf' posts:

Created a new ui webscript '/components/documentlibrary/create-content' that renders a form to capture the new content's name, title, description and contents
Augmented the document library's toolbar component with a 'New Content' button which opens the new create-content form component in a light box / modal dialog using the SimpleDialog library mechanism (similar to the 'New Folder' button)
Added a webscript service (POST /slingshot/actions/file) to the remote API to save the new content in the content repository by creating a new content item and adding it to the curernt path.

The code we wrote previously extended the Share (Slingshot project) and Alfresco (via the Remote API project) by directly coding in the code base of those projects. This is not an acceptable way to extend these products if not intending to become part of the main build. What is needed are two projects that are independent from the main code base and can add the desired functionality to the Share web client and the remote API on the content repository. The new webscript service previously added in the Remote API project will be created as an AMP module based project following the SDK Basic AMP project standard. I will describe this process in the next blog post. In this post, I will describe the steps to create a Share extension project. The approach and structure structure is my own. I am not sure this is the best approach to extend Share, but it does work. I am hoping to improve on this approach in the future (with your help of course).

NOTE: the complete sourceocde for this project can be downloaded from here.

Step 1 - Create a basic project structure

This project is created with Eclipse 'new java project' wizard, named 'deals-share-extension'. I created the following source folders (via File>New>Source Folder):

source/java - containing any java code (so far, none)
config/orbitz/site-webscripts - containing custom components (i.e. '/components/documentlibrary/create-content')
config/orbitz/templates - containing custom templates (so far, none)
config/alfresco/site-webscripts - containing override webscripts extending or replacing existing Share webscripts
config/alfresco/web-extension - contains extension spring bean and surf configurations to extend share (i.e. 'custom-slingshot-application-context.xml')
source/web containing any custom javascript, images and css

Also, the following was added to the project:

lib folder containing junit.jar for anticipated unit tests (more on these in the future)
build.xml ant build script used to build the project (described in the next step)
build.properties file containing configurable parameters for the build script (also described in the next step)

Created during the project build are the 'build/classes' folder containing java source and config files and the 'dist' folder containing the packaged jar file.

Step 2 - Create an Ant build.xml

The build script (see next step) will create a jar (named 'deals-share-ext.jar') containing any java code and any webscripts in the config/orbitz path, and deploy it to the WEB-INF/lib directory of the expanded Share war. In addition, the build script will copy the code in config/alfresco to the WEB-INF/classes/alfresco directory of the expanded Share war adding to or overwriting any existing Share components. Finally, source/web is copied to the Share root to add the custom Javascript, css and images used by the new components.

The build.xml ant script contains the following targets:

init - initializes build properties
incremental - incrementally builds the project (depends on package)
build - (default) cleans and builds the project (depends on clean and incremental)
clean - removes the 'build' and 'dist' directories and files created during compile and package
compile - compiles java code to build/classes and copies files required for the classpath into compiled classes folder and copies the deployable web assets to the build folder
package - creates a jar file in the dist folder from files in build/classes
deploy - copies jar to expanded share project war WEB-INF/lib, config files in build/classes 'alfresco' to WEB-INF/classes and web assets in source/web to the share root
test - runs unit tests

Here is the complete source for build.xml

<project name="deals-share-extension"
 default="build" >

<target name="init" description="initialize build parameters">
<property file="${basedir}/build.properties" />

<path id="classpath.unit.test">

<pathelement location="${dir.name.classes}" />
    <pathelement location="${dir.junit.lib}/junit.jar"/>
</path>
</target>


<target name="incremental" description="incremental build, no clean"
   depends="package" />

<target name="build" description="builds entire project from clean"
   depends="clean, incremental" />

<target name="clean">
<delete dir="${dir.name.build}" verbose="true" includeemptydirs="true"/>
</target>

<target name="compile"
   depends="init">
<mkdir dir="${dir.name.build}/${dir.name.classes}" />
<javac destdir="${dir.name.build}/${dir.name.classes}" fork="true"
   memoryMaximumSize="${mem.size.max}" deprecation="${javac.deprecation}"
   debug="${javac.debug}"  target="${javac.target}" source="${javac.source}" encoding="${javac.encoding}"
   excludes="@{compileExcludes}" >
<src path="${dir.name.source}/${dir.name.java}" />
<classpath refid="classpath.compile" />

</javac>

<copy todir="${dir.name.build}/${dir.name.classes}">
<fileset dir="${dir.name.source}/${dir.name.java}">
  <patternset>
     <exclude name="**/*.java" />
     <exclude name="log4j.properties" />
  </patternset>
</fileset>
</copy>
<copy todir="${dir.name.build}/${dir.name.classes}">
<fileset dir="${dir.name.config}">
  <patternset>
     <exclude name="**/*.java" />
     <exclude name="log4j.properties" />
  </patternset>
</fileset>
</copy>
<copy todir="${dir.name.build}">
<fileset dir="${dir.name.source}/${dir.name.web}">
  <patternset>
     <exclude name="**/*.java" />
     <exclude name="log4j.properties" />
  </patternset>
</fileset>
</copy>
</target>

<target name="package" description="Creates jar file"
   depends="compile">
<mkdir dir="${dir.name.dist}" />
<jar jarfile="${dir.name.dist}/${file.name.jar}"
   basedir="${dir.name.build}/${dir.name.classes}" />
</target>

<target name="deploy" description="copy into share expanded share deployment"
   depends="package">
<copy todir="${env.APP_TOMCAT_HOME}/webapps/share/WEB-INF/lib">
<fileset dir="${dir.name.dist}">
  <patternset>
     <include name="**/*.jar" />
  </patternset>
</fileset>
</copy>

<copy todir="${env.APP_TOMCAT_HOME}/webapps/share/WEB-INF/classes">
<fileset dir="${dir.name.config}">
  <patternset>
       <include name="alfresco/**/*"/>

  </patternset>
</fileset>
</copy>

<copy todir="${env.APP_TOMCAT_HOME}/webapps/share">
<fileset dir="${dir.name.source}/${dir.name.web}">
  <patternset>
      <include name="**/*.js"/>
      <include name="**/*.css"/>

  </patternset>
</fileset>
</copy>

</target>

<target name="test" description="run tests and generate results"
   depends="compile">
<mkdir dir="${dir.name.build}/${dir.name.tes t.results}" />
<junit printsummary="yes" fork="yes" maxmemory="${mem.size.max}" haltonfailure="yes" dir="@{projectdir}">
<jvmarg value="-server"/>
<classpath refid="classpath.unit.test" />
<formatter type="xml" />
<batchtest todir="${dir.name.build}/${dir.name.test.results}">
  <fileset dir="${dir.name.source}/${dir.name.java}">
     <patternset includes="**/*Tests.java" />
  </fileset>
</batchtest>
</junit>
</target>

</project>

Supporting the build.xml file is the build.properties file:

#directory names

dir.name.assemble=assemble
dir.name.bin=bin
dir.name.build=build
dir.name.classes=classes
dir.name.config=config
dir.name.source=source
dir.name.devenv=devenv
dir.name.dist=dist
dir.name.distro=distro
dir.name.docs=docs
dir.name.generated=generated
dir.name.java=java
dir.name.lib=lib
dir.name.test.results=
dir.name.test.results=test-results
dir.name.test.resources=test-resources
dir.name.web=web

file.name.jar=deals-share-ext.jar

dir.junit.lib=lib

Step 3 - Create an extension spring bean configuration

Within the slingshot project in /config/alfresco there is a spring context file 'slingshot-application-context.xml' which among other things defines search paths for web scripts and surf model objects. These spring beans are referred to from the 'web-framework-config-application.xml' defining the beans for finding the model types in surf. What is needed is to add a search path to identify the custom webscripts and model objects we will extend in share. One mechanism to do this is to create a new file under /config/alfresco/web-extension called 'custom-slingshot-application-context.xml' with search paths to find custom components, templates and web scripts.

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>

<beans>

<bean id="webframework.searchpath" class="org.alfresco.web.scripts.SearchPath">
<property name="searchPath">
<list>
<ref bean="dealscontent.store.webscripts" />
<ref bean="webframework.remotestore.webscripts" />
<ref bean="webframework.store.webscripts.custom" />
<ref bean="webframework.store.webscripts" />
<ref bean="webscripts.store" />
</list>
</property>
</bean>

<bean id="dealscontent.store.webscripts" class="org.alfresco.web.scripts.ClassPathStore">
<property name="mustExist"><value>true</value></property>
<property name="classPath"><value>orbitz/site-webscripts</value></property>
</bean>

</beans>

the 'webframework.searchpath' bean overrides a bean defined in the webscript project used to define search paths for webscript processors. Added to the search path list is a reference to a custom 'dealscontent.store.webscripts' bean which defines the specific folder to search in the classpath for our new webscripts as 'orbitz/site-webscripts'.

In the next blog entry, we will write code to add a 'new content' button to the document library's toolbar similar to the code written in the 'learning surf' blog entries.

Learning Surf 6 - Creating a webscript service

2008-12-01T12:54:00.000-08:00

In the previous blog, we created a simple dialog to open a content creation form from Share's Document Library page toolbar when we click on our added 'New Content' button. This form invokes the POST for 'slingshot/doclib/action/folder/site/{site}/{container}/{path}' service implemented as part of the RESTful Remote API of Afresco 3.0. As we left it, the 'New Content' button simply creates a folder doing the same job as the 'New Folder' button.

Step 1 - create a new service

Now we need to create a webscript service to use instead of the slingshot/doclib/action/folder service. for this blog, I will extend the action services to implement the following url pattern:

POST slingshot/doclib/action/file/site/{site}/{container}/{path}

To do this, we will add a new webscript service to the remote api project. Later, we can separate this to our own amp module. As a starting point, we can copy the folder.post.* files to create file.post.* files in Remote API/config/alfresco/templates/webscripts/org/alfresco/slingshot/documentlibrary/action directory. This creates the following files:

file.post.desc.xml
file.post.json.ftl
file.post.json.js

Now we can modify these files to do the work of creating a file instead of a folder. for 'file.post.desc.xml' we modify the url pattern to the following:

<webscript>
<shortname>folder</shortname>
<description>Document List Action - Create folder</description>
<url>/slingshot/doclib/action/file/site/{site}/{container}</url>
<url>/slingshot/doclib/action/file/site/{site}/{container}/{path}</url>
<format default="json">argument</format>
<authentication>user</authentication>
<transaction>required</transaction>
</webscript>

file.post.json.ftl file does not need to be changed, it imports the action.lib.ftl to create a standard results response json format.
file.post.json.js needs to be modified to handle a file instead of a folder.

The main changes I will make to this script:

get a 'content' field from the json request object from the create-content form that we added previously.
```
 if (!json.isNull("content"))
{
  content = json.get("content");
}
```
Rename variables folderName, folderDescription, folderTitle, folderPath to fileName, fileDescription, fileTitle, fileDescription and filePath respectively.

Create a file node instead of a folder node

var fileNode = parentNode.createFile(fileName);

set the content on the newly created fileNode variable arfter the fileNode.save(); method

      fileNode.save();
 // Add uifacets aspect for the web client
 fileNode.content = content;

Change messaging to reflect saving a file, not a folder.

The completed file.post.json.js looks like this:

<import resource="classpath:/alfresco/templates/webscripts/org/alfresco/slingshot/documentlibrary/action/action.lib.js">

/**
* Create file action
* @method POST
* @param uri {string} /{siteId}/{containerId}/{filepath}
* @param json.name {string} New file name
* @param json.title {string} Title metadata
* @param json.description {string} Description metadata
* @param json.content {string} Content of file
*/

/**
* Entrypoint required by action.lib.js
*
* @method runAction
* @param p_params {object} common parameters
* @return {object|null} object representation of action result
*/
function runAction(p_params)
{
var results;

try
{
 // Mandatory: json.name
 if (json.isNull("name"))
 {
    status.setCode(status.STATUS_BAD_REQUEST, "File name is a mandatory parameter.");
    return;
 }
 var fileName = json.get("name");

 var parentPath = p_params.path;
 var filePath = parentPath + "/" + fileName;

 // Check file doesn't already exist
 var existsNode = getAssetNode(p_params.rootNode, filePath);
 if (typeof existsNode == "object")
 {
    status.setCode(status.STATUS_BAD_REQUEST, "File '" + filePath + "' already exists.");
    return;
 }

 // Check parent exists
 var parentNode = getAssetNode(p_params.rootNode, parentPath);
 if (typeof parentNode == "string")
 {
    status.setCode(status.STATUS_NOT_FOUND, "Parent folder '" + parentPath + "' not found.");
    return;
 }

 // Title and description
 var fileTitle = "";
 var fileDescription = "";
 if (!json.isNull("title"))
 {
    fileTitle = json.get("title");
 }
 if (!json.isNull("description"))
 {
    fileDescription = json.get("description");
 }
 if (!json.isNull("content"))
 {
    content = json.get("content");
 }
 // Create the folder and apply metadata
 var fileNode = parentNode.createFile(fileName);
 // Always add title & description, default icon
 fileNode.properties["cm:title"] = fileTitle;
 fileNode.properties["cm:description"] = fileDescription.substr(0, 100);
 fileNode.properties["app:icon"] = "space-icon-default";
 fileNode.save();
 // Add uifacets aspect for the web client
 fileNode.content = content;
 fileNode.addAspect("app:uifacets");

 // Construct the result object
 results = [
 {
    id: filePath,
    name: fileName,
    parentPath: parentPath,
    nodeRef: fileNode.nodeRef.toString(),
    action: "createFile",
    success: true
 }];
}
catch(e)
{
   status.setCode(status.STATUS_INTERNAL_SERVER_ERROR, e.toString());
   return;
}

return results;
}

/* Bootstrap action script */
main();

ant build-tomcat

to make sure all my changes are built. This will deploy share.war and alfresco.war.
Start up tomcat.
To view the new service, use the url http://localhost:8081/alfresco/service/index/uri/slingshot/doclib/action/file/site/%7Bsite%7D/%7Bcontainer%7D which should show the service correctly added.

Step 4 - alter 'New Content' button action to invoke new service
Now we have to use this new service we have created when we press the 'new content' button we added in the previous post. Change the toolbar.js onNewContent action line to read:

         var actionUrl = YAHOO.lang.substitute(Alfresco.constants.PROXY_URI + "slingshot/doclib/action/file/site/{site}/{container}/{path}",

this will call our new slingshot service to create a file, which in turn will call the new remote api service we added to alfresco.

Step 5 - deploy and test
Now, you should be able to press 'New Content' in share Document Library and create a new content item.

Learning Surf 5 - Opening a content editor

2008-10-31T17:50:00.000-07:00

In this blog entry, I will build on the tutorial in my last blog entry where I added a new button to the toolbar of the Document Library section of the Share application. When we click on this 'create' button, a dialog box should open (light box) with a form to create a new content item. When we press 'ok', a new content item should be created with the given name in the current folder.

Step 1 - Create a form webscript

My model example will be the document library 'create folder' web script in Share. This ui webscript contains a form to create a new folder. It is opened from clicking the 'New Folder' button on the Document Library section of Share. This function opens a form in a popup dialog like I want.

To create the web script ui form template, I will start by copying the create-folder.get.*.* webscript files from $SLINGSHOT_SRC_DIR/config/alfresco/site-webscripts/org/alfresco/modules/documentlibrary to $SLINGSHOT_SRC_DIR/config/alfresco/site-webscripts/org/alfresco/components/documentlibrary and rename them to 'create-content.get.*.*'. This creates three files:

create-content.get.desc.xml,
create-content.get.html.ftl
create-content.get.properties

Inside of create-content.get.desc.xml, we need to change the URI of the webscript to /components/documentlibrary/create-content and its description. create-content.get.desc.xml should now read:

<webscript>
<shortname>content-createform</shortname>
<description>Displays a form to create html content</description>
<url>/components/documentlibrary/create-content</url>
</webscript>

Now we have a new ui webscript component 'create-content' that we can call within a dialog that will render a form. The form contains labels for creating a folder so we can modify the create-content.get.properties with custom messages for this dialog:

## Titles
title=Create Content
header=New Content Details

## Labels
label.name=Name
label.title=Title
label.description=Description

Step 2 - Registering the new Web Script

Since we have created a new ui web script at /components/documentlibrary/create-content we need to register it. We simply go to 'http://localhost:8080/share/service/index' and click the 'refresh web scripts' button. This will scan for new web scripts. See the web scripts hello world quick start wiki page for more details. This page also shows a count of the total web scripts registered. We should see this increase by one. To verify the webscript is registered, we can click 'Browse by Web Script UI' and find our new component at '/components/documentlibrary/create-content'. Clicking on our uri, we see a details page describing the component. This information is taken from the 'create-content.get.desc.xml' file.

To test our new component, we can enter its url: 'http://localhost:8080/share/service/components/documentlibrary/create-content'. This will error in the web script because it requires the htmlid parameter to exist. If we enter 'http://localhost:8080/share/service/components/documentlibrary/create-content?htmlid' this will satisfy the requirement and the form should render.

Step 3 - Opening the form in a dialog

In my previous blog entry, we added a button to the toolbar of the Document Library named 'Create' which currently opens a popup message saying feature is not implemented. We will modify the 'Create' button behavior on Document Library toolbar to open this new create-content form in a dialog. In the previous blog, we created the onFileCreate action handler function of $SLINGSHOT_SRC_DIR/source/web/components/documentlibrary/toolbar.js to open a simple popup indicating the feature was not created yet. We will change this behavior by looking at the 'onFolderCreate' function as an example of opening a template in a dialog.

We will copy the body of DLTB_onFolderCreate into the body of DLTB_onFileCreate and change the line

templateUrl: Alfresco.constants.URL_SERVICECONTEXT + "modules/documentlibrary/create-folder",

To read

templateUrl: Alfresco.constants.URL_SERVICECONTEXT + "components/documentlibrary/create-content",

Where the final function should read:

  onFileCreate: function DLTB_onFileCreate(e, p_obj)
{
var actionUrl = YAHOO.lang.substitute(Alfresco.constants.PROXY_URI + "slingshot/doclib/action/folder/site/{site}/{container}/{path}",
{
site: this.options.siteId,
container: this.options.containerId,
path: this.currentPath
});

var doSetupFormsValidation = function DLTB_oNF_doSetupFormsValidation(p_form)
{
// Validation
// Name: mandatory value
p_form.addValidation(this.id + "-createFolder-name", Alfresco.forms.validation.mandatory, null, "keyup");
// Name: valid filename
p_form.addValidation(this.id + "-createFolder-name", Alfresco.forms.validation.nodeName, null, "keyup");
p_form.setShowSubmitStateDynamically(true, false);
};

if (!this.modules.createFolder)
{
this.modules.createFolder = new Alfresco.module.SimpleDialog(this.id + "-createFolder").setOptions(
{
width: "30em",
//               templateUrl: Alfresco.constants.URL_SERVICECONTEXT + "modules/documentlibrary/create-folder",
templateUrl: Alfresco.constants.URL_SERVICECONTEXT + "components/documentlibrary/create-content",
actionUrl: actionUrl,
doSetupFormsValidation:
{
fn: doSetupFormsValidation,
scope: this
},
firstFocus: this.id + "-createFolder-name",
onSuccess:
{
fn: function DLTB_onNewFolder_callback(response)
{
var folder = response.json.results[0];
YAHOO.Bubbling.fire("folderCreated",
{
name: folder.name,
parentPath: folder.parentPath,
nodeRef: folder.nodeRef
});
Alfresco.util.PopupManager.displayMessage(
{
text: this._msg("message.new-folder.success", folder.name)
});
},
scope: this
}
});
}
else
{
this.modules.createFolder.setOptions(
{
actionUrl: actionUrl,
clearForm: true
});
}
this.modules.createFolder.show();
},

A lot more needs to be done. But at this point we should test our code.

To build and deploy, I use ant 'incremental-slinghot-tomcat' which should create the share.war and deploy to $APP_TOMCAT_HOME.

Clicking on the 'Create' button of Document Library, this is what we should now see:

Currently, this web script dialog should create a folder, not a content item that we want. We will modify this in the next step.

Step 4 - Modifying the Create Content dialog to accept content

In the dialog we are creating, some things to notice about the construction of the Alfresco.SimpleDialog object in our 'onCreateContent action handler function:

The 'actionURI' defined at the beginning of the function will be used to invoke the RESTful service on the content repository. Currently this is pointing to the create folder function, but we will change this to create new content.
There are two validators added 'manditory' and 'nodeName' to the name field of the createContent form. We will keep this behavior.

There is actually no 'content' entered for the new content. In creating a new folder, only the metadata 'name', 'title' and 'description' are needed. To create new content, we would also like to add the actual content. We will do this initially as plain text. Later, we will try to use a WYSIWYG editor.

To add the 'content' section, we will modify 'create-content.get.html.ftl' and add the following section:

         <div class="yui-gd">
        <div class="yui-u first"><label for="${args.htmlid}-content">${msg("label.content")}:</label></div>
        <div class="yui-u"><textarea id="${args.htmlid}-content" name="content" rows="3" cols="20" tabindex="3" ></textarea></div>
     </div>

Here we have added a new div section to contain a textarea html form element with the name '-content'. This text area will allow us to enter plain text to supply content to our new document. Later we will modify this to use the yui html editor. The complete 'create-content.get.html.ftl' template should look like the following:

<div id="${args.htmlid}-dialog" class="create-folder">
<div class="hd">${msg("title")}</div>
<div class="bd">
 <form id="${args.htmlid}-form" action="" method="post">
    <div class="yui-g">
       <h2>${msg("header")}:</h2>
    </div>
    <div class="yui-gd">
       <div class="yui-u first"><label for="${args.htmlid}-name">${msg("label.name")}:</label></div>
       <div class="yui-u"><input id="${args.htmlid}-name" type="text" name="name" tabindex="1" />&nbsp;*</div>
    </div>
    <div class="yui-gd">
       <div class="yui-u first"><label for="${args.htmlid}-title">${msg("label.title")}:</label></div>
       <div class="yui-u"><input id="${args.htmlid}-title" type="text" name="title" tabindex="2" /></div>
    </div>
    <div class="yui-gd">
       <div class="yui-u first"><label for="${args.htmlid}-description">${msg("label.description")}:</label></div>
       <div class="yui-u"><textarea id="${args.htmlid}-description" name="description" rows="3" cols="20" tabindex="3" ></textarea></div>
    </div>
    <div class="yui-gd">
       <div class="yui-u first"><label for="${args.htmlid}-content">${msg("label.content")}:</label></div>
       <div class="yui-u"><textarea id="${args.htmlid}-content" name="content" rows="3" cols="20" tabindex="3" ></textarea></div>
    </div>
    <div class="bdft">
       <input type="button" id="${args.htmlid}-ok" value="${msg("button.ok")}" tabindex="4" />
       <input type="button" id="${args.htmlid}-cancel" value="${msg("button.cancel")}" tabindex="5" />
    </div>
 </form>
</div>
</div>

You may also have noticed that we added a new label 'content', so we will have to update our create-content.get.properties file to include it.

label.content=content

Now that our form has the new '-content' field, we can extract content entered from it, and use it to pass to a remote webscript to create this content. To accomplish the creation of a new file, we need to create a new service. This will be the subject of my next blog entry.

Learning Surf 4 - Modifying Share documentLibrary with Create Content button

2008-10-30T11:19:00.000-07:00

This and the next blog entries will walk through the process of adding a new button to the documentLibrary section of Share which will allow the creation of new content using an in-line WYSIWYG editor.

This blog will add a 'Create' button to the toolbar of the Document Library module and open a popup when clicked showing a message 'feature not implemented yet'

Step 1 - mapping the terrain

As I have done in previous blog entries, I will draw a picture of the dependent files (xml, freemarker and javascript) that renders the relevant portion of the document library, and indicate what needs to be modified.

As shown before, the key files are:

'site-data/pages/documentLibrary.xml' page references 'documentLibrary.xml' template-instance
'site-data/template-instances/documentLibrary.xml' contains reference to 'org/alfresco/documentLibrary' template type
'templates/org/alfresco/documentLibrary.ftl' contains the structure of the page with regions containing components including the 'toolbar' region
'site-data/components/template.toolbar.documentLibrary.xml' defines the component to fit in region 'toolbar' of template 'documentLibrary' refrencing a webscript ui component registered to the url '/components/documentlibrary/toolbar'
site-webscripts/org/alfresco/components/documentlibrary/toolbar.get.desc.xml' describes the ui webscript registered to the '/components/library/toolbar' url, it includes freemarker renderers 'toolbar.get.head.ftl' and 'toolbar.get.html.ftl'.
'toolbar.get.head.ftl' references toolbar.js and toolbar.css found in 'web/components/documentlibrary/' source folder.

Step 2 - Add the button to the template

The 'toolbar' component contains the space for the 'create' button I wish to add. Within the 'toolbar.get.html.ftl' I have added a couple of lines for the new button:

 <div class="new-folder hideable DocListTree"><button id="${args.htmlid}-newFolder-button" name="newFolder">${msg("button.new-folder")}</button></div>

<!-- Added by EEW 20081030 -->
<div class="separator hideable DocListTree">&nbsp;</div>
<div class="file-create hideable DocListTree"><button id="${args.htmlid}-fileCreate-button" name="fileCreate">${msg("button.create")}</button></div>
<!-- End Added -->

<div class="separator hideable DocListTree">&nbsp;</div>
<div class="file-upload hideable DocListTree"><button id="${args.htmlid}-fileUpload-button" name="fileUpload">${msg("button.upload")}</button></div>

Step 3 - Add Messages for the button

This code also changes the 'toolbar.get.properties' file adding the key/value 'button.create=Create',

Step 4 - Add CSS Entries and Images for the button

and the toolbar.css used to render the button:


/* added by EEW 20081030 */

.toolbar .file-create button
{
background: transparent url(images/create-16.png) no-repeat 12px 4px;
padding-left: 32px;
}
.toolbar .file-create .yui-button-disabled button
{
background-image: url(images/create-disabled-16.png);
}

/* done added */

As implied by the css above, I have also created two new images to appear with the button: create-16.png and create-disabled-16.png. For testing purposes, I simply copied edit-blog-16.png.

Step 5 - Add the Button as a YUI Button

In 'toolbar.js', I have added a line to instantiate the YUI button named in the toolbar template in the 'onReady' YUI event listener

   
   // added by EEW 20081030

   // File Create button: user needs  "create" access
   this.widgets.fileCreate = Alfresco.util.createYUIButton(this, "fileCreate-button", this.onFileCreate,
   {
      disabled: true,
      value: "create"
   });
   // done added

   // File Upload button: user needs  "create" access
   this.widgets.fileUpload = Alfresco.util.createYUIButton(this, "fileUpload-button", this.onFileUpload,
   {
      disabled: true,
      value: "create"
   });

In this code, we see that the YUI button ties the name 'fileCreate-button' (which is the id in the button tag defined in 'toolbar.get.html.ftl'), and the event name 'onFileCreate', which will fire when the button is clicked.

Step 6 - Add the Event Code

The event is also defined in toolbar.js:

      /**
 * File Create click handler
 *
 * @method onFileCreate
 * @param e {object} DomEvent
 * @param p_obj {object} Object passed back from addListener method
 */
onFileCreate: function DLTB_onFileCreate(e, p_obj)
{
/*
   var url = YAHOO.lang.substitute(Alfresco.constants.URL_CONTEXT + "page/site/{site}/blog-postedit?container={container}",
   {
      site: this.options.siteId,
      container: this.options.containerId
   });
   window.location = url;
   Event.preventDefault(e);
*/
   var notimpTitle = this._msg("title.notimp");
   var notimpMsg = this._msg("message.notimp", "Create Content");

   Alfresco.util.PopupManager.displayPrompt(
   {
      title: notimpTitle,
      text: Alfresco.util.decodeHTML(notimpMsg),
      noEscape: true,
      modal: true,
      buttons: [
      {
         text: this._msg("button.cancel"),
         handler: function DLTB_onActionDelete_cancel()
         {
            this.destroy();
         }
      }]
   });

},

This event handler will open a popup message for now showing that this feature is not yet implemented.

Step 7 - Add The Messages for the Popup Message Box

At this point I am only defining a placeholder for this event. In order to support the above popup, I have included the message keys to 'toolbar.get.properties':

## Added by EEW 20081031

button.create=Create
title.notimp=Not Implemented
message.notimp = Feature {0} is not implemented yet.

## Done Added

Step 8 - Build, Deploy and Test

To test, I use ant task 'incremental-slingshot-tomcat' to build and deploy my changes to tomat. As a remider, the ant task requires environment variables TOMCAT_HOME and APP_TOMCAT_HOME to be defined to the installed tomcat.

And you should see this:

Learning Surf 3 - More analysis of Slingshot (Share) - looking at Blog List

2008-10-29T11:16:00.000-07:00

Please see my previous blog entry for more detail on general concepts of Slingshot's configuration as a Surf platform application.

In the next blogs, I will attempt enhancing Share to add a 'create' button along side of the 'upload' button in the 'document Library' section which will open an in-place WYSIWYG editor to create html based content. In preparation for this, I will look at similar code implemented to post a blog entry.

In Share (Slingshot), creating or selecting a site from the dashboard 'sites' dashlet opens the site dashboard. The top navigation provides buttons to select 'Blog' to view and enter blog entries. Selecting 'blog' creates the URL:

http://localhost:8080/share/page/site/mc/blog-postlist

One of the difficulties in getting your head around working with Surf based web applications is understanding how everything is connected together. I will attempt to show how the bloglist page is rendered.

This diagram shows my map of the dependencies of the various xml, javascript and freemarker files that assemble the bloglist page.

Decomposing the url, we see the pattern /page/* which maps to the pageRendererServlet. Using the 'config/alfresco/web-framework-config-application.xml' which defines url patterns to find the /site/{site}/blog-postlist from the object model defined in xml files, found according to the search path for the types of components it is looking for (see previous blog).

'site-data/pages/blog-postlist.xml' defines a page model object for the page. It refers to a template instance blog-postlist.xml.

'site-data/template-instances/blog-postlist.xml' defines a template-instance model object which refers to the template-type found using org/alfresco/blog-postlist

'templates/org/alfresco/blog-postlist.ftl' is found as the search for template types assumes a freemarker template at the path defined if not explicitly defined see surf developer documentation. This template works in conjunction with component definitions to associate components with regions defined in the source template.

'site-data/components/template.postlist.blog-postlist.xml' provides component mapping to region 'postlist' in source id 'blog-postlist', mapping to a component found by url '/components/blog/postlist'

'site-webscripts/org/alfresco/components/blog/postlist.get.desc.xml' ui webscript is registered to the url pattern defined for the template and uses 'postlist.get.head.ftl' and 'postlist.get.html.ftl' as renderers.

'site-webscripts/org/alfresco/components/blog/postlist.get.head.ftl' links to the 'postlist.js' javascript.

'source/web/components/blog/postlist.js' among other things defines a yui button to create a blog post (createPost-button), which when pressed will call the onCreatePost action handler.

'site-webscripts/org/alfresco/components/blog/postlist.get.html.ftl' renders the Blog post list page, including the 'createPost-button' yui button. Clicking on this button calls the onCreatePost action handler defined in postlist.js' which will in tern compose the url

http://localhost:8080/share/page/site/mc/blog-postedit?container=blog

This page renders a WYSIWYG editor configured to allow creation of blog entries.

Learning Surf 2 - Examining slingshot configuration

2008-10-27T12:46:00.001-07:00

Examining slingshot configuration

You can see my previous blog entry for a background in getting started with surf.

The Surf platform is a web script based framework for developing web 2.0 based applications that can use the alfresco content repository. It relies on the technologies of xml, freemarker and javascript. It heavily leverages alfresco's freemarker templates and the javascript api, and the alfresco's web script technologies that define ui components or RESTful services.

Surf based applications can be developed without an Alfresco content repository access, but ones that use the content repository are developed and deployed as two war files, one for the web application built on surf (i.e. share.war), and one for the content repository it accesses (alfresco.war). These war files can be deployed within the same application container (i.e. tomcat) or different application containers on the same machine or different machines. The web application communicates with the content repository over RESTful services (essentially over http).

The share application is a surf framework application. The source tree stores share in a project called 'slingshot'. Slighshot depends on other projects in the source tree, including:

3rd Party
Core
Web Framework
Webscript Framework

Configurations of a surf application are contained in the following types of configurations:

war configuration files (web.xml)
alfresco configuration files (i.e. web-framework-config.xml and LOTS more)
spring bean configurations (i.e. slingshot-application-context.xml)
resource bundles (i.e. slingshot.properties)

This blog will look at the first three to understand how a surf application is configured.

To trace the configuration, we start with the war. Whithin the Slingshot application is a source folder which includes web/WEB-INF that contains the web.xml for the share.war.

looking at web.xml

A context-param section is included to define the contextConfigurationLocation for spring to find all of the spring beans that are needed to configure the surf application. These include:

classpath:alfresco/webscript-framework-application-context.xml
classpath:alfresco/web-framework-application-context.xml
classpath:alfresco/web-framework-model-context.xml
classpath:alfresco/slingshot-application-context.xml

This ties slingshot to depend on the Webscript Framework and the Web Framework projects.

A listener is defined with a springframework web context loader listener wihich loads the spring context form the class paths defined in the 'contextConfigurationLocation' context parameter.

Several servlets are defined

url-pattern	servlet name	servlet class
/logout	logoutServlet	org.alfresco.web.site.servlet.LogoutServlet
/login/*	loginServlet	org.alfresco.web.site.servlet.LoginServlet
/service/*	apiServlet	org.alfresco.web.scripts.servlet.WebScriptServlet(container=webframework.webscripts.container)
/proxy/*	proxyServlet	org.alfresco.web.scripts.servlet.EndPointProxyServlet
/page/, p/	pageRendererServlet	org.alfresco.web.site.servlet.DispatcherServlet
/s/*	uriTemplateServlet	org.alfresco.web.uri.UriTemplateServlet
/control/*	frameworkControlServlet	org.alfresco.web.site.servlet.FrameworkControlServlet

Finally, weblome file list includes:

index.jsp
index.html

looking at the web-framework-config alfresco configuration file

The configuration file defines

page-mapper
link-builder
file-system
format default
format print
format wap
persisters
model-type (object model) definitions

each model-type defines id, name, class, search path and default store for the following model types:

chrome
component
component-type
configuration
content-association
page
page-type
page-association
template-instance
template-type
theme

These model-type definitions define where to look for marshaled configurations for model objects of each type, whether to look on the remote store, local path or in the class path.

looking at spring bean application context files

Using spring explorer in Eclipse (Ganymede) allowed me to view spring bean configuration dependencies.

The slingshot-application-context.xml references beans defined in web-framework-application-context.xml and web-framework-model-context.xml.

The web framework beans reference beans defined in webscript-framework-application-context.xml.

slingshot-application-context.xml contains the following beans:

The 'webscript.resource' bean list resource bundles that contain messages to use. The other beans (i.e.'webframework.searchpath.chrome') tell surf where to look (i.e. search paths) for definitions of the different model components that surf needs to run. For instance, to know how 'chrome' is configured.

web-framework-application-context.xml contains the following beans:

Tracing through rendering the dashboard

To demonstrate the configuration, lets look at the beginning, rendering the dashboard. The share.war defines the welcome page 'index.jsp'. This jsp redirects to '/page/site-index'. As defined in web.xml, /page/* url pattern runs the 'pageRendererServlet'. This servlet looks for a model object named 'site-index'. The name 'site-index' is defined as a page model object found in the default remote store (as defined in web-framework-config.xml for the page model-type) in './site-data/pages'.

'site-index.xml' defines a page model object named 'site-index' which defines:

title = welcome
descrition = Landing page for users - will create user site dashboard
template-instances = site-index
authentication = user

The site-index page model object references a template instance named 'site-index' found also in the default store ( ./site-data/template-instance):

The template-instance refers to a template-type 'site-index' found in (site-data/template-types)

'site-index.xml' is a template-type model object and defines:

title = site index landing page template type
description = Site index landing page JSP Template Type
renderer = /site-index.jsp
renderer-type = jsp

Looking at '/site-index.jsp' as a jsp template renderer, we see scriptlet logic that follows:

If not already created the user dashboard, create the user's dashboard using the definition in presets (found in ./site-data/presets/presets.xml) for 'user-dashboard'.
Render the user dashboard.

In 'user-dashboard' preset, the 'components' section creates components and assigns to regions according to the template insance (dashboard-3-columns) defined in the 'pages' section.

The 'dashboard-3-columns.xml' template-instance definition defines

template-type = org/alfresco/dashboard.ftl.

'dashboard.ftl' imports alfresco-template.ftl and alfresco-layout.ftl and creates regions named 'component--' where the preset components are added.

The preset creates and places the following components into the dashboard template:
define title from (site-webscripts/org/alfresco/components/title/user-dashboard-title*)
define list of page components (dashlets) positioned at {column#}-{row#):

user-welcome at 1-1
user-calendar at 1-2
rssfeed at 2-1
alfresco-network at 2-2
my-activities at 2-3
cmisfeed at 3-4
my-profile at 3-1
my-sites at 3-2
my-tasks at 3-3

Each dashlet is defined by a ui web-script found in site-webscripts/orgb/alfrsco/components/dashlets/. See a description of alfresco's web-scripts technology for details on ui web scripts.

Learning Surf 1 - building from source

2008-10-20T10:19:00.001-07:00

My goal was to build the latest Alfresco from source, and begin to develop and extend it using Eclipse. I followed the instructions on: Alfresco's developer wiki . I followed the guidance of the Eclipse section to import all alfresco projects.

Unfortunately, between the first time I did this (early September) and the latest time (October 15), there was significant changes to the codebase that affected the Eclipse projects I imported earlier. I went through the pain of refreshing projects and rebuilding everything until I finally got everything to pass. It was probably better that i deleted these older projects and started with fresh imports. This is a large code base (over 500 meg compressed) so I warn you that this will take some time. Once the code base is built from source, I can follow along refreshing as needed.

Note, since I am developing on a Windows laptop (dont ask why), I used tortoise svn. This worked fairly well for me. I also got the subversion plug in for Eclipse. These two seem to work well with each other well for now.

My first step was to build the alfresco war. I had already created an alfresco database in MySQL as the wiki suggested. I also had tomcat 5.5 installed and Ant so the build was fairly painless.


ant build-tomcat

This created the alfresco.war and deployed it to TOMCAT_HOME. Make sure to set up the environment variables as described. TOMCAT_HOME will be where the alfresco.war will be deployed. APP_TOMCAT_HOME will be where share.war and alfwf.war will be deployed. These can be different or the same. Alfresco 3.0 is now truly service oriented and webapps can be developed (i.e. share.war) and deployed independently of the repository (alfresco.war). For development purposes, I set these to the same tomcat instance.

One problem my team ran into was that share.war refused to authenticate admin/admin. We later determined this was due to the fact that we were running tomcat on a different port than 8080 and there were several configuration files that needed to be changed to reflect this:


$ALF_HOME/tomcat/webapps/alfresco/wsdl/administration-service.wsdl
$ALF_HOME/tomcat/webapps/alfresco/wsdl/dictionary-service.wsdl
$ALF_HOME/tomcat/webapps/alfresco/wsdl/content-service.wsdl
$ALF_HOME/tomcat/webapps/alfresco/wsdl/authoring-service.wsdl
$ALF_HOME/tomcat/webapps/alfresco/wsdl/access-control-service.wsdl
$ALF_HOME/tomcat/webapps/alfresco/wsdl/action-service.wsdl
$ALF_HOME/tomcat/webapps/alfresco/wsdl/authentication-service.wsdl
$ALF_HOME/tomcat/webapps/alfresco/wsdl/repository-service.wsdl
$ALF_HOME/tomcat/webapps/alfresco/wsdl/classification-service.wsdl
$ALF_HOME/tomcat/webapps/share/WEB-INF/urlrewrite.xml
$ALF_HOME/tomcat/webapps/share/WEB-INF/classes/alfresco/pagerenderer-config.xml
$ALF_HOME/tomcat/webapps/share/WEB-INF/classes/alfresco/webscript-framework-config-test.xml
$ALF_HOME/tomcat/webapps/share/WEB-INF/classes/alfresco/webscript-framework-config.xml
$ALF_HOME/tomcat/webapps/share/WEB-INF/classes/alfresco/webscripts/org/alfresco/indexall.get.mediawiki.ftl

After building and deploying alfresco.war and share.war, and testing, I switched to the instructions for building and deploying the surf platform. In these instructions, the alfwf.war is built and deployed (alfwf.war) to APP_TOMCAT_HOME. This is a minimal implementation of the webframework that only brings up a test page:


http://localhost:8080/alfwf/page?p=welcome

which runs some tests and dumps some configurations.

Alfresco Surf applications are created leveraging the following technologies and we should be familiar with all of them:

JavaScript
FreeMarker
JSP (if desired)
HTML
XML
Json

At this point, the fun begins - creating templates and components to the new surf platform.

Alfresco Community Conference in DC

2008-10-12T09:23:00.000-07:00

Last week, I attended the Alfresco Community Conference in DC where, among other things, Alfresco's Surf platform was discussed. Alfresco is moving in a bold new technical direction: towards a Web 2.0 framework developed from the ground up, completely overtaking its current Enterprise web framework based on JSF. This is bold because most vendors incrementaly develop over thier legacy frameworks. Alfresco has chosen to radically rewrite theirs.

One of Alfresco's key competitive advantages is that it had the clarity of heindsight. Alfresco could look back at the experience of the past: including Documentum, where it's CTO John Newton was co-founder, and former engineers of Vingette, Interwoven and others. This experience has allowed them to develop a better architecture from the ground up, solving the pain of the past, in a culture steeped in risk taking and innovation. Further, its committment to the community and to open principles has allowed it to continue to lead in innovation, rather than falling behind.

Sometimes openness and innovation leads to chaos. Several potential Alfresco users have hedged thier commitment to alfresco to see what Alfresco 3.0 is all about. Its radical rearchitecture has risked alienating customer customization of its previous JSF based frameworks. It is unclear what existing customers will do with this new technology, but Alfresco has committed to continue to support its legacy JSF applications for a time.

For those of us who are just starting to develop on Alfresco, the future is wide open. My company has decided to participate as Beta customers to Alfresco Enterprise 3.0. This leads us to figuring out how we can capitalize on this new platform architecture, and how to avoid the inevitable barbs of its newness. Among other blog tracks, I will update my experiences with Alfresco Surf platform with how-to's and findings. I hope this proves useful to some.

From a Technical perspective, Alfresco has rearchitected its front end web client and services relying on Web 2.0 components from Yahoo User Interface framework. The web client talks to services via RESTful JSON enabled services typically created using Alfresco's webscript framework. Surf introduces a new component model with page and component dispatching frameworks. Web client things like Templates, Pages and Components are defined declaratively leveraging lightweight XML, like the webscript framework for declaring RESTful services on alfresco. Like services, client component behavior is developed in JavaScript and benefit from a client side alfresco object model to interact with predefined components and/or alfresco remote services.

As I learn this new framework, I will blog on each step I take. I hope this will be helpful to others also learning Surf.

Enterprise 2.0

2008-09-22T05:36:00.000-07:00

I recently attended a workshop sponsored by the Chicago chapter of AIIM about Enterprise 2.0. The audience was a typical spread of IT professionals interested in document management, Image scanning and management, records management and of course consultants looking to make contacts. My team, we numbered 4, were first time attendees and were interested in getting ideas relating to our web content management applications.

Two presentations were given: Jim Vaselopulos (VP and Partner of PSC Group) focused on the human perspective in collaboration, a key aspect of Enterprise 2.0, and Andrew MacMillan (VP of Product Mgmt at Oracle ECM (formally Stellent)) was focused on its technology aspects. Both presentations were compelling: Jim's presentation brought the point home that Enterprise 2.0 technologies were focused on enabling collaboration among content stakeholders, Andrew's presentation talked about the evolving nature of technology through web 1.0 to web 1.5 and web 2.0 like technologies. After the presentations, they were joined by others in a panel discussion.

The first question on the tips of participants was 'what was Enterprise 2.0?' This was answered variously as Web 2.0 technologies applied to the enterprise, and enablement of more ad-hoc collaboration to manage content (the 'adhocracy' as Jim put it). Web 2.0 brings to the table technologies like blogs, wiki's, messaging and tagging ('tagonomy' and 'folksonomy' were entered into the lexicon). Other capabilities of Web 2.0 like 'mashups' were also mentioned. These Web 2.0 technologies are user directed evolve in an ad-hoc manner. This differs from older technology enablers that are more directed, such as workflows and taxonomies that are defined by business analysts and direct collaboration.

My take... So what is E20? E20 is Web 2.0 for the Enterprise. This soundbite will help explain it to curious management. To technologists, it is using Web 2.0 technologies like wiki's, blogs and mashups evolving in the Internet to web based business applications behind the firewall. For ECM, E20 is the addition of pure web based services and collaboration tools to enable user directed, ad-hoc collaboration and use.

The next obvious question of the group was 'what does E20 mean to me?' The group varied in their sophistication and technical backgrounds, but a rift became obvious. This rift was pointed out very succinctly by Jim Vaselopulos in his talk. As he defined it, there are 'digital immigrants' and 'digital natives'. Jim looked at the generation gap between those who were born with digital technologies and those who were introduced to it much later. Their sensibilities were different. The 'digital native's' acceptance (and demand) for truly self controlled digital collaboration far exceeded the 'digital immigrant's' desire and tolerance for the same. From a generation's perspective, baby boomer types look at technology as an addition to traditional communication and formality, necessarily organized in hierarchies. From the perspective of the 'millenniums' (born 1980 - present), technology enables 'flat' and immediate collaboration and informality.

So, from the above distinctions, users may adapt to E20 differently. A pure 'adhocracy' where users have complete freedom to structure information and collaboration may be perceived as a threat to formality of policy and hierarchical organizations. A wiki for instance is controlled by no one. Everyone is a contributor and a consumer. There is no formal structure, there is no formal control. It is subject to the whims of the users. To digital natives (typified by the 20 somethings) this isn't a problem, this is essential. To digital immigrants (the gray hairs), this is an out of control mess. How can you manage important business information this way and expect the information and its structure to just 'evolve?' Playing off of the generation gap isn't fair or accurate, but it does represent the problem in some way.

The room tended towards the 'gray hairs.' Most in the room came from IT where information management policies were more formal, and information organization existed in well structured taxonomies. For instance, introducing a wiki to manage important business information was looked at suspiciously. 'How do we control it? How do we organize it?' they would ask. Our contingent tended toward the other perspective. To a digital native, this is the very point of a wiki: 'no one controls or manages it and everyone controls and manages it.' To the digital immigrant, this can only lead to a mess. To the digital native, control and formal organization limit usefulness and frustrate collaboration. To the digital immigrant, this ad-hoc nature would limit usefulness and frustrate collaboration. Clearly, different users have different perspectives.

In my company, we are wiki happy. Everything goes on the wiki. There are no controls. There is no formal organization. Its organization evolves. The integrity of the information is the responsibility of all. Occasionally, some refactoring has taken place. There is an element of security. Groups of wiki pages are organized into departments. Users within a department are free to contribute. Others may be restricted to viewing. Personal pages remain in control of the author but anyone can read. Inappropriate content would cause some to complain to our tools team. Although this has rarely happened. Organizational structure as evolved. It is still hard to find what you are looking for. Index pages are created occasionally to organize information into loose taxonomies but not as a formal exercise--someone gets tired of hunting for things and creates a page that organizes it.

For our company, this has worked for most people. But we have also recognized that others are not that comfortable. They have tasked to our internal tools team to reconstitute a more formal intranet. This intranet will be controlled and organized formally. Information will be authored by our tech writers at the direction of the management hierarchy. The very thought of this had caused a furor amongst some in our workforce. Some were vehemently apposed to this 'throwback' to the old. Some who were baffled and dismayed by the by the wild west of the wiki were relieved and fought vigorously for its return. It was an interesting example of the digital generation divide pointed out so deftly by Jim Vaselopulos. We should use this as an example that there are more viewpoints to serve. Perhaps the lessons learned are that Web 2.0 is not for everyone. Perhaps E20 adds elements of control and formality that businesses need. Perhaps we should take away from this effort that sometimes the wild west needs a sheriff.

Enchancing ECM-SOA with Enterprise Content Bus

2008-09-16T06:04:00.000-07:00

Other capabilities we are looking for in our SOA approach is to leverage an Event Driven Architecture (EDA) focusing on Document Oriented Messages (actually Content Oriented Messages) and the ability to choreograph many content oriented services. This is the job of a message broker, but more specifically an Enterprise Service Bus (ESB).

We wish to build configurations oriented to choreographing processes for:

Acquisition - acquire content from many sources and many modes (push, pull, scheduled)
Processing - transform, aggregate, index, repurpose, replicate content
Delivery - syndicate or publish in multiple formats over multiple channels
Integration - integrate with other information sources to enrich content

We believe to fully allow us to integrate with the rest of the enterprise, we will need the flexibility that an ESB brings to a SOA. It may be helpful to begin by trying to explain what an ESB is (at least from my perspective). To truly leverage a multitude of services distributed throughout the enterprise, we need to choreograph multiple services together in a process flow. These services may need to be accessed differently using REST, SOAP, JMS or FTP. An ESB centralizes integration and choreography of services and provides many capabilities to talk over multiple channels, route and process messages in many different ways, all mostly through configuration rather than code. Also an ESB can be considered as a container for services oriented toward integration such as routing and transformation. An ESB brings shared capabilities like security, transformations, routing, security, transactionality and high-availability so these cross cutting concerns can be applied uniformly and and not have to be custom developed. An ESB is a specialist in integration and choreography. It allows integration logic to move out of each client, service or service container and reside in a Service Oriented Integration container.

An example may help. A process flow in this case can be a pathway for content to travel from acquisition, to management, processing, to delivery. Each one of these stages in the content's life-cycle might require integrating with many distributed services. Suppose I am automating the process of acquiring word documents to index and post on an intranet.

For acquisition, i may want to poll an external ftp drive to see if new content has arrived
For processing, I may want to enrich this content with computed metadata and store it in the content repository for retension
I also I may want to transform this content into a different representation (i.e. word to PDF)
For delivery I may want to deliver this pdf to a website
Further, I want to update an index page to this document

One approach is to build this as a customization of a content manager. Most content managers offer a way to ftp content to their content repository. But to 'poll' an ftp site would require custom coding. Once the content is in the repository, a workflow or rules can be triggered that integrates automated actions and human tasks. The first step would be to create a PDF copy. Once a PDF copy is created, a job can be scheduled to index the PDFs as a web page index, and then publish the index and latest PDF files to the site.

Another approach would be to leverage an ESB. Leveraging an ESB may improve agility of developing these processes. For instance servicemix has pre-developed and configurable ways to 'poll' and 'send' messages via an ftp channel. One a file is found on the ftp via polling, Further using servicemix a route can be configured by using various Enterprise Integration Pattern implementations. In this case, a 'pipeline' can be configured to choreograph services:

Store acquired word doc via content service
Transform word to pdf via transformation service
Store pdf via content service
Generate index invoking a template service

Finally, the pdf and the index page can be stored to the site's file system via the file sender (another configuration).

Further benefits exist leveraging an ESB. Each step in this process is made via a SEDA architecture using durable queues. That means that if any of the choreographed services break, take longer than expected or otherwise behave unexpectedly, the process continues unabated. The ESB route can be configured to handle error cases such as a service returning an error result. The processing routes can be transactional, and roll back all changes if one step changes. The ESB can be clustered to support High Availability, and can be configured to route based on the type of processing. Further, the services choreographed can be accessed over numerous channels: REST (http), ftp, file, jms, jabber,SOAP (http). And modifying the process in many cases requires reconfiguring, not recoding. And the process configurations are not distributed in many services or clients, but centralized on the ESB.

While there are many ways to choreograph services, an ESB approach may improve agility by leveraging a set of configurable components specialized in integration, orchestration and choreography and that can speak many languages to different distributed systems. The purpose of the ESB is not to take over services from the content manager or other systems but to leverage them. Moving choreography of services to a specialist like an ESB removes the need to create a lot of custom scripting in a content manager which may not be as good at these tasks.

But existing ESB implementations are focused on choreographing messages, not content. Existing ESBs don't have configurable components around processing of content, and may not do well passing around large content. An ESB needs to be customized to manage content and provide configurable components to enhance content processing. Thus, we are constructing an ECB (Enterprise Content Bus) that builds these content centric capabilities on top of an Enterprise Service Bus.

Although not mentioned in the example, choreography using enterprise integration patterns provides a lot of flexibility in combining many services, but the addition of Business Process Management allows these services to be orchestrated according to configurable business processes, and is a great addition to the ESB. Simple processes from acquisition to management to deployment can be implemented via piplelines and wiretaps and content switches. But processing content often requires a business process that integrates invocation of services, integration of systems and human tasks, and provides the visibility into the content processing pipeline. (See following posts on our approach to integrating BPM to our ECB.)

The details to follow in the next post...

ECM SOA standards with CMIS

2008-09-16T05:21:00.000-07:00

Selecting the 'content services' layer -

One of the chief complaints has been the lack (or multitude) of multi-vendor standards for ECM that can fit into a SOA architecture. Recently, EMC, IBM and Microsoft have announced a new standard: CMIS that intends to address this. This standard will be submitted to OASIS for further work. In the mean time, several vendors such as Alfresco Oracle and others are developing implementations of this standard.

In my previous post, I described the components I thought were needed to support a fully functional SOA approach to ECM. Included was an item 'content services'. I believe that this standard fits well into this category. Other 'standards' also exist that we have used:
* WebDAV offers simple access to content and metadata over http.
* JSR 170 offers more sophisticated content model access for Java based clients.

Typically writing content aware applications involves customizing a proprietary content manager application using proprietary APIs and possibly scripting languages. If one is brave enough to attempt to develop an independent application that needs to integrate to a content repository (as we have been), only proprietary API's exist that lock the application into that vendor's content manager. Alternatively, most vendors support some level of WebDAV. So it is possible to develop a content aware application leveraging WebDAV, but different vendors support WebDAV to different levels of compliance. Also since there is no typing model, enforcing a content model standard is difficult. To overcome this in the past, we have developed a WebDAV client that adds typing capability. This effort drove us to look seriously at using JCR (JSR 170). Using JSR 170 means implementing a session based approach and, of course, locks you into Java. But it does offer rich content model semantics. However, its session based, its Java centric nature and its lack of support RESTful or SOAP channels makes it a poor choice for a SOA.

Since CMIS offers a stronger type model and can be developed in SOA friendly SOAP or RESTful manner, it seems it has the right stuff for a standard 'content services' layer to access the Content Repository. However, we need to leverage what exists now in our approach. Since we are a Java shop and will be leveraging one content vendor, JSR 170 still seems the best approach. For RESTful access strongly suggested at our organization, WebDAV may provide a stop gap. We will likely follow CMIS closely and prototype with it.

Next post, a discussion of the Enterprise Content Bus...

ECM-SOA with an Agile Attitude

2008-09-08T06:13:00.000-07:00

In this entry, I will identify the attitudes and concepts that define our ECM-SOA vision. Next entries, I will dive into the technical selections and customizations.

The first challenge is to think of our tooling as not a custom application, but more as a set of adaptable services, applications and integrations. This requires a change of thought. Our previous efforts were to drop a monolithic application called a Content Manager into the middle of things, and then propose to change the business process around this application, ostensibly obsoleting the existing applications and ad-hoc processing to customizations within this new application.

During our previous attempt, we underwent a lengthy analysis phase and generated a 500 page requirements document detailing taxonomies, content types, work flows and templates that would solve our content management (web content management) needs. We then spent lots of time and treasure implementing these requirements. In the end, we built some of the requirements taking far longer and far more resources than anticipated, and we found that most the requirements and subsequently most of the customizations we built were wrong. The heroic content managers and brand managers made it work anyway, developing more ad-hoc, complicated and time consuming steps around yet another application that was supposed to help them. This story is not unique.

We must shift our processes as much as our technology. We are focusing on smaller efforts, more agility and more feedback and move away from 500 page requirements documents. To do this successfully, our architecture also needs to be agile and amenable to change. Our architecture must be a framework to grow on: to grow useful services, and to grow and integrate with useful applications. It must follow user demand that learns from using and refining our processes and tools.

At the core of our architecture is the Content Repository. This tool will store content through various stages of use. It must have versioning capability, search capability, auditing capability, it must provide a flexible capability to organize content into collections, and it must provide flexible meta data structures that can apply both simple and hierarchical views of content cross cutting storage structure.

On this repository, we must define a content model that is flexible and extensible. But the cost of changing and refining storage and meta-data structure must be tolerable. Our definitions must be incremental, careful not to lock ourselves into bad organization and not to anticipate too far in the future. Changes to the content model are always the must costly and must be considered with greater care. The analogy is to a database. Many applications can use the database, and it can store and retrieve a lot of information, but defining and changing its structure must be done with care. Eventually, all content must be converted and stored in the repository in order to maximally leverage the content throughout the organization.

On top of the Content Repository are a set of content services. These services allow applications to be quickly developed and adopted that leverage content and content features. These content services should be developed by leveraging standards including JSR 170 and WebDAV to make them accessible to existing and future application needs. Typically, a Content Manager user interface comes with the content repository that provides a clear view and access to the content. This application can be customized and with enough effort it can host all application needs, but we are weary of this monolithic approach. Current applications exist that may be more suited to business needs. They must be adapted at least to leverage a common repository by using these content services. But they will continue to supply unique views and functions. Later, application integration through the use of portalization may help to alleviate the chaos of multiple applications and views.

Accepting that content exists in many places and is required by many applications, we look to the concept of an Enterprise Service Bus. We will have many integrations to other applications, and content must be acquired, processed, and delivered in unique ways. An ESB allows the centralization of this integration and processing, reducing coupling to the rest of the organization and potentially increasing agility by being more adaptable to change. However, the concept of the ESB focuses on messaging, not content. We will adapt this to provide content processing capabilities and tag it as an Enterprise Content Bus (ECB). This ECB concept will evolve over time and will be detailed here over many posts.

Finally, choreographing acquisition, processing and delivery of content becomes a challenge. Both automated and manual steps must be organized into business processes that adapt and grow over time. Over engineering the business process can be just as damaging as not managing it at all. The content architecture must support a Business Process Management (BPM) applicaiton capable of orchestrating both manual and automated steps. It must be integrated well with the content management application and repository, and the Enterprise Content Bus (ECB). The use of configurable Business Rules Engine (BRE) will help define controls through the steps, enforcing standards, validating processing and ensuring high quality. This capability will allow content management to grow in a managed way over time, in a fully exposed and auditable way.

This architecture is a suite of application cababilities, each highly adaptable and customizable.

To sum up:

The Content Repository stores all content applying standard features
The Content Model enforces standards and increases usefulness across usages
The Content Services allows access to the content reposisotry by manay applications
The Content Manager provides a user interface to manage content
The Enterprise Content Bus (ECB) allows content to be acquired, processed and delivered
The Business Process Management (BPM) frawork allows processing to be orchestrated
The Business Rules Engine (BRE) inforces consistency and quality throughout processing

This is our ECM-SOA vision. How do we implement it? The next posts will tell..

The answer is ECM-SOA

2008-09-04T20:06:00.001-07:00

Of course the answer (to the previous post's concerns) is to try and leverage a Service Oriented Architecture as part of the ECM strategy. So that starts me on my way.

In order to understand my approach, let me share with you some articles and books that have guided me.

Some articles of interest focusing on ECM-SOA:

ECM SOA Article in AIIM talks about SOA for ECM in context of Web 2.0 (or Enterprise 2.0 if you will), but still useful
Integrated Solutions Magazine's ECM SOA article has some data to help support the business case
Since ECM SOA is discussed in context with Web 2.0 (or Enterprise 2.0) I downloaded a good overview of Enterprise 2.0 to keep up with the buzz

But more specifically, my guidance has been more general SOA/Web Services books and guides. is on what SOA is/isn't has been influenced by these books:

Eric Newcommer's classic Understanding SOA with Web Services is not only informative, but a good read
Thomas Erl's SOA Principles of Service Design is the classic, but I didn't get as much out of it as I would have liked
Specifically, I've been interested in Web Services, REST, Enterprise Service Bus and BPM aspects
RESTFul Web Services from O'reilly is very good
Enterprise Service Bus by Chapell was our bible for a while in 2004-2006 and may be a bit dated now
Enterprise Integration Patterns from Martin Fowler's series is exceptional and essential to our work
I found Essential Business Process Modeling very informative theory oriented. For practical use, i just gleaned from implementation approaches on the web (i.e. JBoss' jBPM)

So what is the scope of our work?

The part of ECM we are building now is focused on Web Content Management. We have a common platform on which we can configure, skin and run many travel sites. We are a global company, and our sites must support many languages. The platform must host many brands so each site must be able to be skinned, configured and customized as if it was purpose built.

A key challenge for this is managing web content in multiple languages and for multiple brands. Each type of content we publish to the site needs to be translated to local languages and adapted to fit the brands. Each type of content is currently managed in unique applications, processed with a cadre of custom code and delivered in unique formats.

With all of this custom code, storage and formats, it is difficult to create functions that extend to many types of content, such as those to handle translation and branding. Our challenge is to unify content management and extend our capabilities to efficiently stand up new brands and languages without sinking the content managers and brand managers in a mire of complex, ad-hoc tools, technologies and practices. So our rally cry is "Stand up a new site in 1 day! (any language, any brand)." At least the tools shouldn't be a bottleneck!

Next, our vision...

ECM SOA Strategy

2008-09-03T06:01:00.000-07:00

I am attempting to build a ECM-SOA strategy at my company. This blog will identify key issues we have run across and the solutions we are attempting. I will get very technical since I am the primary technologist for content technologies at my company, but I will also maintain a higher level focus on the business aspects of this initiative, since the two are inextricably tied together.

At my company, we have many applications that manipulate content, both for site management and for document management. Each application was built as a silo, unique technology to suit a unique job -- no sharing, no reuse. This is typical for many companies, whether content management applications or other types of applications. Service oriented architectures (SOA) try to address this issue by placing a service layer between applications that consume services and service provider applications, allowing many applications to leverage shared services. Implementing this forces the organization to think about standards and common facilities.

Enterprise Content Management (ECM) is a term referring to a strategy to manage content across the enterprise in a common way, leveraging common facilities. ECM covers types of content applications including Web Content Management (WCM), Document Management (DM), Records Management (DM), Digital Asset Management (DAM) and others. Companies like mine typically have all of these needs. And we have applications that address these needs, but, like many companies, they are composed of unique purpose built applications with no overarching strategy or technology. Also vast holes exist in this application web that necessitate ad-hoc approaches and manual intervention, costing in labor and quality. This silo approach is costly and limiting.

Vendors attempt to address this need by selling monolithic systems that replace these many purpose built applications with customizations and tailoring of their product. Aggressive implementations of these systems force the organization to change and adapt in order to be successful. Failure typically happens because the organization is unable or unwilling to make these changes, and the customization efforts of these products is vastly underestimated. Much is promised by these solutions, but little is delivered. Sometimes millions of dollars of 'shelfware' or hobbled and cobbled systems limp along adding little and causing frustration and empathy. This is nothing unique to ECM: try CRM, ERP and others. Consultants love them. Companies hate them. We can do better.

My approach is to be more evolutionary. We cannot rip out the many processes and programs that make up a web of content management. They work (more or less), and they focus on solving specific problems. There is a lot of knowledge embedded in each application. There is a lot invested in them: both mindshare and monentary. But change is forcing us to change. We have to improve our efficiency at the same time we expand to a global presence. We have to adapt our management systems to serve our new global platforms. In particular, site content management (Web Content Management and Digital Asset Management) must improve or we will sink under the weight of all the content management needs. In short, we have to change everything to realize our vision. But how can we be evolutionary and still change everything?

I'll leave with this cliff hanger for now...

Region	Scope	Component
header	global	global.header.xml exists
title	template	template.title.contentgrid.xml copied from template.title.documentlibrary.xml
navigation	template	template.navigation.contentgrid.xml copied from template.navigation.documentlibrary.xml
toolbar	template	template.toolbar.contentgrid.xml copied from template.toolbar.documentlibrary.xml
gridview	template	template.gridview.contentgrid.xml created new
filter	template	template.filter.contentgrid.xml copied from template.filter.documentlibrary.xml
tree	template	template.tree.contentgrid.xml copied from template.tree.documentlibrary.xml
tags	template	template.tags.contentgrid.xml copied from template.tags.documentlibrary.xml
footer	global	global.footer.xml exists