Document Workflow - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 10. There's an updated version available that covers our most recent release.


Document Workflow

The DocumentWorkflow

The workflow for publishable documents, hippo:document nodes with mixin hippostdpubwf:document, is provided by the  org.onehippo.repository.documentworkflow.DocumentWorkflow.

The DocumentWorkflow provides all operations through the document hippo:handle and is configured (only) on that node type, if it has a child node by the same name with a hippostdpubwf:document. See also the Document Model documentation.

The DocumentWorkflow is configured and operating on the handle node of such documents instead of on the document (and hippo:request) child nodes directly.

All the workflow operations for such hippo:handle and its children are combined into this single DocumentWorkflow.
The benefit is that the whole (workflow) state of a document handle can be evaluated and managed as a single state machine.

DocumentWorkflow hints()

The DocumentWorkflow. hints() method returns the info on all available and enabled/disabled operations for the document handle AND all of its document and hippo:request children.
Only one workflow instance and one call is needed to determine if and how a specific operation can be invoked.

Hippo Request workflow operations

The interaction with and usage of the review and scheduled workflow request operations also has changed to be handled by DocumentWorkflow.

The DocumentWorkflow now provides the state information and which operations are available for these requests through the hints() returned info as a separate map of available actions, per hippo:request, through the hints() under the "requests" hint key.

The returned "requests" value is of type Map<String, Map<String, Boolean>> with as main key the hippo:request child node its JCR node identifier (UUID) and as value a map of enabled or disabled available actions corresponding to the supported request workflow operations (cancelRequest, rejectRequest, acceptRequest).

Invoking one of these DocumentWorkflow request workflow operations requires the corresponding hippo:request node its identifier as parameter.

DocumentWorkflow enabled operations and permissions

The DocumentWorkflow uses three different roles, hippo:author, hippo:editor and hippo:admin, to differentiate specific operations.

For example, only a user with role hippo:admin is allowed to execute the unlock operation, and a user with only role hippo:author may only use requestPublication or requestDepublication of a document.

While the DocumentWorkflow provides access to all these operations, which operations are currently enabled and accessible based on the current user privileges, can and must be evaluated first by checking the information in the hints() returned map.

For each of the currently available operations the hints() method will return the corresponding operation by method name as key, with a Boolean value to indicate if the operation is enabled or disabled.

Only workflow operations with a corresponding Boolean.TRUE value returned by the hints() method will be allowed to be executed.

If no value is returned by the hints() method for a specific operation the current user will not have the required privileges, or the operation is meaningless in the current document state.

Note that even if the hints() method returned a Boolean.TRUE value for a specific operation, there is no guarantee that invoking that operation will succeed or even be allowed anymore.
Before an operation is actually executed the current and overall document handle state is checked again first, as it might already have been changed between an earlier hints() invocation (if done at all) and the invocation of the workflow operation.

SCXML DocumentWorkflow

The implementation of the DocumentWorkflow uses the Hippo SCXML Workflow Engine and a DocumentWorkflow specific SCXML state machine definition.

Further technical details, and plenty of examples (based upon the SCXML DocumentWorkflow) are provided in the related SCXML Workflow documentation.

Customizing the DocumentWorkflow

You can customize the DocumentWorkflow by changing its SCXML state machine definition located at /hippo:configuration/hippo:modules/scxmlregistry/hippo:moduleconfig/hipposcxml:definitions/documentworkflow. Read SCXML Workflow Execution as a starting point for learning about the semantics of these definitions.

For example you may wish to also allow users in the hippo:editor  role to be able to unlock documents in use by other users. To do this, search the definition for where the unlock action is set and change its conditions.

Note that changes are automatically detected and loaded.

The DocumentWorkflow Implementation class org.onehippo.repository.documentworkflow.DocumentWorkflowImpl optionally can leverage a custom factory class for instantiating its (SCXMLWorkflowData type) DocumentHandle model object, implementing the DocumentHandleFactory interface:

package org.onehippo.repository.documentworkflow;

import javax.jcr.Node;
import org.hippoecm.repository.api.WorkflowException;

 * DocumentHandleFactory is an optional factory interface to be used to override the default
 * {@link DocumentHandle} instance creation for the DocumentWorkflowImpl
 * @see DocumentWorkflowImpl#createDocumentHandle(javax.jcr.Node)
public interface DocumentHandleFactory {
     * Factory method to create a DocumentHandle instance
     * @param node The JCR node representing the document handle
     * @return a DocumentHandle instance
     * @throws WorkflowException
    DocumentHandle createDocumentHandle(Node node) throws WorkflowException;

which can be configured as config property on the workflow configuration itself, like this:

<?xml version="1.0" encoding="UTF-8"?>
<sv:node xmlns:sv=""
         sv:name="default" h:merge="combine">
  <sv:node sv:name="handle" h:merge="combine">
    <sv:node sv:name="hipposys:config" h:merge="combine">
      <sv:property sv:name="documentHandleFactoryClass" sv:type="String">
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?