Error handling from node - guidelines?

I am using Camunda Platform more and more for my Node/Express application, and I enjoy it more and more! Thanks btw for the help provided on this forum!

I would like to let users (who model workflows, and let them run in the background thanks to Camunda) have access to some reporting and notifications (email) when errors occur. It could be for instance:

  • errors due to syntax errors in the scripts they write (for Javascript Script tasks), which happen when the process def is deployed to Camunda.
  • errors during execution, which are in most cases thrown by taskService.handleBpmnError from the camunda-external-task-client-js npm package.

I have read the “error handling” section of the user guide, but I am a bit confused on the best approach I should take. Would you please have some guidelines, or a link to some further documentation/tutorial that could help? (on of my needs would be if I want to notify by email when an error occurs).

Also, I would like to report the error messages produced by Camunda, but with the opportunity to “simplify” them a bit. For instance, by removing all the Java-language related stuff (e.g. stack trace). Ideally, I would like to be able to relay on error codes, and object IDs (such as activity IDs where the error occurred) to present a business-friendly message - possibly translated to languages other than English (Spanish, French, …). It looks to me that the error messages are kind of hard-coded, which would make this task difficult, if not impossible, but maybe I have missed something?

Many thanks for your help on any of these 2 questions!

Unfortunately no help so far, but I could make some progresses by myself, which I am happy to share here.

  1. Errors due to syntax errors in script tasks: it looks like 2 cases may happen:

1.a) if the error occurs in a task which is “directly” linked to the Start event (e.g. no timer in between), then it can be retrieved from the /process-definition/id/start API as a 500 error status, with a message like:

Cannot instantiate process definition process-12:8:624beaf8-4661-11ec-b7c8-0242ac110002: Unable to evaluate script while executing activity 'Event_1ydqfuy' in the process definition with id 'process-12:8:614beaf8-4661-11ec-b7c8-0242ac110002':org.graalvm.polyglot.PolyglotException: ReferenceError: sdfgdfsdfg is not defined

1.b) if the error occurs later (e.g. after a timer has ellapsed, following the Start event), then the Camunda console logs an exception:

javax.script.ScriptException: org.graalvm.polyglot.PolyglotException: ReferenceError: sdfgdfsdfg is not defined

AND an incident is created:

Unable to evaluate script while executing activity 'Event_1ydqfuy' in the process definition with id 'process-12:8:614beaf8-4661-11ec-b7c8-0242ac110002':org.graalvm.polyglot.PolyglotException: ReferenceError: sdfgdfsdfg is not defined

  1. Errors occurring in external tasks (in Node/Express): then handleFailure with retries=0 causes an incident to be created, which can then be accessed from the REST API and reported to the user.

All this said, I can reformulate my question more accurately:

  • For 1.a) and 1.b) : is there a clean way to parse this error message to extract the relevant information to build a user-friendly message (especially: without the Java exception class)?

  • What happens when an error occurs in a process instance launched by a signal (this should be a case 1.c) and how to handle the error in that case?


1 Like

Hey @bfredo123 ,

The behavior where an error occurs (return 500 from a start REST call or later in the Camunda console) is based on the transaction behavior of Camunda. When an error occurs Camunda always rolls back to the last transaction point and the error is displayed there. I think it can be worth looking at the transaction boundaries and how you can set them in the model if you need some.

In general to your question 1a and 1b: I think before deploying to Camunda, Processes and Scripts should be tested. This said the error should not occur during runtime due to missing testing. Are you using inline script or external resources to write your Script tasks? I would recommend to externalize the script. So it is not saved directly to the XML but just referenced. When the user then writes the script you can use all known frameworks for testing JavaScript before you allow them to deploy the script.

If missing variables causes errors, it could be a solution to define input and output mapping for your variables for certain tasks.

So generally speaking I think it is not a good idea to restore the Camunda error message to the person that is responsible to write the JavaScript task. If you still want to due it and exclude the Java logic from the error message, I think you could parse the message. For example you can get the incident via REST. You could change the message and then send it towards a user or display it somewhere for the user.

I am not sure about your last question. Do you mean a Signal BPMN event? If the signal starts a process instance in general the error handling remains the same. Maybe you can elaborate on that a little and I can see if I can help.

Hope this already helps. Cheers


Thank you so much for this answer. I have learnt a lot about “transaction boundaries”!

Regarding 1a and 1b: this is a bit off-topic, but if you have any specific tool in mind for “frameworks for testing JavaScript”, please let me know!

About parsing the error messages, I fear that it is not robust, because if they are rephrased in a future version of Camunda, then the parsing could fail. And also, I don’t know the comprehensive list of potential messages to handle. Maybe this is a wrong assumption though.

About last question (1c): Yes, I mean BPMN signal events. I throw the event from my JavaScript server with the /signal REST API. As this method returns nothing, I don’t know which process instance(s) are created from the signal, and then I don’t know how to link the potential exception to the instances. By reading the doc about transactions, maybe the solution would be that I make the signal event “asynchronous after/before”, and then an incident would be created in case of such an exception? I will try that.

Thanks again!

Hi @bfredo123,

Why are you not using a messenger instead of a signal? The implementation of the signal is accordingly to the BPMN standard from the OMG. A signal can trigger multiple process instances without knowing which ones are triggered. I think the async after/before will not solve this problem and might make it even more complex.

Unfortunately I am not a JS expert but I am sure you will find something within their community.

Kind regards

Thank you Nele!
Actually I would like to offer the capability that any user-made process is triggered when a specific event happens (e.g. a new business object is created on the server, and one user would like to process 1, 2, 3, or more processes when this occurs). So I thought signals were the way to go, preferably to messages.

Alternatively, I could try, from the JavaScript server, to gather all process-definitions starting with a message event, and then send them all a message when the appropriate event occurs, but I am not sure there is a way to query Camunda to gather all such process definitions, and also, I think it would be more elegant to let Camunda do that for the JavaScript server.

Other ideas welcome! :slight_smile: