Skip to main content

Remediating for migrating to Pega Cloud Services environments

This content applies only to Cloud environments.

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.  You must update this functionality to current Pega application features, in order for your application to run correctly in the Pega Cloud Services environment. 

Some of the older functionality may not become apparent until after you have migrated; you will need to update those as well.

The next section describes some known areas of older versions of Pega applications which will require remediation.

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 Services 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 Services balances technologies to provide you with stable, high-performing, and secure connections to critical business systems.  For full details, please see Integrating Pega applications in Pega Cloud with external systems.

Verify that the Connect and Services rules in your application are supported on Pega Cloud, and replace any that are unsupported.

Complete the Integration tab on the Assessment Worksheet.  Be careful to note which system(s) each of these integration rules map to.  Also be sure to note any “legacy” integration rules in your application, and replace them with the appropriate Recommended Integration Standards, which are defined below.

Recommended integration standards for Pega Cloud Services

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 further details, 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 like Amazon Alexa, and more. Pega Platform email integration capabilities use the SMTP, IMAP, and POP3 standards for communication with on-premises and hosted email providers. This means the existing integration capability works seamlessly in Pega Cloud Services.

For further details, see Service Email Rules.

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 Services supports interoperability with IBM WebSphere MQ that many of our clients have deployed in their on-premises environments. However, since it involves non-HTTP ports, this integration requires a private connection.

For details, see Configuring enterprise messaging using IBM MQ.

Integration Security

Pega Cloud Services supports TLS 1.2 for HTTPS connections and provides certificates that are registered with standard authorities. This means Pega Cloud Services supports one-way SSL.  Pega Cloud does not support two-way SSL.

For remote access of client private servers or private services through the Pega Cloud VPN, Pega Cloud can add custom DNS entries to the private host zone. To ensure secure private integration, HTTPS is recommended for REST and SOAP services. The SSL certificate for each private domain, however, must match the certificate on the client-managed server.

Content Management and file repositories

In Pega Cloud deployments, Pega case attachments are stored by default in an Amazon S3 bucket. Pega Platform recognizes this online repository as a Pega Cloud Services File Storage repository.

To support secure file transfers to and from your Pega applications, Pega Cloud offers a dedicated SFTP server that you can use in combination with file listener or file data sets.  For details, see Pega Cloud Services SFTP Service.

Configuration requires a VPN or Amazon Direct Connect channel when on-premises FTP servers must be isolated from the internet.  For details, see Configuring Amazon Web Services (AWS) Direct Connect.

Legacy integration options only available for on-premises deployments

Certain integration capabilities have dependencies on specific deployment options and technology choices that work well with an on-premise data center, but present obstacles when used in a cloud operational model.

The following criteria drive an acceptable use compatibility of your integrations for use with the Pega Cloud Services deployment model:

  1. No dependencies on third-party software that may alter the behavior of the Pega Platform runtime environment.  (Example:  Custom libraries added to the application server configuration file, like tomcat/lib.)
  2. No required customizations of container-level configuration - Pega requires that your application support the Pega Cloud Services auto-scaling of server nodes model.
  3. No database customizations that require unsecured manual changes to the data or database structures.   All database changes must be made through the Pega application.
  4. No use of non-standard ports or dynamic IP addresses that would necessitate the use of a private network connection.
  5. No reliance on a local file system for temporary or permanent file storage.  Since the Pega Cloud file system is transient, your Pega application could experience data loss if it requires access to a local file system.
  6. No reliance on a specific node (identified by a specific Host ID or IP address).  The Pega Cloud model uses transient nodes that can be automatically replaced for performance or other health or maintenance reasons.

If your integration technologies violate any one these criteria, Pega Platform support cannot be extended for your Pega Cloud Services or Client Managed cloud deployments until you make acceptable integration substitutions by implementing one of our recommended integration standards.

The following integrations use technologies supported only within the on-premises deployment environment:

File connectors

File connectors are not supported in Pega Cloud, since they are tightly coupled to local file systems, and do not support streaming. Use Repository rule APIs to interact with cloud storage providers like Amazon S3™ and Microsoft Azure Blob storage.

Pega Cloud remediation:  Use Pega Repository APIs to interact with cloud storage providers like Amazon S3™; you could also configure a file listener to process your files.

Enterprise JavaBeans™ (EJB)

EJB connectors and services are not supported because they require a Java Enterprise Edition (EE) runtime environment to function correctly.

Pega Cloud remediation:  Replace these connectors with a supported connector type.

Java EE Connector Architecture (JCA Connectors)

JCA connectors are not supported for the same reasons that EJB connectors and services are not supported.

Pega Cloud remediation:  Replace these connectors with a supported connector type.

JMS MDB Listener

Message driven beans (MDBs) are a Java Message Service (JMS) listener that can reliably consume messages from a queue or a durable subscription. The messages may be sent by any Java EE component.  Since Pega Cloud Services environments use a Java SE runtime environment, the JMS MDB listener is not supported.

NOTE:  Do not confuse message driven beans with MBeans, part of Java Management Extensions (JMX).

Pega Cloud remediation:  Replace these connectors with a supported connector type.

JMX Management Beans (MBeans)

Management beans, or JMX Management Beans (MBeans), are the objects in a Java EE technology that allows applications to expose operational facilities in accord with the Java Community Process standard JCP-160. This standard is informally known as Java Management eXtensions or JMX.  Since Pega Cloud Services environments use a Java SE runtime environment, JMX MBeans are not supported.

Pega Cloud remediation:  Replace these connectors with a supported connector type.

JSR94 Services

The JSR94 service API can only be accessed from a third-party process executing in the same runtime environment as the Pega Platform. This is not possible on a managed cloud environment.

Pega Cloud remediation:  Replace these connectors with a supported connector type.


Background processing

Legacy options

Depending upon your on-premises setup, you may be running these types of background functionality on one node, or all nodes, or certain specified nodes. 

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.

Recommended functionality for agents:  Queue processor and Job Scheduler

Configuring any of these processes to run on a particular node is not supported in a Pega Cloud environment. Starting with Pega Platform 8.1, Job Scheduler and Queue Processor rules were developed as an alternative to Agents and designed to run in either on-premises or Pega Cloud environments.  Job Scheduler rules replace Advanced Agents for recurring or scheduled tasks, and Queue Processor rules replace Standard Agents for queue management and asynchronous processing.

For best practice guidance for associating such work resources with node types, see the following articles:

Node classification

In an on-premises setup, for application versions prior to 7.3, in order to do background processing using agents and file listeners you may have hard-coded node IDs into your agent or listener definitions, or specified a particular node for your Search indexes.

However, identifying a specific server for your background processes will not work in a cloud environment.  Beginning with Pega 7.3, you can optimize performance and provide higher scalability and stability in a Pega cluster of servers by using node classification, which segregates nodes by purpose and defines their behavior.  All the nodes in your Pega Cloud Services environments have already been classified.

For details, see Node Types.

To prepare for your migration, you should 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.

See Mapping agents to node types and Mapping listeners to node types

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.

Since you are already a Pega client, you may already be familiar with setting up a Search node on the Search landing page.  In your Pega Cloud Services 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 in Pega Cloud Services environments.  Therefore, before your migration:

  • You must reset your search indexing to use a Search node type; otherwise, your Search functionality will be broken after the migration.
  • You must 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

Since Pega Cloud uses Tomcat as the web server, no Enterprise deployment functionality will work, including:

  • MDB listeners  (see previous section)
  • Connect-EJB (see Enterprise JavaBeans section above)
  • Service-EJB (see Enterprise JavaBeans section above)
  • Container Managed Transactions
  • Two-phase commits

Container Managed Transactions

Pega Cloud Services 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".

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

Application Security

Pega Cloud Services provides multiple layers of security and monitoring for your virtual private cloud environment.  However, you still need to make sure that your application is secure.  You are responsible for identity and access management – an appropriately-secure password process for your users, and a secure login process.

For details, see Customer access to Pega Cloud Services environments.

Setting up secure connections for authentication functionality

Pega Platform supports the following protocols for user logins.

  • Basic credentials – User identity is verified through a user ID and password that can be stored in the Pega database or another internal or external data source.
  • SAML 2.0 – User identity is verified through an external identity provider that supports the SAML 2.0 protocol. For more information, see Web single sign-on (SSO) with SAML 2.0.
  • OpenID Connect – User identity is verified through an external identity provider that supports the OpenID Connect (OIDC) protocol.
  • Anonymous – User identity is not verified until partway through a session. For example, an unauthenticated user can add items to a shopping cart, and enter credentials when they check out.
  • Token credentials – User identity is verified through use of a token that is validated by an external identity provider or by the Pega Platform OAuth 2.0 authorization layer; often used in offline mobile applications.

NOTE:  The Authentication in Pega Platform article states that Microsoft Active Directory (AD) is supported for SAML 2.0.  Active Directory is not supported for Pega Cloud Services, as it cannot authenticate users accessing AD-integrated applications externally.  Instead, Active Directory Federated Services (ADFS) is supported.  ADFS provides single sign-on access to servers that are off-premises.

Authentication for Pega Cloud Services

You can customize authentication services to use information that is stored within the identity provider to determine the user's roles and privileges in Pega Platform.  There are three options for connecting to Pega Cloud:

  • Internet only
  • Private connection only
  • Internet plus private connection

For details, see Pega Cloud Services networking.

We encourage clients to use web services like REST/SOAP that travel over the encrypted internet (HTTPS), which does not require a private connection and is still secure.

If you require a private connection to your identity provider from your Pega Cloud environment, use one of the following:


Suggest Edit
Did you find this content helpful?

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

We'd prefer it if you saw us at our best.

Pega Community has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice
Contact us