Manage data instances during an upgrade

From PegaWiki
Manage data instances during upgrade / This is the approved revision of this page, as well as being the most recent.
Jump to navigation Jump to search

Manage data instances during an upgrade

Description Manage data instances during an upgrade
Version as of 8.1
Application Pega Platform
Capability/Industry Area System Administration


Application implementations that are built on other underlying applications or frameworks are very common. This pattern helps faster implementation, because there is a lot of potential reuse. Due to varying business requirements, the default configurations that were originally shipped by the underlying application or framework need to be updated in the implementation layer. These configurations can be driven using multiple types of data records, such as dynamic system settings and custom data types. When such updates are done, the actual record shipped by the underlying application is updated. After the underlying application is upgraded, the implementation expects its data changes to be retained. The implementation layer does not want the upgrade to override its planned data changes. A simple and convenient way to achieve this is explained here.

Customization of data records[edit]

Some of the common data records provided by the application framework, which are generally customized by the implementation teams, include the following:

1. Dynamic system settings are instances of the class ‘Data-Admin-System-Settings’. Each dynamic system setting will hold a ‘Value’ that either regulates the behavior of a specific feature of the application or provides the necessary run-time value for a property. It is a very common practice to customize the values of these settings to suit the application’s business and technical needs.

2. Custom Search Properties are instances of ‘Data-CustomProperties-Search’. This record holds the list of properties to be stored in the Lucene index for a specific class, which can be queried and returned using Elastic search. These records will be updated by the implementation teams to add or remove the properties to be indexed, based on business needs.

Besides these data record types, there are many other data records such as Data-UniqueID, Data-EmailAccount, and Data-Logger-Category that can be updated by the implementation teams.

Approach to retain the updates on the data records[edit]

If a data record is updated in the new version (for example, v1.2) of the application framework, it will have a newer ‘update date time’ than the record in the implementation system. As a result, when upgrading the built-on application framework from the old version to the new version (v1.1 to v1.2), the data record in the target system will be replaced by the incoming record from the framework’s application bundle. This override results in losing the customizations done by the implementation teams to suit the customers’ business needs and may lead to unwarranted changes to business operations. In some situations, based on how the setting has been used, it can lead to severe business implications.

Illustration of data records overridden and retained during an upgrade
Figure 1: Illustration of data records overridden and retained during an upgrade

For example, consider an implementation application ‘U+ Castings’ built on a framework application ‘Pega Foundation for Production (PFP) 8.1’.

A dynamic system setting ‘InvoiceFilePath’ that specifies the folder to generate the invoice files was provided with a default value of ‘/opt/tomcat/Invoice’ by the framework PFP. This dynamic system setting was customized by ‘U+ Healthcare’ to suit their deployment model, with a value ‘/WPSHome/Invoice’.

In the subsequent release (8.2), PFP updated this dynamic system setting to a different value of ‘/opt/tomcat/InvoiceOUT’. Therefore, the data record that is packaged with PFP 8.2 will have a newer pxUpdateDateTime than the one in ‘U+ Castings’. During the upgrade of PFP from 8.1 to 8.2, this dynamic system setting will be replaced with the default value from PFP 8.2. This results in reversing the customizations made by the implementation application, which will result in unexpected behavior after the upgrade, as illustrated in figure 1.

Configuration of product rule to skip updates
Figure 2: Configuration of product rule to bypass updates during import

To avoid this unwanted situation, it is recommended that you use the following simple approach so that data instances are not overridden during an upgrade.

In the product rule that is used to package the framework application (in the preceding example, Rule-Admin-Product for packaging PFP 8.2), define the classes that should bypass updates to the instances during the import and upgrade of the application. This can be done by adding the classes under ‘Bypass updates for class instances on import’ section of the Deployment tab of the product rule (Rule-Admin-Product), as shown in figure 2.

Important points to be considered[edit]

This configuration on the product rule will only skip the records that already exist on the target system. However, any new records of the specified class (for example, Data-Admin-System-Settings) will be imported.

Because the upgrade process does not import the data records from the new version of the application if the data record already exists on the target system, customers may not get any new additions done to these records. For example, if a new property was added to a record of ‘Data-CustomProperties-Search’ in the new version, this property will not be present on the record for the customers if the data record was already updated. Therefore, it is recommended to provide a document that details any such changes that may not be imported during upgrade. The implementation team must manually merge the changes after upgrade. This will not be application for dynamic system setting, as it can only has one value.

This configuration on the product rule is available in Pega Platform 8.1TM version and later.

This paradigm holds true for any construct of an application built on any application, irrespective of it being CRM or industry application or an implementation built on a custom framework.