Skip to main content

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

Managing Hazelcast client-server mode for Pega Platform

Updated on June 4, 2021

This content applies only to On-premises and Client-managed cloud environments

This section includes best practices and guidelines to help you manage on-premises Pega Platform™ environments operating with client-server Hazelcast. 

Best practices for performing server maintenance

To prevent undesired results, when performing maintenance on Hazelcast servers, use the following best practices:

Note: Improper termination of nodes might lead to data loss.
  • Starting servers

    • Ensure to start at least three Hazelcast servers before starting Pega Platform. An alert is sent if less than three servers are available.

    • Ensure that at least one Hazelcast server is in operation for clients to start Pega Platform.

  • Shutting down servers

    Ensure that you gracefully shut down all Pega Platform before shutting down the Hazelcast servers.

  • Restarting and refreshing servers

    If you need to restart or refresh Pega Platform, you can perform a rolling restart. Perform the restart during low activity times because additional resources are consumed for data repartitioning.

  • Decreasing Hazelcast cluster capacity

    You can remove Hazelcast at any time; however, keeo at least three or more servers in the cluster. An alert is displayed if the number of servers is less than three.

  • Recovering after improper shutdown, termination, or node lost

    A full copy of all the data exists across the servers. If one or more of the required three nodes is lost, the other nodes can cover the distributed operations until you restore the node. After you restart the server, the remaining nodes redistribute data to the node to protect against another node loss.

Upgrading Pega Platform

The process for upgrading Pega Platform with Hazelcast depends on the type of upgrade that you want to perform:

Upgrading from Pega Platform with embedded Hazelcast to Pega Platform with client-server Hazelcast

If you are upgrading Pega Platform 8.x with embedded Hazelcast to Pega Platform 8.4 or later with client-server Hazelcast mode enabled, start Hazelcast servers after upgrading the Pega database and application servers and before restarting the Pega nodes.

  1. Configure your database, install or upgrade Pega Platform, and then configure the application server. See the appropriate deployment guide for your system on the Deploy Pega Platform page
  2. Gracefully shut down all Pega nodes in the embedded Hazelcast cluster.
  3. Configure client-server mode for Hazelcast on Pega Platform, which involves configuring the connection between Hazelcast servers and changing the cluster identification setting. For instructions, see Configuring client-server mode for Hazelcast on Pega Platform.
  4. Restart Pega Platform.
Note: If you want to upgrade an earlier version than Pega Platform 8.1, contact Global Client Support.

Upgrading to major and minor versions of Pega Platform with client-server Hazelcast

If you are upgrading Pega Platform with Hazelcast client-server, you restart Hazelcast servers after the database is upgraded and before restarting the Pega nodes. 

  1. After upgrading the Pega database, gracefully shut down all Pega nodes.
  2. Restart the Hazelcast servers.
  3. Start the Pega nodes.

To upgrade Pega Platform, see the appropriate deployment guide for your system on the Deploy Pega Platform page

Applying patches to Pega Platform with client-server Hazelcast

If you are upgrading Pega Platform with Hazelcast client-server to a patch version of Pega Platform with Hazelcast client-server, no additional upgrade steps apply. You can perform a standard rolling upgrade. Patch releases are available through Digital Software Delivery. To apply a patch to your existing system, see Applying the latest on-premises patch.

Rolling back Hazelcast client-server mode for Pega Platform

If you configured Hazelcast client-server mode for Pega Platform and want to roll back your changes to restore embedded Hazelcast, modify the prconfig.xml file and perform a rolling restart.

  1. On the application server, navigate to the prweb/WEB-INF/classes directory, and then open the prconfig.xml configuration file.
  2. Change the clientmode setting from true to false:

    <env name="cluster/clientserver/clientmode" value="false" />
  3. Remove the following line:
    <env name="cluster/clientserver/serveraddress" value="localhost:5701,localhost:5702" />
  4. Ensure that database/databases/PegaRULES/defaultSchema is set to the name to which the schema rules were upgraded.
  5. Perform a rolling restart of the Pega nodes. For more information, see Performing a rolling upgrade.

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