The following figure shows where in the data flow that data source errors can occur:

Causes of data source errors include the following:

• A source system or database is down, and the connection times out.
• A request passed to the external system using the connector is invalid.
• Credentials are invalid or are not authorized to get the data requested.
• An internal system error occurred, either during loading or on the external system.

Information in data source error logs

When a data source error occurs in any data source other than an activity or data transform, the system adds the page property pyErrorPage to the data page. This property contains all error details so that users do not have to track them down across the various error properties and page messages used by connector, report definition, and lookup data sources. The details of a data source error contain the following information:

The system always populates .pyStatus and .pyStatusMessage when an error occurs, and these rules can be used with any data source. When the source type is a connector of type SOAP, SAP, or dotNet, and a SOAP fault causes the error, the following properties are also populated:

Two additional properties are available for more advanced use cases, such as custom connector logic or load activities. These properties can provide additional detail in page messages:

Handling data source errors

You perform error handling in the response data transform of a data source. The response data transform runs after the system obtains the data from the data source. It maps part or all of the information returned from the data source to the data page.

When making a new response data transform, the system adds several error-handling actions automatically, as in the following example:

The response data transform includes a reference to the pxDataPageHasErrors when rule. The nested section beneath the when rule is for entering the error handling logic. The when rule is the primary tool for conditionally running data source error-handling logic. You can conditionally change the when rule parameters to call a different source, and then retry persisting the when rule, or use another data page entirely for the logic to handle data source errors.

Pega Platform provides several tools for handling data source errors. A good place to start is the data transform pxErrorHandlingTemplate. This data transform includes the following sample actions that you can use for common data source error-handling tasks:

• Read page messages on the data page.
• Clear page messages from the data page so it does not stop work processing.
• Return an invocation error by adding page messages, so that case processes pick the error up (remember to handle the error in your case layer).
• Output messages to the system log.
• Send an email to a system administrator or other stakeholder.

Using the default error-handling setup

To use the default error-handling setup, perform the following steps:

1. Right-click the when rule step and click Enable.
2. Add the error-handling logic in the steps nested below the when rule. You can also add the logic in a separate data transform that you can use across multiple data sources and call the transform from the data transform nested steps.

In these cases, selecting the Run response data transform on error check box on the data page is recommended. This runs the response data transform directly on the data page, saving memory and the processing cost of running a redundant page and mappings.

Error-handling data transform that you can reuse across various sources

To create your own error-handling data transform that you can reuse across various sources, you can either copy the logic from the template into your response data transform or save the template to your class and ruleset. All the data transform rows are disabled by default. You must right-click and enable the actions that you want to customize on each row.

When a dataSource page has errors, you can pull in data from a different data page instead, for example, to:

• Reference another data page to pull data from an alternative data source
• Reference another data page with the same data source for retrying

Advanced data source error handling

To create a reusable error-handling data transform that works across all data sources, or uses the post-load activity to handle errors, refer to the data source that was used to conditionalize the actions or messages, and ensure that the actions or messages in the new error-handling data transform are conditionalized in the same way as the data sources.

In addition to the pyErrorPage property, all data pages contain an embedded page property called pySourcePage. This property contains up to five rules that provide detailed information about the data source that the system uses to load the data page. The following table lists the rules:

Unlike pyErrorPage, pySourcePage is always present on loaded data page instances. You can always reference it from your data transforms or activities or view it in the clipboard to see which source was run.

Activity data sources

Using an activity as your data source reduces your error-handling options. However, several options are available in Pega Platform that make error handling in activities easier:

• The system creates pyErrorPage and adds it to the step page whenever a Connect-* method is used to call a connector. pyErrorPage has the same information that is described in the Data Source Errors. Therefore, you can use the when rule pxDataPageHasErrors to verify whether there is an error on the Connect-* step page.

The system captures error information only for the connector types that the data page form supports as data sources. For other, more advanced connector types, you might need to look at the form to see what other error information is available and which properties contain the information. The following are some examples of error information for supported connector types:

• Calls to report definitions that use Rule-Obj-Report-Definition.pxRetrieveReportData do not create a pyErrorPage. You need to continue to look for page messages to see if an error occurred and the root cause of the error. You can still use the when rule pxDataPageHasErrors to compare against the step page that the system used to call pxRetrieveReportData and determine whether an error occurred, or you can use the when rule hasMessages.
• Lookups performed by using obj-open steps do not create a pyErrorPage. The system displays no error messages and you cannot use the when rule pxDataPageHasErrors to check for errors. Instead, use the when rule StepStatusFail. You also need to use the function @Utilities.getWorstMessage() to determine the root cause of the error and use the method Activity-Clear-Status to clear the fail status, if necessary (for example, if you intend to handle the error by performing a lookup on a different class instead).