Read more about this book      

(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.

Another area that is lacking in the 3.3 release is the availability of client-side JavaScript APIs for automating Records Management functions. The implementation of Records Management exposes many webscripts for performing records functions, but that same records functionality hasn’t been exposed via a client-side JavaScript API.

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.

Alfresco rules

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.

If the standard actions aren’t sufficient to perform the desired task, an alternative is to write a custom server-side JavaScript that can be attached as the action to a rule that will be run when triggered. The complete Alfresco JavaScript API is available to be used when writing the custom action.

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:

Auto-declaration example

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
  cm:content)
var fPieces = document.qnamePath.split('/');
fName =fPieces[fPieces.length-1].substr(3);
// Remember the ScriptNode object for the parent folder being filed
  to
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
  Correspondence";
var filePlan =
  companyhome.childByNamePath("Sites/rm/documentlibrary");
var recordFolder = filePlan.childByNamePath(destLocation);

// Add aspects needed to turn this document into a record
document.addAspect("rma:filePlanComponent");
document.addAspect("rma:record");

// Complete mandatory metadata that will be needed to declare as a
  record
document.properties["rma:originator"] = document.
properties["cm:creator"];
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() + '-' +
  idStr;
document.save();
document.move(recordFolder);

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",
  props );
stubDoc.content = "This file is now under records management
  control:n " + recordFolder.displayPath + '/' + fName;
// Make a reference to the original document, now a record
stubDoc.addAspect("cm:referencing")
stubDoc.createAssociation(document, "cm:references");
stubDoc.save();

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.