Pega exception handling in connectors

What is exception handling in pega?

As we know connectors are used to communicate with external systems to fetch data and there is a possibility of something going wrong always exists. We can encounter some exceptions/errors during the communication so we need to be ready with the handling strategies. Errors could be temporary/Transient or permanent. Transient errors are temporary errors, do not last long, and can rectify themselves over time.  For example, Connector is unable to connect because the application is temporarily unavailable/restarted.
Permanent errors: Typically due to configuration issues or invalid request, these kinds of error persists until we fix them.

How to do exception handling in pega

exception handling in pega

For Transient errors: Send an alert to end-users that Integration is failed and ask to re-try after some time because these are temporary issues and can be fixed on their own.

For Permanent errors: We need to write those exceptions into the log file so that we can investigate and fix them. Implement a process for the investigation and fixing.

Error handling in connectors in pega

Connectors are invoked from Data pages and Activities. so we can configure exception handling in both the rules by defining a data transform to handle errors. Create a re-usable data transform and use that in both the data page and activity. Pega provides an OOTB data transform template in the base class.
@baseclass.pxErrorHandlingTemplate (it is a Final rule, save as with a different name into our application).

Pega error handling in the data transform


The above Error handling data transform is a standard data transform and we can save as and customize it as per our needs. It has OOTB functions to catch the errors, Log the errors and clear the errors and so. 

We can handle exceptions in below three ways for Integration Connectors.

  1. Data pages - Response data transform.
  2. Activities  - Transition step with JUMP label and data transform.
  3. Connector rule with error handling flow.

Exception handling in data pages

We will invoke a Connector from a data page to read data from an external system. 
To configure exception handling in the data page use response data transform and apply an error handling data transform.
error handling in data pages pega

1. Save As standard @baseclass.pxErrorHandlingTemplate with a different name into your application.

2. Create a response data transform if not existed (by default response data transform will be created by pega and pxErrorHandlingTemplate data transform will be there) and refer to newly created data transform to perform error handling.
pega error handling in data transform

Note: In Standard pxErrorHandlingTemplate data transform all the steps are disabled, so we have to save as with a new name and enable required steps.

3. Enable when rule (pxDataPageHasErrors) and refer newly created data transform to perform error handling in response data transform.
exception handling in data transform in pega

Exception handling in activity

When the connector is invoked from the activity and encounters any errors we can handle those exceptions in activity steps by checking StepStatusFail and using the JUMP label.
We can define our own property-set step/data transform to handle the errors or can use Data transform created for error handling.

exception handling in activityException handling in Connector rule with Error handler flow

If the errors are not detected or handled by Invoking rules (data page or activity), we still handle the exceptions in the Connector rule form in the Service tab. This option is always there and enabled.
Errors are handled by Error handler flow and this flow is not executed if the error is detected in the response data transform or in a transition in an activity.

error handler flow

Standard OOTB Work-.ConnectionProblem flow is the default for all the connectors for error handling.
We can save as and customize or define our new Error handler flow here.
ConnectionProblem flow in pega
When an error occurs original flow execution stops and control goes to Error handler flow (if it is standard Work-.ConnectionProblem flow). 

If the error is due to connection problem means ExceptionType = "" it will be routed to "IncompleteConnections" workbasket for retry. SLA (Work-.RetryConnection) will be executed on the workbasket item and re-try. SLA activity Work-.RetryConnection will be executed and if the connection status is good it will start the ResumeFlow.

If the error is not a transient (resource unavailable) error, Connector will be retired and processing will continue in Work-.FlowProblems flow. FlowProblems flow will route the work item to a Workbasket or to an Operator and can choose below paths:
  1. Restart the initial flow
  2. Retry the connector
  3. Resume the flow without retrying the connector
  4. Cancel the error handling flow


  1. Very useful information. Thanks for sharing. Please keep post.

  2. It only gets invoked when we are using Integrator shape.Correct?
    How in invoke ConnectionProblem Flow if the error are detected in response DT or in a transition in an activity.

  3. Thank for sharing the information. Very useful article

  4. Very informative and useful article.

  5. As said that if the errors are not detected by the invoking rules, pega will invoke error handler flow which is mapped in the connector rule. But my question is how will pega know if the error is handled or not by the invoking rules and invoke error handler flow, as this error handler flow is mapped in the connector rule which already gets executed before it calls the pxhandlerdata transform from the response data transform right?