Data source error handling in data pages
Data source errors occur during the execution of a data source that cause it to return incorrect, flawed, or missing data.
Point at which errors can occur during execution of a data source
Examples of data source errors include:
- 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 load or on the external system
When a data source error occurs in any data source other than an activity or data transform, the page property pyErrorPage is added 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. It contains the following information:
| Rule | Description |
|---|---|
| .pyStatus | The status when the data source finishes processing. If an error occurs, its value is Fail. |
| .pyStatusMessage | A message about the error that was encountered during data source processing that forced it to stop. This message is informative and can be made into a page message shown to users as an invocation error. This is also the value that is put into the default page message added on error. |
.pyStatus and .pyStatusMessage are always populated on error and can be used with any data source. When the source type is a connector of type SOAP, SAP, or dotNet, and the error was caused by a SOAP fault, the following properties are also populated:
| Rule | Description |
|---|---|
| .pyFaultCode | Contains the code from the SOAP fault. See the W3C page on SOAP Fault Codes for more information. |
| .pyFaultReason | Contains an explanation of the issue causing the SOAP fault and is intended to be shown to users or put in a message. See the W3C page on SOAP Reason Elements for more information. |
| .pyFaultDetail | Contains details from the SOAP fault, if provided, including application-specific error information. See the W3C page on SOAP Detail Elements for more information. |
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:
| Rule | Description |
|---|---|
| .pxMessageSummary.pxErrors | When the data page has messages, this page list contains the message details, one page per message. The property .pyDescription contains the message. If the message is attached to a property, the property .pyLabel contains the property reference. |
| .pyInvocationException | If an error occurred because of an exception thrown during data source processing, this property contains the exception Java object. This property is only populated if the connector source type is SOAP, SAP, dotNet, or Java. |
Handling data source errors
Error handling should be done in the response data transform of a data source. The response data transform is executed after the data has been obtained from the data source, and maps part or all of the information returned from the data source to the data page.
When making a new response transform, several error handling actions are added automatically, as displayed in the following example:
Example of a new response transform with automatically generated error-handling actions
A reference to a when rule, pxDataPageHasErrors, is already included, and a place to put error handling logic is nested beneath it. This when rule is the primary tool for conditionally executing data source error handling logic in the same way that you use hasMessages for handling invocation errors.
To use the default error-handling setup, right-click the when step and click Enable. Then, add your error-handling logic in the nested steps below. You can also add it in a separate data transform that can be used across multiple data sources and call it from the nested steps.
When a response data transform is specified and the data source class matches the data page class, enable Run on data page. This executes the response data transform directly on the data page rather than on the Data Source page, saving the memory and processing cost of an unnecessary page and mappings.
Example of a response data transform with Run on data page enabled
Examples of handling data source errors
Pega 7 provides several tools for handling data source errors. A good place to start is the data transform pxErrorHandlingTemplate. This data transform has sample actions that you can use for common data source error-handling tasks, including:
- Read page messages on the data page
- Clear page messages from the data page so it does not stop work processing
- Throw an invocation error by adding page messages so case processes pick it up (remember to catch and handle it in your case layer)
- Output messages to the system log
- Send an email to a system administrator or other stakeholder
You can either copy the logic from the template into your response data transform or save the template to your class and ruleset to create your own error handling transform that can be reused across sources. All rows start in a disabled state, so remember to right-click and enable actions that you want to use and customize.
You can also pull in data from a different data page instead of using the normal DataSource page when it has errors. Examples of this include:
- Referencing another data page to pull data from an alternative data source
- Referencing another data page with the same data source to use for retry
Advanced data source error handling
It is possible to create a reusable error handling data transform that works across all data sources or uses the post-load activity to handle errors in a way that isn’t possible from a data transform. To do this, you might need to know which data source was used to conditionalize actions or messages.
In addition to pyErrorPage, all data pages have an embedded page property called pySourcePage. This property contains up to five properties that provide detailed information about the data source that is used to load the data page:
| Rule | Description |
|---|---|
| .pySourceType | Specifies one of the following source types: Connector, Report Definition, Lookup, Data Transform, or Activity. |
| .pyConnectorType | If the source type is connector, this rule specifies the type of connector. |
| .pySourceName | Specifies the identifier of the connector, report definition, data transform, or activity rule used as the data source. This is empty for lookup data sources, because they do not use a rule. |
| .pySourceClass | Specifies the Applies To class of the connector, report definition, data transform or activity rule used as the data source. For lookup data sources, this is the identifier of the class used for the lookup. |
| .pySourceNumber | Specifies the index of the data source on the data page form at the time of load. The topmost source is 1, and the indexes increase going down the form. |
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 executed.
Activity data sources
If you use an activity as your data source, your error-handling options are fewer. However, several options are available in Pega 7.1.8 that make error-handling in activities easier:
- pyErrorPage is created and added to the step page on error whenever a Connect-* method is used to call a connector. It has the same information described in Data Source Errors. Therefore, you can use the when rule pxDataPageHasErrors against the step page of the Connect-* step to check if there is an error.
- 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 figure out if an error occurred and what went wrong. You can still use the when rule pxDataPageHasErrors against the step page that was used to call pxRetrieveReportData to determine if an error occurred, or you can use the when rule hasMessages.
- Lookups performed by using obj-open steps do not create a pyErrorPage. No error messages are displayed, and you cannot use the when rule pxDataPageHasErrors here to check for errors. Instead, use the when rule StepStatusFail. You also need to use the function
@Utilities.getWorstMessage()to determine what went wrong and use the methodActivity-Clear-Statusto clear the fail status, if necessary (for example, if you intend to handle the error by performing a lookup on a different class instead).