Integration is unavoidable in enterprise Pega applications. External systems hold data that your application needs – customer records, product details, policy information. Every connector you build deserves some architectural thought before you start configuring rules.
Here are five best practices I apply every time.
1 – Decide Your Integration Layer Placement
Before creating any connector, decide where the integration class layer belongs in your application stack.
If the external data is specific to one application, the integration layer goes at the application level. If the data is reusable across multiple applications in the same division, put the INT layer at the division level. If it can be reused across the entire organisation, put it at the org level.
The same logic applies to your data layer. Where you place these layers determines how easily they can be reused – or deliberately kept isolated.
2 – Keep Integrations Modular
Do not dump all your connector rules into org-level rulesets. Keep the org layer thin – logos, skin, shared constants. Your connectors belong in dedicated rulesets.
If a set of connectors to the same external system could be reused across multiple applications, consider packaging them as a component application. Other teams can then take the component without needing to rebuild the connectors from scratch.
This is the kind of thinking that separates a well-structured Pega programme from one that becomes a maintenance burden over time.
3 – Always Use a Data Page to Call Your Connector
Pega recommends this and I agree completely. Wrap every connector invocation in a data page.
A data page creates an abstraction layer over the data source. If the external system changes, if the data moves to your own database, or if the connector needs to be swapped out – you change the data page configuration. Everything that references the data page remains untouched.
The data page also handles caching, which means you are not hitting the external system on every single call. And the response data transform in the data page is the right place to do your INT-to-data mapping.
4 – Never Hard-Code URLs or Configuration in Connector Rules
URLs, authentication profiles, timeout values – none of these belong hard-coded in your connector rule. They change between environments.
Use Pega’s App Settings rule to define these values per production level. Then reference them using the out-of-the-box data page that retrieves application settings directly. You do not need a custom data page, custom data transform or custom properties for this. The out-of-the-box approach is cleaner and avoids creating tight dependencies when you try to reuse connectors across applications.
This applies to authentication profiles and timeouts as well – not just URLs.
5 – Design Error Handling From the Start
Connector errors fall into two categories.
Transient errors – network blips, temporary unavailability – tend to resolve themselves. Design a retry mechanism for these. Queue the failed request and retry after a delay.
Permanent errors – record not found, invalid request, authentication failure – need explicit handling in your connector invocation logic. These are often valid business scenarios that need to be surfaced to the user or handled through a different process path.
Error handling is not an afterthought. Design it alongside the happy path. The external system will fail at some point, and how your application responds defines whether it degrades gracefully or breaks badly.
Watch the Full Discussion
In the video below I walk through all five best practices with examples from real enterprise application structures – including how to decide on integration layer placement and how to use App Settings correctly for dynamic URL referencing.
These five points are what separates a well-designed Pega integration from one that causes problems at scale. Worth revisiting every time you start a new connector story.
