Invocation error handling in data pages
Error handling in data pages is a complex problem. Data page errors occur for a variety of reasons, but they all prevent data from being loaded as expected. Invocation errors, one type of data page error, prevent requested data pages from being loaded correctly.
Point at which invocation errors occur and prevent data pages from being loaded correctly
Some examples of invocation errors and their causes:
| Errors | Causes |
|---|---|
Required parameters missing | A data transform tries to modify properties in a case that is based on values from a data page, but the data is not returned when the transform is run because a required parameter is missing. |
Data source error cannot be handled | A flow has a property with automatic data access enabled to copy the data that it needs to proceed in the work item. When the user attempts to proceed to the next step, a data source error that could not be handled at the data layer prevents the user from proceeding. |
Keys not found | A case shows inputs for properties that are used as keys in a property with automatic data access enabled to pull the rest of the data into the case. When the user enters the properties, the data is not returned and an error is shown because the keys were not found in the list. |
When an invocation error occurs, the requested data page instance is marked with page messages that explain the error. In situations where automatic data access for properties is used, errors can occur on a property that refers to data on a data page or a property that copies data from a data page. (For more information, see Load data into a page list property.)
In these situations, the errors might be on the associated data page instance. For example, in the case above where the user uses a key that is not on the data page, the page messages are on the property instead of on the data page itself because the data page was loaded without issues.
Handling invocation errors
You can handle invocation errors by building conditional logic in the case layer. Generally, this logic should be built into whatever rules reference the data page or auto-populated property, such as:
- Flow action post-processing transform or activity
- Data transform or activity referencing the data
- Decision shape followed by a utility step in a flow
You can also defer load activity on a section with a page context of the data page or auto-populated property.
Use these tools to handle the errors in the locations mentioned above:
- Apply the hasMessages when rule to the page that you are trying to use. Any error-handling logic that you include after the when rule is run only in the case of an invocation error and can be used to handle the error.
- When data is pulled into the case from a property with automatic data access enabled, use the function
@(Pega-RULES:Default).getMessagesAll()in the context of that page property to get all invocation errors that occurred as text separated by new line characters. You can then write error-handling logic based on what occurred. - If you use the data page directly, or you want to iterate through all errors on the case, including invocation errors from auto-populated properties, you can iterate through the property .pxMessageSummary.pxErrors in a data transform or activity.
Examples of handling invocation errors
Handling invocation errors is typically use case-specific and each application has its own requirements. The following table lists some common error-handling tasks:
| Task | Procedure |
|---|---|
Preventing case processing from continuing when the data page has an invocation error | Case processing already has built-in validation that prevents users from continuing when the case has errors. To make use of this, use an auto-populated property embedded within the case instead of referencing the data page directly. |
| Retrying a data page | After a data page instance has been loaded, regardless of whether it has errors, it is not cleared or refreshed unless its refresh strategy dictates or it is procedurally removed. To retry the data page, either manually remove the original instance or specify the hasNoMessages when rule in the Do not refresh when field. Re-referencing the data page then results in a retry. The only exception to this is using a property with automatic data access by copy. In this case, remove both the property and the data page from which it is auto-populating to force a retry. |
Calling an alternate data page or data source | To call an alternative data page or data source, add conditional processing that uses a different data page or different parameters if an invocation error occurs. You can do this for items such as data transforms, activities, and sections by using the hasMessages when rule. If the hasMessages when rule returns true for the data page against which it is executed, than an invocation error has occurred. You can conditionally change the parameters so that a different data source is called and retry or use another data page entirely for your logic in that case. An alternative way to conditionalize your logic is to use the hasNoMessages when rule to determine when an invocation has not occurred. |
Notifying an administrator that an invocation error has occurred | The simplest way to do this is to create a data page of class Data-Corr-Email that accepts the error information that it needs to create the email as parameters and fills in the administrator’s information and any other basic details. You can then pass that data page to the function You can even have the data page itself call this function as a part of its load to give yourself the ability to email the administrator no matter where the error occurred, even if you are working with a section or UI rule. |
Moving the case to an administrator’s workbasket | This is best handled by using conditional logic in the flow, or in an activity that assigns it to an administrator. |
Moving the work item into the ConnectorProblem flow and taking additional actions | Data pages prevent the ConnectorProblem flow from being called automatically, but it can still be called manually. This is again best handled by using conditional logic in the flow, or in an activity rather than in a flow or data page. |
A number of other error-handling tasks can be configured, but the same basic pattern applies:
- Use the hasMessages when rule to conditionalize processing based on whether an invocation error has occurred.
- Use additional data pages to handle invocation errors, because data page references can occur anywhere and you want to be able to handle errors wherever they are.
- For error handling that can only be done in the flow or an activity (such as the last two above), make sure that you first reference the data page and conditionalize your processing in a place where you can handle errors.