Nexus' software components have new names:

Nexus PRIME -> Smart ID Identity Manager
Nexus Certificate Manager -> Smart ID Certificate Manager
Nexus Hybrid Access Gateway -> Smart ID Digital Access component
Nexus Personal -> Smart ID clients

Go to Nexus homepage for overviews of Nexus' solutions, customer cases, news and more.


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:

  1. Activate the service tasks by adding their bean definitions to custom-beans.xml.
  2. Restart Tomcat so that the new bean definition will be loaded by Identity Manager.
  3. 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.


Expand/Collapse All

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 it's 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
<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:

${exceptionCatchingMailJavaDelegate}

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
<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:

${exceptionCertificateCatchingPublicationTask}

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

Configuration of Service Task

To use the handlers, set the delegate expression in your service task to the following values, for example:

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

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
<bean id="bpmnErrorThrowingDelegateHandler_Mail" class="de.nexus.projectutils.delegationhandler.BpmnErrorThrowingDelegationHandler" parent="mailDelegateHandler">
    <property name="errorCode" value="CUSTOM_ERROR" />   
</bean>