Introduction

Since Preflight Optimization is a design time optimization, there are situations when the specific classes that are used to represent some aspects of the user interface are not known until run time. When this happens and preflight optimization has been turned on, some classes associated with objects in the model that are only determined at run time may not be included in the design time optimizations. In this document, we show some cases where out-of-the-box Express apps exhibit this behavior and how the Preflight Optimization Advanced tab can be used to force ("whitelist") the inclusion of these run time classes. We also present some hints on how to refer to the browser DOM to find the classes to help customers find and fix similar issues in their Pega applications.

Which Express apps require whitelisting to make sure classes only known at run time are included during Preflight Optimization?

All 3 of the primary Express application types:

• Task Tracker
• Service Request
• Request Approval

What needs to be whitelisted?

Since an application's Preflight Optimization is performed separately depending on the target Portal, the classes that need to be noted depend on which Portal is being optimized.

For the User portal:

• Rule Type: Section – Applies to: Assign-Worklist – Name: pyCaseContentDetails

For the Manager portal:

• Rule Type: Section – Applies to: Data-Portal – Name: pyWelcomeToPegaCaseManager
• Rule Type: Section – Applies to: Data-Portal – Name: pyCaseManagerShortcuts

Why do these sections need to be whitelisted?

Preflight Optimization works by performing a design time analysis of the application’s model. This allows the optimizer to see which components are used in the model. This is typically a subset of all possible components available to an application. The JavaScript part of the optimizer uses the information from this analysis to load only the JavaScript files necessary to support the components that are used. The CSS part of the optimizer looks at the components that have been seen as used and further looks at the aspect of the model analysis to determine which CSS Formats have been used for each component that’s been used. Then, only the CSS Formats that have been detected as being used in the application are loaded by the running application.

Since the Preflight Optimization is a design time optimization, there are cases when the specific classes that are used to represent some aspects of the user interface are not known until run time. When this happens and preflight optimization has been turned on, it can result in some classes associated with objects in the model being used at run time that have not been included in the design time optimizations. In the case of the 3 sections listed above, each of the Sections that need to be whitelisted are not associated with a specific class until run time. Therefore, we need to add them to the Preflight Optimization whitelist in order for the model analyzer to make them as being used.

How do I whitelist these sections?

When creating a Preflight Optimization, you can add specific items to be whitelisted on the Preflight Optimization Advanced tab. (You can also “blacklist” items by entering them on the Advanced tab and checking the “Skip” checkbox.)

To properly whitelist the Section needed for the User portal, you can enter the information above in the Advanced tab as shown here:

To properly whitelist the Section needed for the Manager portal, you can enter the information above in the Advanced tab as shown here:

What happens if these Sections are NOT Whitelisted?

In the User portal, when creating a new case (below, we show the creation of Service Request), the Open Assignments detail is improperly rendered. The text is shifted over to the right and the “clock” icon is in the wrong place relative to the text as shown here toward the right of the screen:

In the Manager portal when viewing the Dashboard, the Tour video and Welcome panes are incorrectly stacked and the Case Manager shortcut icons are improperly rendered as shown here in the top middle and right of the screen:

How will these Sections be displayed when they have been properly whitelisted?

When properly whitelisted, the CSS optimization will have loaded all of the CSS necessary to render the sections. Therefore, these sections will be rendered exactly as they are rendered when the application does not have CSS Optimization turned on.

In the User portal, the Open Assignments text and “clock” icon will appear properly placed as shown here:

In the Manager portal, the Tour Video and Welcome to Pega 7 sections will be shown side-by-side. Similarly, the Case Manager Shortcuts will be properly rendered. Both of these are shown here:

How can I find and fix similar CSS Whitelisting opportunities in my applications?

If you encounter other Sections (or UI objects) in your applications that seem to have been missed by the CSS Optimizer since the class assignment wasn’t known at design time, you can inspect the page’s elements (using your browser’s DOM Inspector) to see where the problem likely was encountered. If we look at the “Get next work” improper rendering in the Manager portal, we can use the DOM Inspector to see where the appropriate “Get next work” is found. Then, if you read up the DOM structure, you can find the closest enclosing Section. In that markup, you can find that the text is in the Rule-HTML-Section (so we know this is a section) with the node_name of pyCaseManagerShortcuts and a pyClassName of Data-Portal. Note that these map directly to the Section – Data-Portal – pyCaseManagerShortcuts that we entered in the Advanced tab to whitelist the section. You can see a sample, annotated markup here: