Bizagi provides an interfaces wizard to easily configure invocation to external services in Process-level integration (without the need of programming).
This wizard provides assisted steps to configure the parameter mapping involved in the invocation to these services (Web services or REST services), and how to handle possible business errors in such invocations (a functional error handling different than the handling for technical errors).
When applying application integration in Processes (e.g., verifying some information in an external system, querying customer information, updating payroll information, etc.), the integrated application may respond with a business error.
Business errors refer to messages such as "Customer not found", "Operation could not be completed due to internal reasons...", amongst others.
The interface wizard guides the user in a step by step fashion to evaluate and handle potential business errors in Process flows, and implement accordingly.
You may choose to display distinct specific error messages or rather trigger an Error Event to cause a transition to different workflow state.
Error handling configuration
Error handling is implemented in the last step (Error Handling) of the Interfaces Wizard.
In addition to converting the invocation's response, which is sent by the external application in XML format, certain information contained in this response can also be defined.
This is done in the following way:
1. Decide on the corrective action of the error.
This means specifying either an error message to be thrown, or an Error Event to trigger a transition.
2. Define the error response.
This means creating a decision table to allocate the information found in the XML output when error or exceptions are thrown during the service.
In the following example, we will consider The Credit Process which invokes an external Web service to verify if a customer is blacklisted.
Bizagi should display error messages generated by the external service, if raised (i.e., when the ErrorCode result has a value other than "001").
In the Response Data step, we consult the XML-structured response of the external Web service, ResponseBlackList, which is presented as a table to the left. The table heading, BlackList915, references the name of the external Web Services.
1. Deciding the action for the error
First, we decide on the corrective action to follow in response to a potential error.
The drop-down list of the Action fields present the two options: to display an error message, or to trigger a transition from a BPMN event.
The second option, Perform Adjustment (trigger a transition), will only be enabled if the Process diagram design allows for error handling; specifically, an Error Catch Event must be attached to the boundary of the relevant activity.
When selecting the second option, notice the event takes the same name set by default in the transition (called Perform Adjustments as shown in the image below).
When an exception path is taken, Bizagi will not commit the changes done in that task through the invocation (the mapped output information is disregarded).
Recall that this is so because the exception event is set as an interrupting event which executes a canceling action on the expected/regular path.
For this example, we will choose the Throw Exception option.
Consider the following:
External interfaces must be compensated adequately when these interfaces have been implemented within a Process, to perform modifications on data external to Bizagi through Web Services or component library. Activities that perform reversal for multiple cases must be avoided because the Activity does not know which Activities were completed successfully and which ones must be reversed.
2. Defining the response errors
The message of the generated exception will be found in the XML output when error or exceptions are thrown during the service.
We will save the error response in a given XPath as found in the output parameter of the Web service method.
You can type the XPath definition directly in the white-background field to navigate to the Response XPath field.
Notice when navigating (drilling down) the XML response structure, the slash character (/) precedes the data contained in the returned XML.
The schema of the return XML will be shown in the previous step, Response Data, of the interface wizard, when importing the XML structure definition. In our example the schema contains the following two error handling elements:
ErrorCode: Code of the error that occurred, otherwise it will be empty.
ErrorDescription: Message of the error that occurred, otherwise it will be empty.
In our example, the XPath will be specified as the name of the XML response,ResponseBlackList, followed by the slash character and lastly the element name, ErrorCode, in the XML output: ResponseBlackList/ErrorCode
In this example, the error code from the response is sent in the response as ResponseBlackList/ErrorCode (as seen in the response structure in the Output configuration's previous image).
Click on Add error validation, to validate the information returned in the ErrorCode element.
When the value of the ErrorCode element differs to "001", Bizagi should show the ErrorDescription element contained in that same response structure (as ResponseBlackList/ErrorDescription).
You may also choose to enter a fixed text as the Error message as oppose to the description returned by the service.
Error handling entails that only those exceptions which are configured as functional exceptions explicitly within the Error handling screen, will be interpreted as those eligible to take an alternative path (i.e., that one of an attached Error Event). All other errors, such as those technical exceptions (e.g., an unavailable external service, network issues, or erroneous configuration), will not trigger an alternative path and should be re-attempted instead whenever their execution fails.
If error handling is specified as a Throw Exception action, failed invocations which are set as Asynchronous Activities can be reviewed and monitored in the Administration options at the Work Portal.
To view more information Asynchronous Activities Administration.