Understanding invocation errors
Data page errors occur for a variety of reasons, all of which prevent data from loading as expected. Invocation errors prevent requested data pages from loading correctly.
The following figure shows where in the data flow that invocation errors can occur:
The following table lists some examples of invocation errors and their 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 case 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 system marks the requested data page with page messages that explain the error. When you set automatic data access for properties, 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 auto-populated property.
In these situations, the errors might be on the associated data page instance. For example, when 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 loads without issues.
Handling invocation errors
You can handle invocation errors by building conditional logic in the case layer. Generally, you should build this logic into the rules that 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 in a section with the page context of the data page or auto-populated property.
Use the following tools to handle the errors in the locations listed 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 only runs in the case of an invocation error and can be used to handle the error.
- When a property with automatic data access pulls data into a case, use the function
@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:
|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 loads, regardless of whether it has errors, it is not cleared or refreshed unless its refresh strategy dictates clearing or refreshing, 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 copying. In this case, remove both the property and the data page from which it is auto-populating to force a retry.
|Calling an alternative 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 run, then an invocation error has occurred. You can conditionally change the parameters to call a different data source, and retry or use another data page entirely for your logic.
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 then 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 when the page loads 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||Use conditional logic in the flow or in an activity to assign the case 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. Use conditional logic in the flow or in an activity, rather than in a flow or data page.|
Configuring error-handling tasks
You can configure a number of other error-handling tasks, for which you take the same basic approach:
- Use the hasMessages when rule to conditionalize processing based on whether an invocation error has occurred.
- Use additional data pages to handle invocation errors. Data page references can occur anywhere, so you can handle errors wherever they are.
- For error handling that you can only do in the flow or in an activity, as shown in the table of tasks and procedures in the Examples of handling invocation errors section, make sure that you first reference the data page and then build conditional logic into your processing in a place where you can handle errors.