Error handling service tasks in Identity Manager

This article includes updates for Smart ID 23.10.3.

This article describes service tasks that can be used in Smart ID Identity Manager to provide improved error handling in the BPMN processes. The tasks compensate a problem that occurs when a task inside a process fails and thus causes the complete process to fail. To provide reliable processes it is often necessary to react on failures during process execution with a defined behavior, so that the process can provide it's own error handling. The error handling service tasks provide a simple way to catch every kind of failure and wrap it inside a BpmnError that can be processed by the process.

The project utils provide tasks for different kinds of standard JavaDelegate classes. They all have the same behavior, that is, to invoke a BPMNError if the inner delegation class fails. The tasks can be used in service tasks in BPMN processes by setting the bean name as delegate expression.

Since not all of these tasks are available in the default Identity Manager installation, you have to follow these steps:

Activate the service tasks by adding their bean definitions to custom-beans.xml.
Restart Tomcat so that the new bean definition will be loaded by Identity Manager.
In the service task, set the delegate expression with Identity Manager Admin, after you have uploaded the processes, or edit the delegate expression directly in the BPMN definition with Nexus Activiti Designer. See Set up process in Identity Manager.

Be careful with exceptions! Even if Identity Manager catches the exceptions, Activiti will still try to roll back the process. To avoid this, the part that might throw the exception must be executed asynchronously by setting the attribute async=true in the BPMN definition.

ExceptionCatchingWrapperJavaDelegate

Description

Use this task to wrap a task of type JavaDelegate in order to provide error handling for it. It turns any failure in form of an Exception into a BpmnError with a defined error code setErrorCode. The BPMN process then can react on that BpmnError and initiate its own error handling. The default error code is "ERROR".

Bean configuration in custom-beans.properties

This can be used for every class of type JavaDelegate. To use the wrapper, put the bean name into the property "javaDelegate".

Example:

CODE

<bean id="exceptionCatchingMailJavaDelegate" class="de.nexus.projectutils.action.ExceptionCatchingWrapperJavaDelegate">
  <property name="javaDelegate" ref="sendMailJavaDelegate" />
  <property name="errorCode" value="ERROR_CODE" /> <!-- optional -->
</bean>

Configuration of Service Task

To use this task set the delegate expression in your service task to the following value:

CODE

${exceptionCatchingMailJavaDelegate}

ExceptionCatchingWrapperParameterizedJavaDelegate

Description

Use this task to wrap a task of type ParametrizedJavaDelegate in order to provide error handling for it. It turns any failure in form of an Exception into a BpmnError with a defined error code setErrorCode. The BPMN process then can react on that BpmnError and initiate it's own error handling. The default error code is "ERROR".

This can be used for every class of type ParametrizedJavaDelegate. To use the wrapper, put the bean name into the property "javaDelegate".

Example:

CODE

<bean id="exceptionCertificateCatchingPublicationTask" class="de.nexus.projectutils.action.ExceptionCatchingWrapperParameterizedJavaDelegate" parent="parameterizedTask">
  <property name="javaDelegate" ref="certificatesPublicationTask" />
  <property name="errorCode" value="ERROR_CODE" /> <!-- optional -->
</bean>

Configuration of Service Task

To use this task set the delegate expression in your service task to the following value:

CODE

${exceptionCertificateCatchingPublicationTask}

BpmnErrorThrowingDelegationHandler

Use this task to wrap a task of type DelegationHandler in order to provide error handling for it. It turns any failure in form of an Exception into a BpmnError with a defined error code setErrorCode. The BPMN process then can react on that BpmnError and initiate it's own error handling. The default error code is "ERROR", to change it, see heading "Change Error Code" below.

Bean configuration in custom-beans.properties

There are pre-configured BpmnErrorThrowingDelegationHandler beans for all delegation handlers offered in Identity Manager. They can be used for every service task based on the class ConfigurableJavaDelegate, for example:

ChangeStateJavaDelegate
SaveJavaDelegate
MailJavaDelegate
NumberAssignJavaDelegate
NumberReturnJavaDelegate
...

These are the pre-configured handlers that are available to be used in Service Tasks:

bpmnErrorThrowingDelegateHandler_Mail
bpmnErrorThrowingDelegateHandler_CertRequestMail
bpmnErrorThrowingDelegateHandler_Transfer
bpmnErrorThrowingDelegateHandler_Script
bpmnErrorThrowingDelegateHandler_Save
bpmnErrorThrowingDelegateHandler_Delete
bpmnErrorThrowingDelegateHandler_Production
bpmnErrorThrowingDelegateHandler_NumberAssign
bpmnErrorThrowingDelegateHandler_NumberReturn
bpmnErrorThrowingDelegateHandler_ChangeState
bpmnErrorThrowingDelegateHandler_ChangeStateInCA
bpmnErrorThrowingDelegateHandler_ApplyMapping
bpmnErrorThrowingDelegateHandler_History
bpmnErrorThrowingDelegateHandler_ModifyRoles
bpmnErrorThrowingDelegateHandler_HttpClient

Configuration of Service Task

To use the handlers, set the delegate expression in your service task to the following values.

Example

CODE

<serviceTask activiti:class="de.vps.act.processexecution.mail.MailJavaDelegate" id="Mail1" name="Send Mail">
  <extensionElements>
    <activiti:field name="delegateExpression">
      <activiti:expression><![CDATA[${bpmnErrorThrowingDelegateHandler_Save}]]></activiti:expression> 
    </activiti:field>
  </extensionElements>
</serviceTask>

In the BPMN.IO editor you achieve the same thing by adding a new “Field Injection” with the name “delegateExpression”, the type “Expression” and the value “${bpmnErrorThrowingDelegateHandler_Save}“.

Change error code

The default error code that will be created in the BpmnError is ERROR. If another error code should be used, the bean definition of the delegation handler has to be overwritten in custom-beans.xml.

Example:

CODE

<bean id="bpmnErrorThrowingDelegateHandler_Mail" class="de.nexus.projectutils.delegationhandler.BpmnErrorThrowingDelegationHandler" parent="mailDelegateHandler">
    <property name="errorCode" value="CUSTOM_ERROR" />   
</bean>

No custom error code configured

If there is no custom error code configured and the exception caught is of type BaseTranslatableException, the BpmnErrorThrowingDelegationHandler will use the first element of the arguments array within the exception, if there is one, as the error code.