SCXML Workflow Engine

The SCXML Workflow Engine

Bloomreach Experience Manager provides a SCXML based Workflow engine which uses the open source Apache Commons SCXML 2.0 library and the W3C State Chart for XML (SCXML) specification to execute a workflow definition as a state machine.

Bloomreach Experience Manager specific enhancements and extensions have been added on top of the Apache Commons SCXML library to provide a transparent, easy to use, and customizable integration with our Repository content and Workflow APIs.

A Hippo SCXML Workflow definition, which is an XML document, is loaded dynamically from the Repository, including configurations of custom 'actions' which can be invoked through the SCXML Workflow state machine.

The following screenshots shows a partial view of how and where the  SCXML DocumentWorkflow is defined in the SCXMLRegistry module configuration:

Part of the documentworkflow SCXML definition itself.


The configuration of a custom SCXML action for usage in the documentworkflow definition.


The execution of a Hippo SCXML Workflow state machine is handled through a generic org.onehippo.repository.scxml.SCXMLWorkflowExecutor instance which you can instantiate and configure from within a (now very minimalistic) Workflow implementation. Most if not all workflow operations then can be handled and delegated to the SCXML Workflow state machine by triggering a workflow action, optionally with a payload, using the SCXMLWorkflowExecutor which will raise this as a SCXML event within the state machine.

The Workflow implementation can, and for most cases will need to, pass Workflow specific input data to the SCXML state machine through a custom org.onehippo.repository.scxml.SCXMLWorkflowData interface implementation.

The current state of the SCXML state machine, as well as any optional result data from triggering an event, is communicated back through a org.onehippo.repository.scxml.SCXMLWorkflowContext object.

As the state of a Hippo SCXML workflow state machine typically depends on (JCR) repository content, which is or can be highly volatile, the SCXMLWorkflowExecutor should always first (re)start the SCXML state machine before accessing the SCXMLWorkflowContext or SCXMLWorkflowData to prevent them to report stale information.

More detailed instructions how to setup and use a workflow driven by a SCXML state machine is documented in SCXML Workflow Definition and SCXML Workflow Execution, or how you can extend your workflow with custom SCXML actions in SCXML Workflow Actions And Tasks.

The DocumentWorkflow is implemented using the SCXML Workflow Engine, and can serve as an extensive example. Details of how the DocumentWorkflow is implemented and configured is documented in SCXML DocumentWorkflow.


SCXML Workflow Engine features

Standard features

Conforming to the SCXML specification, a SCXML Workflow definition consists of:

  • one or more states, including compound and parallel states
  • transitions between states
  • executable content to *do* things, like (custom) actions and scripts or with process control elements like if, elseif, else, foreach
  • (external) data access and manipulation

Unsupported features

Other elements of the SCXML specification, like external communications, internal session management or embedded datamodel usage (XPath based or otherwise) are, at least for now, not used nor supported, or only in a limited way (like for the datamodel).

Some of those features might get full support though with future releases of the SCXML Workflow Engine.

Commons SCXML 2.0 features

Additional features specific to Commons SCXML are:

  • Groovy as expression and scripting language
  • pluggable custom (Java) actions usable within the SCXML definition

SCXML Workflow Engine features

The Hippo SCXML Workflow Engine adds to this the following features:

  • SCXML Workflow definitions storage in the Hippo Repository
  • a generic SCXML Workflow execution framework for invoking SCXML state machine
  • state and data communication between the invoking Workflow and the SCXML state machine using SCXMLWorkflowContext and SCXMLWorkflowData
  • a set of base custom SCXML actions for accessing and managing state and data communication through the SCXMLWorkflowContext

Specific workflow implementation features

The DocumentWorkflow is implemented using a SCXML Workflow definition, for which a set of specific SCXML actions are provided which can be used as reference or as building block reused or even extended for other SCXML Workflow definitions.


The W3C SCXML standard and Apache Commons SCXML 2.0

The SCXML Workflow Engine provided by the Hippo Repository is using Apache Commons SCXML 2.0 to execute state machines defined based upon the W3C SCXML specification.

Note that Apache Commons SCXML 2.0 is still a work in progress and not formally released yet.

The roadmap and status of the Apache project towards full compliance with the specification is documented can be followed on their online Roadmap page, with several milestone targets planned towards the final 2.0 release.

For the purpose of executing Hippo Repository workflow operations, so far only a subset of the standard SCXML features is needed (and for now supported), and for this the Hippo Repository uses the stable and tagged Commons SCXML 2.0 milestone 1.

Note also that Hippo is directly involved in and contributing to this Commons SCXML 2.0 roadmap development.

Until the final Commons SCXML 2.0 release is available, Hippo will provide and bundle a stable and verified tagged build of this library with the Hippo Repository.

For the definition of SCXML Workflow state machines, the W3C SCXML specification therefore can be used and followed with regards to the specific subset of features used.

Besides the specification based features, Apache Commons SCXML provides many additional capabilities and a very extendable API, which makes it especially useful for implementing custom state machine progressing.

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?