Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

This content has been archived and is no longer being updated.

Links may not function; however, this content may be relevant to outdated versions of the product.

Data source error handling in data pages

Updated on May 4, 2020

Data source errors occur during the execution of a data source that cause it to return incorrect, flawed, or missing data.

Data source errors

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:


The status when the data source finishes processing.

If an error occurs, its value is Fail.


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:


Contains the code from the SOAP fault. See the W3C page on SOAP Fault Codes for more information.


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.


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:


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.


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:

Response transform

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 the class of the data source matches the class of the data page, the response data transform is optional, because the data source can be run against the data page directly.

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.

Data sources form

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
Do not attempt to reference the currently loading data page from within the response data transform. This method does not work and can cause errors when you try to load the data page.

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:


Specifies one of the following source types: Connector, Report Definition, Lookup, Data Transform, or Activity.


If the source type is connector, this rule specifies the type of connector.


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.


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.


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.
Error information is captured only for the connector types that are supported as data sources on the data page form. For other, more advanced connector types, you might need to look at the form to see what other error information is available and what properties contain the information.
  • 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 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).

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us