(For more resources on this subject, see here.)
Current limitations in Records Management
The 3.3 release of Alfresco Records Management comes with some limitations about how rules and workflow can be used.
Records Management requirements, and specifically the requirements for complying with the DoD 5015.2 specification, made it necessary for Alfresco developers, at least for this first release of Records Management, to make design decisions that involved limiting some of the standard Alfresco capabilities within Records Management.
The idea that records are things that need to be locked down and made unalterable is at odds with some of the capabilities of rules and workflow. Proper integration of workflow and rules with Records Management requires that a number of scenarios be carefully worked through. Because of that, as of the Alfresco 3.3 release, both workflow and rules are not yet available for use in Records Management.
It is expected that capabilities of Records Management working alongside with rules, workflow, and APIs will likely improve in future releases of Alfresco.
While the topic of this article is workflow and automation, the limitations we've just mentioned don't necessarily mean that there isn't anything left to discuss in this article. Remember, Alfresco Records Management co-exists with the rest of Share, and rules and workflow are alive and well in standard Share.
Also remember that prior to being filed and declared as a record, many records start out their lives as standard documents that require collaboration and versioning before they are finalized and turned into records. It is in these scenarios, prior to becoming a record, where the use of workflow often makes the most sense.
With that in mind, let's look at the capabilities of rules and workflow within Alfresco Share and how these features can be used side-by-side with Records Management today, and also get a feel of how future releases of Alfresco Records Management might be able to more directly apply these capabilities.
The Alfresco rules engine provides an interface for implementing simple business rules for managing the processing and flow of content within an organization. Creating rules is easy to do. Alfresco rules were first available in the Alfresco Explorer client. While rules in the Explorer client were never really hard to apply, the new rules interface in Share makes the creation and use of rules even easier.
Rules can be attached to a folder and triggered when content is moved into it, moved out of it, or updated. The triggering of a rule causes an action to be run which then operates on the folder or the contents within it. Filters can also be applied to the rules to limit the conditions under which the trigger will fire. A trigger can be set up to run from one of the many pre-defined actions or it can be customized to run a user-defined script.
Rules are not available for Share Records Management Folders. You may find that it is possible to bypass this limitation by either navigating to records folders using the Repository browser in Share or by using the JSF Explorer client to get to the Records Management folder. From those interfaces, it is possible to create rules for record folders, but it's not a good idea. Resist the temptation. It is very easy to accidently corrupt records data by applying rules directly to records folders.
Defining a rule
While rules can't be applied directly to the folders of Records Management, it is possible to apply rules on folders that are outside of Records Management which can then push and file documents into records folders. We'll see that once a document is moved into a records folder, rules can be used to update its metadata and even declare it as a record.
To apply rules to a folder outside of the Records Management site, we select the Manage Rules action available for a folder:
On the next screen, we click on the Create Rules link, and we then see a page for creating the definition of the rules for the folder:
A rule is defined by three main pieces of information:
- The trigger event
- Filters to limit the items that are processed
- The action that is performed
Triggers for rules
Three different types of events can trigger a rule:
- Creating or moving items into the folder
- Updating items in the folder
- Deleting or moving items from the folder
Filters for rules
By default, when an event occurs, the rule that is triggered applies the rule action to all items involved in the event. Filters can be applied that will make rules more restrictive, limiting the items that will be processed by the rule.
Filters are a collection of conditional expressions that are built using metadata properties associated with the items. There are actually two conditions. The first condition is a list of criteria for different metadata properties, all of which must be met. Similarly, the second condition is a list of criteria for metadata properties, none of which must hold.
For example, in the screenshot shown below, there is a filter defined that applies a rule only if the document name begins with FTK_, if it is a Microsoft Word file, and if it does not contain the word Alfresco in the Description property:
By clicking on the + and – buttons to the right of each entry, new criteria can be added and existing criteria can be removed from each of the two sets.
To help specify the filter criteria from the many possible properties available in Alfresco, a property browser lets the user navigate through properties that can be used when specifying the criteria. The browser shows all available properties associated with aspect and type names:
Actions for rules
Actions are the operations that a rule runs when triggered. There is a fairly extensive library of actions that come standard with Alfresco and that can be used in the definition of a rule. Many of the actions available can be configured with parameters. This means that a lot of capability can be easily customized into a rule without needing to do any programming.
Actions that are available for assignment as rule actions are shown in the next table:
It is interesting to note that there are many Records Management functions in the list that are available as possible actions, even though rules themselves are not available to be applied directly to records folders.
Actions can accept parameters. For example, the Move and Copy actions allow users to select the target destination parameter for the action. Using a pop-up in the Rules Manager, the user can find a destination location by navigating through the folder structure. In the screenshot below, we see another example where the Send email action pops up a form to help configure an e-mail notification that will be sent out when the action is run:
Multiple rules per folder
The Rules Manager supports the assignment of multiple rules to a single folder. A drag-and-drop interface allows individual rules to be moved into the desired order of execution. When an event occurs on a folder, each rule attached to the folder is checked sequentially to see if there is a match. When the criterion for a rule matches, the rule is run.
By creating multiple rules with the same firing criteria, it's possible to arrange rules for sequential processing, allowing fairly complex operations to be performed. The screenshot below shows the rules user interface that lets the user order the processing order for the rules. Actions like move and copy allow the rules on one folder to pass documents on to other folders, which in turn may also have rules assigned to them that can perform additional processing.
In this way, rules on Alfresco folders are effectively a "poor man's workflow". They are powerful enough to be able to handle a large number of business automation requirements, although at a fairly simple level. More complex workflows with many conditionals and loops need to be modeled using workflow tools like that of jBPM, which we will discuss later. The next figure shows an example for how rules can be sequentially ordered:
Now let's look at an example where we file documents into a transit folder which are then automatically processed, moved into the Records Management site, and then declared as records. To do this, we'll create a transit folder and attach two rules to it for performing the processing.
The first rule will run a custom script that applies record aspects to the document, completes mandatory records metadata, and then moves the document into a Folder under Records Management, effectively filing it. The second rule then declares the newly filed document as a record.
The rules for this example will be applied against a folder called "Transit Folder", which is located within the document library of a standard Share site.
Creating the auto-filing script
Let's look at the first of the two rules that uses a custom script for the action. It is this script that does most of the work in the example. We'll break up the script into two parts and discuss each part individually:
// Find the file name, minus the namespace prefix (assume
var fPieces = document.qnamePath.split('/');
// Remember the ScriptNode object for the parent folder being filed
var parentOrigNode = document.parent;
// Get today's date. We use it later to fill in metadata.
var d = new Date();
// Find the ScriptNode for the destination to where we will file
hardcoded here. More complex logic could be used here to
categorize the incoming data to file into different locations.
var destLocation = "Administrative/General Correspondence/2011_01
var filePlan =
var recordFolder = filePlan.childByNamePath(destLocation);
// Add aspects needed to turn this document into a record
// Complete mandatory metadata that will be needed to declare as a
document.properties["rma:originator"] = document.
document.properties["rma:originatingOrganization"] = "Formtek, Inc";
document.properties["rma:publicationDate"] = d;
document.properties["rma:dateFiled"] = d;
// Build the unique record identifier -- based on the node-dbid value
var idStr = '' + document.properties["sys:node-dbid"];
// Pad the string with zeros to be 10 characters in length
while (idStr.length < 10)
idStr = '0' + idStr ;
document.properties["rma:identifier"] = d.getFullYear() + '-' +
At the top of the script, the filename that enters the folder is extracted from the document.qnamePath string that contains the complete filename. document is the variable passed into the script that refers to the document object created with information about the new file that is moved into the folder.
The destination location to the folder in Records Management is hardcoded here. A more sophisticated script could file incoming documents, based on a variety of criteria into multiple folders.
We add aspects rma:filePlanComponent and rma:record to the document to prepare it for becoming a record and then complete metadata properties that are mandatory for being able to declare the document as a record.
We're bypassing some code in Records Management that normally would assign the unique record identifier to the document. Normally when filed into a folder, the unique record identifier is automatically generated within the Alfresco core Java code. Because of that, we will need to reconstruct the string and assign the property in the script.
We'll follow Alfresco's convention for building the unique record identifier by appending a 10-digit zero-padded integer to the year. Alfresco already has a unique object ID with every object that is used when the record identifier is constructed. The unique ID is called the sys:node-dbid. Note that any unique string could be used for the unique record identifier, but we'll go with Alfresco's convention.
Finally, the script saves the changes to the document and the document is filed into the Records Management folder. At this point, the document is now an undeclared document in the Records Management system.
We could stop here with this script, but let's go one step further. Let's place a stub document in this same folder that will act as a placeholder to alert users as to where the documents that they filed have been moved.
The second part of the same script handles the creation of a stub file:
// Leave a marker to track the document
var stubFileName = fName + '_stub.txt' ;
// Create the new document
var props = new Array();
props["cm:title"] = ' Stub';
props["cm:description"] = ' (Stub Reference to record in RM)';
var stubDoc = parentOrigNode.createNode( stubFileName, "cm:content",
stubDoc.content = "This file is now under records management
control:\n " + recordFolder.displayPath + '/' + fName;
// Make a reference to the original document, now a record
The document name we will use for the stub file is the same as the incoming filename with the suffix _stub.txt appended to it.
The script then creates a new node of type cm:content in the transit directory where the user originally uploaded the file. The cm:title and cm:description properties are completed for the new node and text content is added to the document. The content contains the path to where the original file has been moved.
Finally, the cm:referencing aspect is added to the document to allow a reference association to be made between the stub document and the original document that is now under Records Management. The stub document with these new properties is then saved.
Installing the script
In order for the script to be available for use in a rule, it must first be installed under the Data Dictionary area in the repository. To add it, we navigate to the folder Data Dictionary / Scripts in the repository browser within Share. The repository can be accessed from the Repository link across the top of the Share page:
To install the script, we simply copy the script file to this folder. We also need to complete the title for the new document because the title is the string that will be used later to identify it. We will name this script Move to Records Management.
|Read more about this book|
(For more resources on this subject, see here.)
Adding the folder rules
We are now ready to add the rules to the folder. Within the Manage Rules area for the folder, we create the first of two rules:
Based on the criteria set in the form, the first rule:
- It is applied to all items coming into the folder
- It will not process incoming files when the filename ends in the suffix _stub.txt
- It executes the script Move to Records Management as the rule action
Files that end in the suffix _stub.txt are not processed because these are the stub files that are created to reference the location of the original files coming into the folder. Processing these files would cause the script to go into an infinite loop, creating a new stub file for each previous stub file being added.
This first rule is also ordered sequentially as the first of the two rules. It will be processed first, add the records aspects, complete mandatory metadata fields, and file the document in a Records Management Folder. It will also create a stub document in the folder with a reference to the record location.
The second rule is created in a similar way with identical triggering criteria. The rule has the following features:
- It is applied to all items coming into the folder
- It will not process incoming files when the filename ends in the suffix _stub.txt
- It runs the pre-defined action of declaring the document as a record
Updating the form
The form used to display the metadata for the type cm:content in the Document Details page does not display the properties from the aspect cm:referencing by default. We would like to be able to display the property cm:references as a link to the original record that was uploaded from the details page of the stub document.
To do that, we need to make two changes to the definition of the default cm:content form in tomcat\webapps\share\WEB-INF\classes\alfresco\share-formconfig.xml. The changes need to appear in an override file to be stored in the tomcat\shared\classes\alfresco\web-extension\site-webscripts directory.
We add an entry for field-visibility and another for appearance. After adding this file, we restart the server:
<show id="cm:references" />
<field id="cm:references" read-only="true" >
Testing the auto-filing rules
Once the rules are defined and the form override file is in place, we are ready to test the auto-filing capability. To do that, we can go to the Transit Folder and upload a file. After the upload, we see a new file added to the Transit Folder directory, but it is not the file that we uploaded. It is the stub file that was created.
If we open the details page of the stub document, we see the References data in the Metadata form, referring to the original file. We also see a text message in the content that includes the path in the repository to the declared record in Records Management:
We can then look at the record within the File Plan and see that it has indeed been filed. The metadata has been updated appropriately and the document has been declared as a record. By scrolling to the end of the metadata, we can also see that the disposition instructions for the record have also been added:
Workflow or, as it is sometimes called, "Advanced workflow", has been gradually implemented in the 3.x releases of Alfresco Share. In version 3.4, most workflow capabilities that had been available in the Alfresco Explorer client have been made available in Alfresco Share. Earlier, in the 3.3 release of Alfresco, only very simple workflows could be created and assigned within the Share workflow structure.
One limitation of workflow is that it has been disabled for Records Management. It's not clear whether workflow will be enabled within the Records Management site as Alfresco Share becomes even more capable.
We'll see in the rest of this article, similar to how we discussed the rules framework earlier, workflow can be approached as something that supports document processes prior to being filed into Records Management.
Embedded jBPM workflow engine
Rules, while powerful, breakdown when the processes that they model become too complex. Advanced workflow is the solution within Alfresco for modeling complex processes with many tasks and complex transitioning between those tasks. Advanced workflow is made possible by the jBPM workflow engine, which is embedded in the core Alfresco software. jBPM (JBoss Business Process Management) is open source software, which is managed by RedHat.
Using the graphical layout tool within jBPM, business processes can be visually constructed by drawing process activities and connecting them with transition lines. The resulting visual workflow diagram can be used by both non-technical users and developers as a discussion point for coming to an agreement on the flow of a business process.
Once agreed to, the workflow diagram can then be turned into a process description in the form of XML, and that process description can then be fed into the workflow engine. Within Alfresco, the workflow is seen as a template that can be selected and initiated as a process instance within Alfresco.
The jBPM engine is a RedHat JBoss product, but it is completely independent of the JBoss application server. jBPM comes bundled with the Alfresco installation and can be run with any application server. For more information about jBPM, go to the home page: http://jboss.org/jbpm.
jBPM graphical process designer
The jBPM graphical process designer (GPD) is a plugin for the Eclipse IDE. The jBPM GPD has an interface for easily laying out the flow of a process. As nodes and transitions between the nodes are drawn using the GPD, equivalent XML source code is automatically created that describes the process.
The XML generated by the GPD creates a skeleton definition file that is used by Alfresco to interpret the process flow. The XML created by the GPD then needs to be manually edited before feeding into Alfresco in order to include role to task mappings and to define how actions for a task are to be performed within Alfresco. The file used by the jBPM workflow engine follows the syntax of the jBPM process design Language (jPDL).
More detailed information about how to set up the GPD Eclipse plugin and how to create jPDL XML documents for use within Alfresco can be found on the Alfresco wiki at http://wiki.alfresco.com/wiki/WorkflowAdministration.
Standard Share workflows
In Share version 3.3, only two workflow templates are available. In version 3.4, a few additional templates were added. Unfortunately, workflows cannot be directly applied to records within a Records Management site.
Workflows can be applied as an action to a single or to multiple documents in a standard Share site:
After the Assign Workflow action is selected, a dialog pops up that allows the user to select the workflow template to assign to the document.
From the drop-down list of this menu, we see that there are two out-of-the-box workflow templates that can be assigned:
- Review & Approve: This workflow template lets this document be sent to one or more users with the task to review and to then approve or reject the document's content.
- Adhoc Task: This workflow template allows the document to be sent to another user on an ad hoc basis for further work.
Consider the following workflow scenario:
Susan, an Engineer, has just completed writing a document about company network security policies. Susan does not have direct access to the Records Management System.
Susan checks her document into the document library of the Share site called "Operations".
Susan starts a workflow and assigns to Bill, the Records Manager, a task to first review the document, to then file it in the Records Management system, and declare it as a record, if appropriate.
Bill is alerted of Susan's request via the workflow. He finds and reviews the document, and then files it and declares it.
Bill marks the workflow task as approved and completed.
Susan is alerted that Bill has approved and processed her request.
To implement this workflow, we will use the standard Alfresco Review & Approve workflow template.
The workflow template
We can see the flow of the Review & Approve template in the following diagram. Shown here is the workflow as modeled in the jBPM GPD tool. It is annotated to show the roles that Susan and Bill play in the workflow process that we just described:
Starting the workflow
Let's now run through the flow of this workflow and see how it works. Susan kicks it off by first checking in her recently completed document about network security. She checks this document into the document library of the Share site called "Operations".
To start the workflow, Susan clicks on the Assign Workflow action available for the document. She selects the workflow template called Review & Approve, assigns the task to Bill, and specifies a Due Date for completing the task:
Susan then clicks on the Assign Workflow button at the bottom of the pop-up. Immediately after doing that, she sees a small status icon displayed next to the document that indicates that the document is now included as part of a workflow:
|Read more about this book|
(For more resources on this subject, see here.)
We next see that Bill logs in to Share. On his custom Share home page, he sees that he has been assigned a new task that is displayed in his My Tasks dashlet:
The task includes the instructions from Susan and a link to the document intended for review. After clicking on the link to the document, he is able to review the document. After checking the document, Bill approves it. He then moves the document into the Records Management site. He completes any mandatory metadata associated with the record and then declares the document as a record:
When Bill has completed his task, he returns to the My Tasks dashlet and closes out the task by clicking on the Approve link. After doing that, the task item is removed from Bill's task list.
Completing the workflow
The next time that Susan logs into Share, she sees in the My Tasks dashlet of her dashboard home page the final task of the workflow which she originally initiated. The task item shows her that her document was approved and completed by Bill. To close out the workflow, Susan clicks on the Task Done button and the task is then removed from Susan's task list:
Future directions for Alfresco workflow
We've seen now how the integration of jBPM into Alfresco allows for the construction of complex workflows. The jBPM engine in Alfresco provides capabilities that rival the BPM capabilities of commercial ECM vendors. However, Alfresco plans to do more.
In May of 2010, Alfresco announced a major change to their roadmap for how they will approach workflow. Alfresco hired the founder and a core developer of the open source jBPM project, Tom Baeyens and Joram Barrez. Rather than pursuing enhancements to the jBPM product, these two developers will be focused on developing a new Business Process Management (BPM) suite called Activiti.
Activiti is an Apache-licensed open source software based on Business Process Modelling Notation (BPMN), a modeling language that was developed to represent the steps of a business process. BPMN is a standard that is maintained by the Object Management Group (OMG). The language was specifically designed to be used both for design and execution.
The Activiti suite includes a BPM engine, graphical design tools, and control consoles.
How Activiti will work alongside Alfresco, as of this writing, hasn't been included as part of the Alfresco roadmap. In the short term, Alfresco continues to fully support and work on completing the integration of jBPM into Share. In the plug-and-play tradition of the Java Spring framework, Activiti, jBPM, and other process control engines may become swappable BPM engine choices in the future. Long term though, Activiti is slated to become the default BPM engine in Alfresco. Activiti is expected to appear in an Alfresco release in early 2011.
More information about Activiti can be found at the Activiti website at http://www.activiti.org/
How does it work?
Let's now look in more detail at how advanced workflow is integrated into Alfresco Share. To make the discussion more concrete, let's focus on the construction of the Review & Approve workflow template that we just walked through above from the user's perspective.
The jPDL code
The corresponding jPDL file for the standard Review & Approve process can be found in this location: tomcat\webapps\alfresco\WEBV-INF\classes\alfresco\workflow\review_processdefinition.xml.
In this file, we see that the internal name for this workflow template is defined to be wf:review:
<process-definition xmlns="urn:jbpm.org:jpdl-3.1" name="wf:review">
The workflow is then made available to Share via a definition in the tomcat\webapps\share\WEB-INF\classes\alfresco\share-config.xml file.
<workflow definition="wf:review" />
<workflow definition="wf:adhoc" />
Here we see the adhoc and review standard workflows defined. From this configuration, the available workflows for use in Share can be identified and displayed for selection when a new workflow is initiated.
Exposing available workflow templates in the Share interface
configs = scopedRoot.childrenMap["workflow"];
for (var i = 0; i < configs.size(); i++)
// Get workflow definition name from each config item
workflowDefinition = configs.get(i).attributes["definition"];
Monitoring via the Workflow Console
Alfresco provides a tool to monitor the states of the workflow jobs within the system. The Workflow Console is located at a URL similar to http://localhost:8080/alfresco/faces/jsp/admin/workflow-console.jsp.
By running the command show definitions all in the Workflow Console, we can find the names of the installed workflow templates. Here we see that the wf:review workflow template is labeled as jbpm$1. The wf:adhoc workflow is defined as well as some WCF workflow templates, if WCM is installed:
In the advanced workflow scenario that we described above with the users Susan and Bill, we can go into the Workflow Console to check the status of the job. Let's look at the status of the job in the workflow console after Susan has completed her task.
In the console, the first step is to specify which workflow definition we want to query. To do that, we use the command use definition jbpm$1:
Then we can query the workflow ID of the current instance of the workflow.
The jBPM workflow engine manages the states of the workflow and logs all actions. We can use the command show workflow definition jbpm$1 or show workflow definition all to see all workflows:
Here we are interested in examining the entry at the bottom. From the workflow id jbpm$1, we can find the workflow paths for this instance:
This shows us that the workflow instance is at the node marked approved. Using the path id of jbpm$1-@, we can find the task id for the process. To do that, we use the command show tasks jbpm$1-@. The current task for the path is as follows:
Then, we can generate a complete description for that task using the command desc task jbpm$3:
Here we see properties of the Alfresco object content model from the bpm namespace.
Automation is all about making things easier, for both administrators and end users. Alfresco provides tools like rules and workflow that help to do just that. Rules can help simplify tedious tasks. Workflow can help streamline business processes.
In this article, we covered the following topics:
- Some of the limitations of rules and workflow when used with Records Management
- How to define rules and apply them to Alfresco folders
- How to use the jBPM graphical process language for laying out workflow templates
- A scenario for the auto-declaration of records based on Alfresco rules
- A review-and-approve scenario for corporate records that uses Alfresco workflow
At the end of the article, in a 'How does it work?' section, we looked at some of the details for how advanced workflow can both be configured and monitored. In particular, we covered:
- How to configure workflows developed in the jBPM design tool to be recognized and used within Alfresco
- How to use the Alfresco Workflow Console to monitor the state of workflow jobs
- Roles and Responsibilities for Records Management Implementation in Alfresco 3 [article]
- Introduction to Successful Records Management Implementation in Alfresco 3 [article]
- Installing Alfresco Software Development Kit (SDK) [article]
- The Deployment Feature of Alfresco 3 [article]
- Advanced Collaboration using Alfresco Share [article]