Creating Custom Workflows

October 8, 2024

Introduction

Jahia DXP module that makes it possible to deploy workflow definitions using OSGi services and descriptors.

Reference implementation

Jahia's schedule-publication-workflow is an Open-Source module using workflow extender to deploy custom workflow definitions.

You can refer to its source code for a reference implementation.

Eclipse BPMN2 modeler

You can use Eclipse BPMN2 modeler to edit new/existing workflows:

  1. Download Eclipse IDE at https://www.eclipse.org/downloads/ and install it.
  2. Launch Eclipse IDE and go into Help -> Install New Software...
  3. Search for "BPMN2", select "Eclipse BPMN2 Modeler" and click "Next". Follow the steps to install the modeler extension
  4. You should now be able to open and edit BPMN2 files

This workflow extender will automatically transform any BPMN2 edited with the Eclipse BPMN2 Modeler to be compatible with Jahia's embedded workflow engine (jBPM 6.0). You will see log entries such as the following, indicating that the file is being transformed at deployment time:

2020-11-29 21:03:13,659: INFO  [JBPMBundleProcessLoader] - Found OSGi workflow processes to be deployed.
2020-11-29 21:03:13,659: INFO  [JBPMBundleProcessLoader] - Found OSGi workflow process bundle://198.11:0/org/jahia/modules/workflows/scheduled/default-workflow.bpmn2. Updating...
2020-11-29 21:03:13,668: INFO  [JBPMBundleProcessLoader] - Found workflow definition to transform to legacy format: bundle://198.11:0/org/jahia/modules/workflows/scheduled/default-workflow.bpmn2
2020-11-29 21:03:13,668: INFO  [JBPMBundleProcessLoader] - Adjusting schema locations...
2020-11-29 21:03:13,668: INFO  [JBPMBundleProcessLoader] - Removing xsi:anyType attribute on element /bpmn2:definitions/bpmn2:process/bpmn2:extensionElements/drools:import
2020-11-29 21:03:13,669: INFO  [JBPMBundleProcessLoader] - Removing xsi:anyType attribute on element /bpmn2:definitions/bpmn2:process/bpmn2:userTask/bpmn2:extensionElements/drools:onExit-script
2020-11-29 21:03:13,669: INFO  [JBPMBundleProcessLoader] - Removing xsi:anyType attribute on element /bpmn2:definitions/bpmn2:process/bpmn2:userTask/bpmn2:extensionElements/drools:onExit-script/drools:script
2020-11-29 21:03:13,669: INFO  [JBPMBundleProcessLoader] - Removing xsi:anyType attribute on element /bpmn2:definitions/bpmn2:process/bpmn2:task/bpmn2:extensionElements/drools:onEntry-script
2020-11-29 21:03:13,669: INFO  [JBPMBundleProcessLoader] - Removing xsi:anyType attribute on element /bpmn2:definitions/bpmn2:process/bpmn2:task/bpmn2:extensionElements/drools:onEntry-script/drools:script
2020-11-29 21:03:13,669: INFO  [JBPMBundleProcessLoader] - Removing xsi:anyType attribute on element /bpmn2:definitions/bpmn2:process/bpmn2:task/bpmn2:extensionElements/drools:onExit-script
2020-11-29 21:03:13,669: INFO  [JBPMBundleProcessLoader] - Removing xsi:anyType attribute on element /bpmn2:definitions/bpmn2:process/bpmn2:task/bpmn2:extensionElements/drools:onExit-script/drools:script
2020-11-29 21:03:13,670: INFO  [JBPMBundleProcessLoader] - Moving property definitions to start of process definition...
2020-11-29 21:03:13,671: INFO  [JBPMBundleProcessLoader] - Adding drools:taskName="Check date valid" to element /bpmn2:definitions/bpmn2:process/bpmn2:task
2020-11-29 21:03:13,672: INFO  [JBPMBundleProcessLoader] - Saving transformed BPMN2 file to /Users/loom/java/deployments/jahia-8.0/tomcat/temp/default-workflow6943343967398990743.bpmn2...
2020-11-29 21:03:13,901: INFO  [JBPMBundleProcessLoader] - ...workflow processes deployed.

Available built-in task names

The name that is given to a task is directly associated with built-in tasks available in the Jahia DXP. Here is a list of available tasks:

  • "Lock node"
  • "Unlock node"
  • "Custom lock node"
  • "Custom unlock node"
  • "Add label"
  • "Send mail"
  • "Publish node"
  • "Unpublish node"
  • "Set node property"
  • "Call remote publish"
  • "Execute remote publish"

Custom work item handlers

Tasks are implemented in Java using WorkItemHandler implementations. It is possible for an OSGi workflow module to add its own work item handlers.

Here's an example of an OSGi WorkItemHandler implementation:

@Component(immediate=true)
public class CheckDateWorkItemHandler implements WorkItemHandler {

    private static final Logger logger = LoggerFactory.getLogger(CheckDateWorkItemHandler.class);
    private static final String TASK_NAME = "Demo";

    private WorkflowService workflowService;

    @Reference
    public void setWorkflowService(WorkflowService workflowService) {
        this.workflowService = workflowService;
    }

    @Activate
    public void start(BundleContext bundleContext) throws Exception {
        logger.info("Registering custom work item handler {}", TASK_NAME);
        JBPM6WorkflowProvider workflowProvider = (JBPM6WorkflowProvider) workflowService.getProviders().get("jBPM");
        workflowProvider.registerWorkItemHandler(TASK_NAME, this);
    }

    @Deactivate
    public void stop(BundleContext bundleContext) throws Exception {
        logger.info("Un-registering custom work item handler {}", TASK_NAME);
        JBPM6WorkflowProvider workflowProvider = (JBPM6WorkflowProvider) workflowService.getProviders().get("jBPM");
        workflowProvider.unregisterWorkItemHandler(TASK_NAME);
    }

    @Override
    public void executeWorkItem(WorkItem workItem, WorkItemManager workItemManager) {
        logger.info("executeWorkItem");
        Map<String,Object> results = new HashMap<>();

        final Map<String, Object> vars = workItem.getParameters();

        results.put("hello", "world");

        workItemManager.completeWorkItem(workItem.getId(), results);

    }

    @Override
    public void abortWorkItem(WorkItem workItem, WorkItemManager manager) {
        logger.info("abortWorkItem");
    }
}

The above code registers a new work item handler that will be mapped to the task name "Demo".