Document Workflow

DocumentWorkflow Overview

The workflow for publishable documents is defined by the org.onehippo.repository.documentworkflow.DocumentWorkflow interface. In Bloomreach Content, publishable documents are nodes with the primary type hippo:document and the hippostdpubwf:document mixin. The default implementation is org.onehippo.repository.documentworkflow.DocumentWorkflowImpl.

The DocumentWorkflow is configured with the property hipposys:nodetype set to hippo:handle. Only nodes of type hippo:handle will trigger this workflow. The workflow requires the node to be a hippo:handle. For details on customizing the workflow for specific document types, see the section below. The workflow is only active when the hippo:handle node contains a child node with the same name and that child node has the hippostdpubwf:document mixin. For more information, see the Document Model documentation.

All workflow operations for hippo:handle nodes and their children are combined and exposed through a single DocumentWorkflow. This approach allows you to evaluate and manage the entire state of a document handle as a single state machine.

Enabled Operations and Permissions

The DocumentWorkflow distinguishes between three roles: hippo:author, hippo:editor, and hippo:admin. Each role has access to specific operations. For example, only users with the hippo:admin role can execute the unlock operation, while users with the hippo:author role can use only the requestPublication and requestDepublication operations.

The DocumentWorkflow defines all possible operations, but which operations are enabled depends on the user's privileges. The hints() method returns a map that indicates which operations are currently available for a specific document handle and its child nodes.

• If a user is not authorized for an operation, the hints() method does not include that operation.
• If an operation is not relevant for the current document state (for example, trying to unpublish a document that is not published), the operation is omitted from the map.
• If no value is present for an operation, it is disabled by default.

The return value of the hints() method is a Map<String, Serializable>. For document operations, the value is a Map<String, Boolean>, where the key is the operation name and the value indicates whether the operation is enabled.

The values from hints() are valid only at the time of invocation. Document state or user authorization may change between the time hints() is called and when an operation is executed. The workflow checks permissions again at execution time, so an operation reported as enabled may still fail if the state has changed.

Request Workflow Operations

The DocumentWorkflow manages review and scheduled workflow request operations. State information and available operations for these requests are included in the hints map under the key "requests". The value is a map of type Map<String, Map<String, Boolean>>, where:

• The key is the JCR node identifier (UUID) of a hippo:request node (a child of the handle).
• The value is another map (Map<String, Boolean>) that lists supported request workflow operations and indicates whether each operation is enabled.

To invoke a request workflow operation, you must provide the JCR node identifier of the corresponding hippo:request node as a parameter.

SCXML DocumentWorkflow

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

For technical details and examples based on the SCXML DocumentWorkflow, refer to the SCXML Workflow documentation.

All SCXML state machine definitions are registered at /hippo:configuration/hippo:modules/scxmlregistry/hippo:moduleconfig/hipposcxml:definitions. The document workflow uses the definition named documentworkflow. See SCXML Workflow Execution for information on the semantics of these definitions.

The document workflow is linked to an SCXML definition by name in the workflow configuration. For the document workflow, this configuration is located at /hippo:configuration/hippo:workflows/default/handle/hipposys:config. To use a custom SCXML definition, update this configuration.

Customizing the DocumentWorkflow

You can customize the DocumentWorkflow by modifying its SCXML state machine definition or by creating a new SCXML definition and updating the workflow configuration to use it.

Common customization scenarios include:

• Allowing users with the hippo:editor role to unlock documents locked by other users.
• Registering event listeners that respond to document state changes.

Any changes to SCXML definitions are detected and loaded automatically.

To use a different SCXML definition for specific document types:

1. The workflow definition nodes are orderable and processed in order by the WorkflowManager. The first matching definition is used.
2. The document workflow is configured to operate on hippo:handle nodes with a hippo:document child of the same name. This configuration is located at /hippo:configuration/hippo:workflows/default/handle.
3. Copy the handle node and place the new node above the original in the order.
4. Change the hipposys:subtype property to match your document type.
5. Update the SCXML definition name in the handle's child node hipposys:config to reference your custom SCXML definition.

The DocumentWorkflowImpl class can also use a custom factory class for creating its DocumentHandle model object (of type SCXMLWorkflowData). The factory must implement 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;
}
copy

To configure a custom factory, set the property in the workflow configuration as shown below:

definitions:
  config:
    /hippo:configuration/hippo:workflows/default/handle/hipposys:config:
      documentHandleFactoryClass: my.custom.documentworkflow.DocumentHandleFactoryImpl
copy