Throwing BPMN Errors with JavaScript in Camunda

Using JavaScript to throw BPMN Errors that can be caught by Error Events using Camunda BPM

Camunda’s implementation of BPMN Error Events allows a developer to easily throw a BPMN Error in Java Delegation code. But what is not explicitly written in Camunda’s documentation is that you can throw BPMN Errors which can be caught by Error Events using Scripting languages such as JavaScript and Groovy. This is really useful for when you want to leverage Error Events without having to write and deploy Java Delegation code to the server (Java Delegation code cannot be deployed through Camunda’s REST API).

Lets look at a simplified example:

BPMN Error Events are meant to capture serious events in a process. Camunda often defines Error Events as capturing Business errors rather than Technical errors. An example of a business error could be an ‘Out of Stock Item was requested’, ‘Shipping an item will take longer than a pre-defined SLA’, ‘Resolving a service request will exceed the mandated SLA’ (such as a Access to Information Requests), and ‘systems are down, requiring special intervention in the process’. In our example a signature is being validated and a problem is identified.

The Start Event captures some information with a signature, a Script Task is then executed to validate the signature, and if the signature is found to be invalid, a review signature User Task is generated. If the signature is valid, then a User Task is generated to process the request.

If we did not use Error Events, the process may look like:

Now imagine this in a larger, more complicated BPMN process, with the possibility of multiple Error Events attached to tasks, and you will see a process becoming ever more complex to build, maintain and most importantly, understand without Error Events.

At DigitalState, we work with governments on their business processes, especially when using DigitalState’s Platform for Digital Public Services. What we see everyday is that Governments have a lot of services, some are simple and many are complex. When those services are broken down into their respective BPMN processes, even a small local government can end up with thousands of BPMN processes representing the business processes that make up the politics and bureaucracy of the government. This is not a result of governments being overly complex or overly bureaucratic, it is the result of governments having to manage and deliver so many different services to citizens, businesses, residents, and tourists. So it tends to be very important for governments to have the ability to quickly and easily build and deploy BPMN processes including any with BPMN Error Events, without having to modify the BPMN Server. Our goal is that we only have to deploy the new or updated process, and any related external scripts and forms, using the Camunda REST API.

So how do we do this? Thankfully we can throw BPMN Errors that are caught by Error Events using scripting in Camunda.

Throwing BPMN Errors with JavaScript

See the Camunda Error Event documentation for all of the different locations that Error Events can be attached.

In this example we attach the Error Event to a Script Task.

The Script Task has the following Configuration:

ScriptFormat: JavaScript
Script Type: Inline Script
Script:
var sigValidity = execution.getVariable(“SignatureValidity”);
if ( sigValidity == true ) {
 execution.setVariable(“SignatureAcceptedTF”, true);
} else if ( sigValidity == false) {
 throw new org.camunda.bpm.engine.delegate.BpmnError(“SignatureError”);
}

Result Variable: scriptOutput

This is a standard configuration of a script task, with inline JavaScript, but there is a “special” line:

throw new org.camunda.bpm.engine.delegate.BpmnError(“SignatureError”);

This line throws a JavaScript error using the org.camunda.bpm.engine.delegate.BpmnError() class. See the BpmnError() JavaDocs for more information about this class. In this example the Error Code is “SignatureError”. The error code is what the Error Event will catch and be returned in the Error Event’s Error Code Variable.

Next we configure the Error Event to catch the BPMN Error:

To create a new Error, select the “+” next to the Error field and an Error will be generated.

Next, set the other fields in the properties panel:

Error Name: Signature Error
Error Code: SignatureError
Error Code Variable: errorCodeValue

The Error Code field is what tells the Error Event which BPMN Error to catch. Ensure that your Error Code field matches the Error Code value passed to the the BpmnError() class.

The Error Code Variable field is the name of the process variable that will be created when the error is caught and the variable will contain a String of the Error Code.

You can also catch any/all Errors with a single Error Event, by leaving the Error Event’s Error Code field blank.

Throwing a BPMN Error with Groovy

For quick reference, if you are interested in how to throw a BPMN Error in Groovy, it is nearly identical to Javascript:

Example of throwing a BPMN Error with Groovy:

def sigValidity = execution.getVariable(“SignatureValidity”);
if ( sigValidity == true ) {
 execution.setVariable(“SignatureAcceptedTF”, true)
} else if ( sigValidity == false) {
 throw new org.camunda.bpm.engine.delegate.BpmnError(“SignatureError”)
}

Conclusion

Throwing and catching BPMN Errors using JavaScript (or Groovy), is a easy way to leverage the power and convenience of BPMN Error Events without having to write and deploy Java Delegation code. Using scripting to throw BPMN Errors in Camunda, allows a user to build a business process that utilizes BPMN Error Events, and deploy those processes through the Camunda REST API without having to modify Java Delegation code on the Camunda server.

Example Files

You can download the BPMN example files here.