How to Implement a Custom Workflow

This documentation page is outdated and currently under review.

Overview

A custom workflow in Bloomreach Content consists of several required components:

An interface that extends org.hippoecm.repository.api.Workflow.
An implementation of that interface, typically extending org.hippoecm.repository.ext.WorkflowImpl.
A workflow category configuration, usually defined in a YAML file. This configuration determines when the workflow is available, based on the node type and the user's role.
A CND file to define any additional document properties, along with a corresponding YAML namespace definition.

Enabling Workflow Actions in the CMS UI

To make the custom workflow accessible from the CMS user interface, you must create a menu plugin. This example assumes a plugin named FeaturedWorkflowPlugin is available.

Example: Custom Workflow Module Structure

A typical custom workflow module includes the following files:

.
|____pom.xml
|____src
| |____main
| | |____java
| | | |____com
| | | | |____mycompany
| | | | | |____FeaturedWorkflow.java
| | | | | |____FeaturedWorkflowImpl.java
| | |____resources
| | | |____hcm-config
| | | | |____categories.yaml
| | | | |____configuration.yaml
| | | | |____featured.cnd
| | | | |____namespace.yaml
| | | |____hcm-module.yaml

Defining the Custom Workflow Interface

src/main/java/com/mycompany/FeaturedWorkflow.java

package com.mycompany;
import ...

public interface FeaturedWorkflow extends Workflow {

    void feature() throws WorkflowException, RepositoryException,
                          MappingException, RemoteException;
}

The FeaturedWorkflow interface defines a single workflow action, feature. All workflow interfaces must extend org.hippoecm.repository.api.Workflow.

Implementing the Custom Workflow

src/main/java/com/mycompany/FeaturedWorkflowImpl.java

package com.mycompany;
import ...;

public class FeaturedWorkflowImpl extends WorkflowImpl
                                     implements FeaturedWorkflow {

    public FeaturedWorkflowImpl() throws RemoteException {
    }

    public void feature() throws WorkflowException, MappingException,
                                 RepositoryException {
        getNode().setProperty("featured:isFeatured", true);
    }
}

FeaturedWorkflowImpl implements the FeaturedWorkflow interface and extends WorkflowImpl. The feature action sets the boolean property featured:isFeatured to true on the associated node. This example does not provide an action to reset the flag to false.

Note: The boolean property is not part of the document's default properties. You must define it explicitly.

Defining the CND File

Properties that the workflow persists must exist in the repository. Define them using a CND file. You can use an existing property, but ensure there are no conflicts with other uses. For a self-contained workflow, define a separate namespace and mixin node type.

src/main/resources/hcm-config/featured.cnd

<jcr='http://www.jcp.org/jcr/1.0'>
<nt='http://www.jcp.org/jcr/nt/1.0'>
<mix='http://www.jcp.org/jcr/mix/1.0'>
<hippo='http://www.onehippo.org/jcr/hippo/nt/2.0'>
<featured='http://www.mycompany.com/featured/nt/1.0'>

[featured:featured] mixin
- featured:isFeatured (Boolean) = 'false' mandatory autocreated

This CND defines the featured namespace with the URI http://www.mycompany.com/featured/nt/1.0. The mixin node type featured:featured contains a boolean property featured:isFeatured, which defaults to false, is mandatory, and is autocreated. Any document with this mixin will have the property available.

To register the CND file in the repository, use the following YAML definition:

src/main/resources/hcm-config/namespace.yaml

definitions:
  namespace:
    featured:
      uri: http://www.mycompany.com/featured/nt/1.0
      cnd: featured.cnd

Configuring the Workflow Manager

src/main/resources/hcm-config/configuration.yaml

definitions:
  config:
    /hippo:configuration/hippo:workflows/featured:
      jcr:primaryType: hipposys:workflowcategory
      /featured:
        jcr:primaryType: frontend:workflow
        hipposys:classname: com.mycompany.FeaturedWorkflowImpl
        hipposys:display: Featured workflow
        hipposys:nodetype: featured:featured
        hipposys:privileges: ['hippo:editor']
        /hipposys:types:
          jcr:primaryType: hipposys:types
        /frontend:renderer:
          jcr:primaryType: frontend:plugin
          plugin.class: com.mycompany.FeaturedWorkflowPlugin

This YAML defines a workflow category named featured. When imported, it creates the workflow category if it does not exist, or adds children if it does. The child node featured of type frontend:workflow specifies that the workflow is available in the CMS UI.

hipposys:nodetype specifies the node type the workflow applies to. In this example, it is set to the mixin node type featured:featured.
hipposys:privileges defines the required user role, here hippo:editor.
hipposys:classname specifies the workflow implementation class.
hipposys:display sets the display name in the UI.
plugin.class under frontend:renderer specifies the plugin used for the workflow button in the CMS UI.

To support multiple plugins for the same workflow, use frontend:plugincluster instead of frontend:plugin for the sub-node.

Enabling the Workflow in the CMS Editor

To make the workflow category available in the editor, add it to the list of categories in the editor configuration:

src/main/resources/hcm-config/featured.yaml

definitions:
  config:
    /hippo:configuration/hippo:frontend/cms/cms-preview/workflowPlugin:
      workflow.categories:
        operation: add
        type: string
        value: [featured]

This configuration adds the featured workflow category as a new menu in the document viewer.

To localize the workflow menu label, use the following YAML example:

src/main/resources/hcm-config/translations.yaml

definitions:
  config:
    /hippo:configuration/hippo:translations/hippo:workflows/en:
      featured: Featured Workflow
    /hippo:configuration/hippo:translations/hippo:workflows/nl:
      featured: Aanbevolen

This provides English and Dutch translations for the workflow menu label.