Skip to main content

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

Remediations for Migrating to Pega Cloud

Updated on December 12, 2023


This content applies to On-premises, Client-managed cloud and Pega Cloud environments

Attention: This documentation has been moved to the new documentation site:
This documentation is no longer being maintained. It is out of date and pending deletion. Please update your bookmarks.

Certain features in older Pega applications imposed dependencies on specific deployment options and technology choices that work well with an on-premise data center, but cannot be supported in a cloud operational model.

There may be a number of these “older technology choices” which are implemented in your applications.  Update this functionality to current Pega application features, so your application runs correctly on Pega Cloud.

Some of the older functionality may not become apparent until after you have migrated.  You need to also update those.

The next sections describe some known areas of older versions of Pega applications which will require remediation.  For more information about identifying unsupported functionality and implementing replacement features and functionality, see the Modernization Implementation Guide.

Integration Functionality

Platform integration used to be driven by technology-specific connectors that limited the endpoints and formats of organizational data. While many of those purpose-driven connectors still exist, most organizations are retiring them in favor of newer approaches better suited to today’s fast-changing technology.  In addition, several of the older methods of integration are not totally secure.  

Consequently, Pega Cloud does not support many older connector standards, putting the focus instead on web-based standards that provide a more secure connection.  Integration via Pega Cloud balances technologies to provide you with stable, high-performing, and secure connections to critical business systems.  For more information, see Integrating Pega applications with external systems .

Complete the Integration tab on the Gap Assessment Worksheet to identify integrations present in your application. Note which systems each of these integration rules map to.  Also note any “legacy” integration rules in your application, and replace them with the appropriate Recommended Integration Standards.

Verify that the Connect and Services rules in your application are supported on Pega Cloud, and replace any that are unsupported.  For more information about unsupported integration types and their replacement functionality, see the Modernization Implementation Guide.  

Integrations Involving Date and Time

Evaluate all integrations with external systems to assess how each integration handles time and time zones.  

In particular, check for DateTime data that does not explicitly specify the time zone of the data.  There may be an implicit assumption that all servers are in the same time zone.  This assumption may no longer be valid after migrating to Pega Cloud, because Pega Cloud uses the UTC time zone.

If time zones are not currently being handling correctly, include time zone remediation in your project plan.

Your databases might also have issues with timezone conversion, for more information see the Time Zone Correction heading in Other Things to Consider.

Integration Security

Pega Cloud supports TLS 1.2 and TLS 1.3 for HTTPS connections and provides certificates that are registered with standard authorities.

For more information, see Transport Layer Security (TLS) best practices.

For remote access to client private servers or private services a private connectivity option should be implemented. Pega Cloud can add custom DNS entries to the private host zone. To ensure secure private integration, Pega recommends HTTPS for REST and SOAP services. The SSL certificate for each private domain, however, must match the certificate on the client-managed server.

Recommended integration standards for Pega Cloud

Web Services APIs

Pega recommends RESTful web service APIs as the standard for web service integration, and therefore builds native capabilities exposed as RESTful APIs into the Pega Platform. The RESTful standard is widely adopted, with examples including OpenID® authentication standard and OpenAPI™ specifications.

Pega also supports the Simple Object Access Protocol (SOAP) web service standard. While we continue to see the market shift to Representational State Transfer (REST), and many clients phasing out SOAP in favor of the RESTful approach, SOAP still enjoys wide adoption. These specifications enable ease of configuration and maintenance of application interfaces.

Pega Platform also supports the SAP® iDoc connector using the REST infrastructure to connect to SAP ERP systems using a common data schema to send and receive XML.

For more information, see Connecting to REST and SOAP services.

Email provider integration

Email integration has existed in Pega Platform since its inception and remains the most consistently applied integration capability. The scope has broadened as new communications channels emerge, including SMS, chatbots, and others. Pega Platform email integration capabilities use the SMTP, IMAP, and POP3 standards for communication with on-premises and hosted email providers. This means that the existing integration capability works seamlessly on Pega Cloud.

For more information, see Creating a Service Email rule.  

Asynchronous messaging integration using IBM WebSphere™ MQ

Decoupling and consolidating the routing and transmission of messages between producers and consumers enables the development of complex, loosely-coupled application networks to increase resilience to node-level connectivity outages. Pega Cloud supports interoperability with IBM WebSphere MQ that many of our clients have deployed in their on-premises environments. However, because it involves non-HTTP ports, this integration requires a private connection.

For more information, see Configuring enterprise messaging using IBM MQ.   

Content Management and File Repositories

On Pega Cloud, Pega case attachments are stored by default in your Pega Cloud file repository. For more information, see Using Pega Cloud File storage.

To support secure file transfers to and from your Pega applications, Pega Cloud provides a dedicated SFTP server that you can use in combination with file listener or file data sets.  For more information, see Using Pega Cloud SFTP service.

Configuration requires a private connectivity channel when on-premises FTP servers must be isolated from the internet.  For more information, see Pega Cloud connectivity options.

Background Processing

Update these background processing methods for Pega Cloud:

  • A file listener with a file service was used to import and process files from another system or that were created by application users.
  • Email listeners provided the Pega Platform with the information it needed to route email incoming messages to an email service rule (Rule-Service-Email rule type).
  • Agents rules defined the background processing that was to be accomplished by agents in the system, including the activity that each agent should execute for the processing, its wake-up schedule, and its agent queue settings. Each agent that was listed in the Agents rule had one task it accomplished (checking incoming email, updating status of work objects, etc.).
  • Agent Schedule data instances determined whether an agent was enabled, and (on a multi-node system) on which server node that agent would run.

See the Job Scheduler and Queue Processor sections of the Modernization Implementation Guide for information on identifying and remediating instances of deprecated listener and agent functionality.

Node Classification

In your on-premises setup, you may have hard-coded node IDs into your agent or listener definitions.  However, identifying a specific server for your background processes will not work in a cloud environment.  Instead, use node classification. This segregates nodes by purpose and defines their behavior.  All the nodes in your Pega Cloud environments have already been classified.

To prepare for your migration, go through all of your Pega work resources and ensure that they are associated with the node types that you will have in your Pega Cloud environment, so after the migration, these work resources are configured properly.

For more information, see:

Search indexes

Depending on how your system is configured, developers can search for rules, data instances, and work items, and application users can search for work items. By default, full-text search is enabled for rules.

You are already a Pega client, so you may already be familiar with setting up a Search node on the Search landing page.  In your Pega Cloud environment, this has already been done for you.  Elastic Search is embedded in your environment, and the Search indexing is already associated with the Search node type.  The Search indexes are automatically built when the system is first used, and automatically update as you use your Pega application.

IMPORTANT:  As stated in the Node Classification section above, associating a work resource to a specific host ID is not supported on Pega Cloud.  Therefore, before your migration:

  • Reset your search indexing to use a Search node type; otherwise, your Search functionality will be broken after the migration.
  • Remove any command-line Search settings that use a JVM startup (for instance, -Dindex-directory) to add or modify an index host node.  This is legacy on-premises functionality – as stated above, the Search nodes will already be properly set for your environment during the provisioning phase.

Legacy Enterprise Application Deployment Functionality

In an on-premises environment, there are two ways to deploy a Pega application:

  • Enterprise application deployment, using the EAR file.
  • Web application deployment, using the WAR file

Because Pega Cloud uses Tomcat as the web server, Enterprise deployment functionality does not work, including:

Container Managed Transactions
Pega Cloud environments use the Tomcat web server; therefore, container-managed transactions are not supported.

Two-phase commits:  Java Transaction API (JTA)
The Java Transaction API is a Java EE API that allow distributed transactions to be committed across multiple databases. JTA is a specification developed under the Java Community Process as JSR 907.

When Pega Platform is installed as an Enterprise tier application (and the XA version of database drivers are installed) the Commit and Rollback methods apply to both internal and external classes, implementing a distributed transaction. Informally, this is known as "two-phase commit".

Because Pega Cloud environments use a Java SE runtime environment, two-phase commits are not supported.


  • Previous topic Identify Gaps, Required Changes, and Deprecated Features
  • Next topic Application Security Compliance on Pega Cloud

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