The use of Client Side Human Services (CSHS) continues to become more attractive as IBM incrementally improves the tooling for and implementation of them. Current differences in features and capabilities between Heritage Human Services (HHS) and CSHS require adjustments in development practices. One such area that requires adaptation is in managing errors occurring in JavaScript nodes.

Note: The information below is current as of IBM BPM version 8.5.7 CF2017.03.

Managing JavaScript Errors in Client-Side Human Services

Outcomes of Unhandled Errors

JavaScript errors occurring in HHS "Server script" or CSHS "Client-side script" nodes can be particularly troubling because they result in a complete halt of the task. End-users are displayed with a white page with an error message:

HHS 

"Error

Ask the administrator to check the SystemOut.log file for more information to resolve the error. (<Reference String>)"

CSHS

"Error: An error occurred while evaluating the JavaScript in the "<Script Name>" (<GUID>) script task. See your browser console for more information. Correct the JavaScript and try again."

Neither of these outcomes are user-friendly, particularly since an end-user is not going to have the capacity to correct JavaScript. Other than the suggestion to "try again" there also isn't helpful guidance for what a user should do in order to proceed.

Successful error handling is not only important for a good user experience but it also facilitates the ability of support members to help customers and can cut down on the time it takes for development to address issues.

Note that JavaScript errors arising from Coach Views are rarely fatal to a Task. They mayresult in abnormal behavior of Coach components but error messages tend to be silently being logged to the browser's console. They can still have negative impacts on Task performance and the overall process, such as getting stuck in a state where boundary events to exit a coach are unable to fire, but for the purposes of this article we will focus on errors arising from CSHS Client-side script nodes.

The Client-Side Human Service JavaScript Problem

In HHS diagrams, a Server script node can be wired with an Error Intermediate Event:

This paradigm does not exist in CSHS: "Error boundary event" components cannot be attached to Client-side script nodes. While the component's symbol is identical to the HHS's Error Intermediate Event, per IBM BPM documentation, these components are for Service nodes only (meaning that these also cannot be attached to Coach nodes either). Instead, "Global error event handler" components can be placed in the CSHS. These, as their name implies, are designed to catch all errors but can also be configured to catch specific errors. However, these event handlers do not catch client-side JavaScript errors from script nodes or coach views.

IBM's current policy (as of May 2017, IBM BPM version 8.5.7 CF2017.03) is that the error event framework used in CSHS are "targeted to 'business' errors that are modeled in the CSHS or a service." Improvements are scheduled to officially clarify this behavior in IBM's documentation.

Methods for Handling CSHS JavaScript Errors

As Client-side JavaScript nodes are closer to pure JavaScript than ever before, standard error handling paradigms apply. This means developers can, and should, employ try/catch/finally syntax as their main tool for managing JavaScript errors. While this does give a lot of flexibility with regard to how the developer chooses to handle errors, it also potentially complicates outcomes and service diagrams.

As a try/catch/finally script node will complete successfully from the perspective of BPM, the management of the error largely becomes a decision for how to wire the Client-side script node in the diagram. The exception to this is syntax errors which won't be managed by a try block, but these should mostly be found and resolved during development.

1. Wire the node as normal. With proper logging of errors in the catch block of the script, data around the error can be sent to the console log. The downside is that the error ends up nearly invisible to the end user; now instead of the task coming to a complete halt the user may be presented with inconsistent data or task behavior with no understanding of what has gone wrong (nor indication that they should be seeking out help). Simply hiding problems is often not a good choice!
2. Use decision gateways to route error pathways. The decision gateway can evaluate a variable set in the catch block of the Client-side script node. This setup mimics the Error boundary events useable in a HHS.
   
   Error handling gateways can, of course, be routed to any appropriate end point, such as Error end events, Stay on page events, or additional scripts, coaches, and nested services. The particular end point will depend upon your solution, however, it is worth pointing out that routing an error to a coach or nested service designed to function as an error endpoint actually mimics the available functionality of the Global error event handler. The error event handler node can be double-clicked on to open a nested diagram which can include additional variables, scripts, and coaches to manage the error and display information to users. So while it is unfortunate that IBM BPM doesn't currently allow JavaScript errors to hook into this existing framework, nearly identical outcomes can still be implemented.

Considerations

As with any programming endeavor, an evaluation of the pros and cons is required to determine the best method for a given implementation. Since the generic Global error event handler doesn't catch JavaScript errors, designers need to balance the needs to error management from script nodes with the time and complexity of covering error conditions. For example, it may greatly complicate a diagram to have every script node exit path evaluated by a decision gateway. Likewise, having a common nested service for managing script errors may not work for every path.

With that in mind, we suggest keeping in mind two concepts:

1. Add JavaScript error handling wherever feasible. Make sure to minimally focus on critical or risky points in the process but keep in mind future maintainability of the process.
2. Manage errors with a thought towards end users. End users are the ones most likely to encounter bugs in production and yet are typically the least equipped to manage them. Empower your users to help both you and themselves by presenting them with helpful messaging and recovery pathways.

Special Note: We have submitted a Request for Enhancement (RFE) with IBM BPM to enhance user-facing JavaScript error handling. If you would like to support and vote for this RFE please follow this link. 

[EDIT June 2020] RFE is still in Open state but there was an APAR fixed by IBM that partially addresses the request from the RFE. See APAR #JR59749 available starting IBM Business Automation Workflow (BAW) v18.0.0.2 and later versions

Additional Reading: