Errors in data sources
Data source errors occur during the execution of a data source, and cause the data source to return incorrect, flawed, or missing data.
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:
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 occurred during data source processing that forced the processing to stop. This is an informative message that you can use as a page message shown to users as an invocation error. This is also the value that is put into the default page message that the system adds when an error occurs. |
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:
Rule | Description |
.pyFaultCode | Contains the code from the SOAP fault. See Section 5.4.6 SOAP Fault Codes of the W3C recommendations for more information. |
.pyFaultReason | Contains an explanation of the issue causing the SOAP fault that you can show to users or put in a message. See Section 5.4.2 SOAP Reason Element of the W3C recommendations for more information. |
.pyFaultDetail | Contains the details of the SOAP fault, if provided, including application-specific error information. See Section 5.4.5 SOAP Detail Element of the W3C recommendations 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. The system only populates this property if the connector source type is SOAP, SAP, dotNet, or Java. |
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:
- Right-click the when rule step and click Enable.
- 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:
Rule | Description |
.pySourceType | Specifies one of the following source types: Connector, Report Definition, Lookup, Data Transform, or Activity. |
.pyConnectorType | If the source type is a 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 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 methodActivity-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).
Previous topic Use case: Referencing data in a data page by using parameters Next topic Use case: Loading data into a page list property