Balasubramanian Durai (durab)
Principal Software Engineer
Pegasystems Inc.
durab Member since 2016 9 posts
Posted: December 10, 2019
Last activity: December 19, 2019
Posted: 10 Dec 2019 20:42 EST
Last activity: 19 Dec 2019 9:21 EST

Common UI issues on upgrade of Pega Applications Built on UI-Kit

Every once in a while, things need to be upgraded. Your credit card, your car, your device's software/applications (the list goes on..). Things get outdated, stale, and irrelevant; it's just the way of our constantly changing world.

Nowadays, upgrading applications are a must. The need for upgrade is essential for the following points:

  • Application needs to be fast and scalable
  • To be compatible with new systems & tools
  • No dependency on hardware
  • To have good support in mobility & accessibility
  • To be more secure
  • Improved focus on user experience
  1. UI issues after upgrade

After upgrading pega applications to newer versions, the most common UI issues are misalignment of the layouts, controls and text overlapping over content, browser compatibility issues, etc.

Misalignments or UI distortions may arise due to many factors in a pega application:

  1. Rules being overridden in the application layer
  2. Rules being updated in base layer
  3. Changes to formats in skin
  4. Wrong css selectors being picked from override files
  5. Platform changes
  1. How to identify UI issues after upgradation?

There are ways to identify whether the issues are application specific or due to changes in platform.

  1. Check if the rules has been overridden in the application - If yes, then refer to the ruleset in base layer for how its constructed
  2. Check if the application is using app skin or directly inheriting from UI Kit ruleset
  3. Check whether there is a change in the format present in the skin
  4. Check if any css selectors are wrongly picked from any overridden files
  1. Most common UI issues observed

Issue 1 - Application portal header misalignment:

The application portal header misalignment occur if the header rule has been overridden in the application layer and when the rule is not used directly from UI kit ruleset.

Root Cause:

pyPortalHeader section has been overridden, and the application name uses label control and application name label format has a line height of 40px. From 8.1, the application name format label has been updated to not use line height. Refer to the section used in Uikit Ruleset


Update the pyPortalHeader section to use inline middle dynamic layout format, since Portal Header Primary format has been deprecated to align the items vertically centered

Issue 2 - Work area header misalignments

After upgrading the applications, the work area header gets misaligned with wrong padding and different background color. Issue is because of wrong settings in standard container format.

Steps to fix the issue:

  1. Navigate to the application skin
  2. Click on “Containers”
  3. Check “Show legacy styles”
  4. Click “standard format” and update the following settings

Issue 3 - Label elements showing for controls after upgrade

Before proceeding with fix ensure the control is inside a dynamic layout and format for layout is set as “Mimic a sentence”

Root Cause

From 8.1 “Mimic a sentence” format of pyEnduser skin displays labels. Reason behind this intentional change is as labels can be added or removed per control, there is no value in having any OOTB layout format define the label display for any control dropped inside it.

Steps to fix the issue

  1. As a local-change, make rule changes to not show labels for controls (Recommended)


  • Uncheck “Use property default “ checkbox
  • Clear text in “Label value” field if any

  1. Override the “Mimic a sentence” format in skin


  • Use this solution only when then there are too many rules to be updated
  • Latest changes to this format will not be available as format is overridden


  • Open skin
  • Go to dynamic layouts components
  • Override “mimic a sentence” format
  • Change label position value to “none”

Upgrading applications and fixing issues is a tedious work as it consumes lots of time and resources. It is always advisable to follow the best practices to avoid the number of issues

Best practices to be followed to avoid ui kit upgrade issues

  1. Don’t name the rules in the application the same as in UI kit ruleset
  2. If any rule is overridden, check the same rule in the UI kit layer for how its constructed.
  3. CSS files should not be overridden in the application layer with the same name as in Uikit rule
  4. Custom css files should be included for any custom styles specific to application
  5. Styles and javascript files should not be included in Harness
  6. Use helper classes to avoid overrides
Low-Code App Development System Administration Upgrades Developer Knowledge Share