Jared Ottley

Continuing on from my previous post on Simple Workflows let’s look at using the Simple Workflow model in a few web scripts.

The first web script will add a simple workflow to a node. The second will allow us to signal the transition of accept or reject on that node.

Add a Workflow

As discussed in the previous post, a simple workflow is made up of two paths: accept or reject with a copy or move to another folder. You are also able to set the name presented to the user for the accept or reject step. This is very useful as what we may be presenting to the user is to not accept or reject documents, but rather sending the document to two different group owned folders based on context/content of those documents. At least one step is required. Alfresco defaults “accept” for the required step and makes “reject” the optional step. These need to be passed to our web script. The payload is passed as json. A full example of this looks as follows:

{
    "simpleworkflow": {
        "accept": {
            "name": "acceptstep",
            "move": true,
            "folder": "workspace://SpacesStore/ebd7ff99-b423-4e45-ad4f-71929ce4c089"
        },
        "reject": {
            "name": "rejectstep",
            "move": true,
            "folder": "workspace://SpacesStore/0239b2ed-ebfa-4b9d-a7fa-f0404448cffc"
        }
    }
}

In the above example, the reject object is optional.

Both the accept and reject objects are made up of the three required values of the simple workflow aspect: name, move and folder.

The name field maps to either approveStep or rejectStep. It is the name presented in the Alfresco UIs. But it could also be used in a custom interface as they are returned as part of the list of properties for the node.

The move field maps to either approveMove or rejectMove. This boolean field indicates with a true value to move the node or, if false, to copy the node.

The final field, folder, maps to approveFolder or rejectFolder. This is the folder node where the document should be moved or copied to when the appropriate action is taken.

The web script can be call by passing the simpleworkflow json object to simpleworkflow/add/{store_type}/{store_id}/{id}. Upon completion a json object of { "success": true|false] }. True upon successful completion, false if there was an error adding the simpleworkflow aspect to the node.

Using a Simple Workflow from a Web Script

This web script was originally developed for a customer to return XML, but I’ve now updated it to return json by default. The XML is maintained here for backwards compatibility.

When a simple workflow aspect is added to a node, it just adds the properties of what should occur when an accept or reject action is taken. The actual actions of what happens is built into UIs. So the web scripts need to do the same: perform the copy or move to the targeted folder. The call is pretty simple: simpleworkflow/{accept|reject}/{store_type}/{store_id}/{id}. The json or XML that is returned let us know of either the success or the failure of this action. Failures can provide some information on why the failure occurred. A success messages, provides more detail: what action occured — copy or move, which step was taken — returning the name as set in the approveStep or rejectStep properties, the folder that document was moved or copied to. The destination that is returned is the human readable path. (If there is any interest we can update this to return the nodeRef as well as the path.)

The json returned looks like:

{
    "success": true,
    "action": "move",
    "step": "acceptStep",
    "destination": "/Company Home/Sites/workflow/docmentLibrary/workflow/accept"
}

These web scripts can be downloaded from its Google Code Project.

When I worked on the sales side at Alfresco, one of the easiest things to demo was a simple workflow. It was usually something that enabled the prospect to tick off a major requirement on their long list of things that the solution they were looking for needed. Alfresco has two kinds of workflow: simple and for lack of a better word advanced. Advanced workflows usually require some level of business logic, multiple steps, several actors, etc. Advanced workflows are implemented using Activiti (Alfresco 4.0 forward) or JBPM (pre Alfresco 4.0 and maintained for legacy in Alfresco 4.0) Simple workflows provide an accept, a reject, and then the content is either copied or moved to another folder.

What I really like about simple workflows is how they are implemented and how you can model your own customizations or applications using this pattern. As a follow up to this post I’m going to share a web script to add a simple workflow to a node and then another to progress the workflow by accepting or rejecting it.

Let’s dig in!

Simple workflows present, as stated above, the ability to accept and reject the document and then copy or move that document to another space. The key to a simple workflow is the model.

      <aspect name="app:simpleworkflow">
         <parent>app:workflow</parent>
         <properties>
            <property name="app:approveStep">
               <type>d:text</type>
               <protected>true</protected>
            </property>
            <property name="app:approveFolder">
               <type>d:noderef</type>
               <protected>true</protected>
            </property>
            <property name="app:approveMove">
               <type>d:boolean</type>
            </property>
            <property name="app:rejectStep">
               <type>d:text</type>
               <protected>true</protected>
            </property>
            <property name="app:rejectFolder">
               <type>d:noderef</type>
               <protected>true</protected>
            </property>
            <property name="app:rejectMove">
               <type>d:boolean</type>
            </property>
         </properties>
      </aspect>

Each node that has a simple workflow attached to it has this aspect applied to it, which specifies through properties what steps are available, what that step should be called (acceptStep and rejectStep) and then what should occur when that step is taken: should it be moved or copied (acceptMove and rejectMove)? and where it should go (acceptFolder and rejectFolder).

Knowing this opens many doors for us. Because the steps are properties on the node, we can modify them, if needs be, using either javascript or Java. We can also build on top of this. When I worked on the Consulting team at Alfresco a customer wanted to have a three step workflow: accept, reject and other. Modeling this was simple. All we really needed to do was add three simple properties: the step name (text), the destination node (noderef) and if it is a move or copy (boolean). A bit more complex was adding the logic for exposing this through the Explorer UI. (This customer had not yet moved to Share). Because we did not want to affect all of the simple workflows already in place, we opted to add an additional 3 step simple workflow, giving them the ability to have up to 5 different paths that could be taken for a single node.

We can also tie simple workflows into more complex actions: dynamically adding simple workflows or scripting more complex actions that allow users to manually take the workflow steps but also allowing programatic lifecycle or state to take simple workflow actions. By jumping out of Explorer or Share and into a custom application you can expose simple workflows from the repository through a web script (an easier task than modifying JSF) and one that I’ve used for several different Alfresco implementations. We will cover that in my next post.