Error detection configuration
Connectors are used with data pages to read data — such as customer and insurance policy data — from an external system. When a connector is invoked by a data page, error detection identifies and addresses any integration errors. Each connector includes an error handling flow.
Data source errors
Data pages are loaded on demand. Errors may occur when retrieving data from a data source.
Examples of errors include:
- Time out: a source system or database is down
- Invalid request: an invalid authentication or data request
- System error: an error during loading or on the external system
The type of data source that is used to load the data page affects how errors are detected and handled. Data source errors must be handled as part of the data page load mechanism.
When data pages invoke a connector, best practices are to:
- Add error detection to all data pages
- Invoke a reusable error handling data transform to identify and address errors
Note: Pega Platform™ provides a template for a data transform called pxErrorHandlingTemplate, as a reusable error-handling data transform. The pxErrorHandlingTemplate data transform is in the base class.
Error handling logic
Design your error handling logic based on business needs and the types of errors that occur. Three situations to consider are:
- When an error is fixable by the user
- When an error is not fixable by the user, but processing can continue (for example, if the data is not mandatory for the process)
- When an error is not fixable by the user, and case processing must stop
Early error detection
To ensure the best user experience, identify errors as early as possible in the process, with clear error messages explaining to the user what happened and what they should do next. Whenever possible, include an alternate process flow when the case cannot proceed, such as to open a chat for assistance, or send an email to confirm to the user that an error resolution case has been created.
Response data transform
The Connector, Report definition, and Lookup data source options of a data page require a Response data transform. Apply the best practice of checking for errors directly in the Response data transform using a when condition to check for any error messages on the data page. If errors exist, call a separate Error handling data transform.
Error messages
If there is an issue, an error message displays on the clipboard. If the error is correctable by the user, display an error message to explain to the user how to correct it.
Error handling flow
The Error handling flow feature identifies errors that are not detected in a data page or in a data transform. Pega Platform automatically invokes the Error handler flow if the error is not addressed by another mechanism. This feature is always enabled and allows you to implement a process for handling the error. It is typically used when the connector response is not required immediately — for example, when updating a legacy system.
Note: The error handler flow does not run if the error is detected in the response data transform.
You can configure the Error handling flow on the Service tab for the connector. By default, connectors use the standard ConnectionProblem flow. The flow can be copied and customized. You may also choose to create an alternative error handler flow.
When an error occurs, the original flow execution is paused. Control is handed over to the Error handler flow. If the resource is unavailable, a transient error may be preventing processing. If there is no transient error, the connector is retried, and processing continues in a flow called FlowProblems.
The FlowProblems flow either routes the work item to a problem flow workbasket or notifies an operator about the issue.
The operator may:
- Retry the connector
- Resume the flow without retrying the connector
- Restart the initial flow
- Cancel the error handling flow
Note: As a best practice, notify the user about the error, and whenever possible, reroute to an alternate process so that the user is not stuck on the screen waiting for something to happen.
Error handling data transform
The template for the Error handling data transform includes examples of calls to standard utility functions. You can configure the data transform to customize error handling behavior, such as providing more user-friendly error messages.
In the following image, click the + icons to learn more about Error handling data transform template:
Retry a connector invoked from a data page
If the returned error is temporary, give the user the option to retry the connector. To retry the connector, configure the data page refresh strategy:
- Create a when condition that returns true when there are no error messages.
- Configure the Do not reload when setting so that the data page does not reload if there are no error messages.
Note: When more than one system or step of persistency is required, plan your error handling carefully. The error handling in this situation must account for the possibility of an error with any of the individual transactions, the availability of compensating actions (such as rollback APIs) for any transactions that had already completed, and whether the case can proceed and how.
Addressing responses from returned errors
If there is an immediate need for the response to be returned by the invoked service, in addition to providing an error message to the user, you should write the error to the log file. Writing a message to the log file helps you troubleshoot errors. For example, you analyze the log file to identify patterns related to a specific error. In the log message, include details about the connector request to help identify the cause of the error.
Tip: To learn more about the details provided in the error log, see Errors in data sources. In addition to writing the error to a log file, consider generating an email with details about the error to notify the system administrator or another interested party.
Check your knowledge with the following interaction:
This Topic is available in the following Module:
If you are having problems with your training, please review the Pega Academy Support FAQs.
Want to help us improve this content?