Short Description
In this document, you will learn about the following topics:
- Dirty dialog
- Difference between a browser Dirty Dialog and Pega Dirty Dialog
- When to use the browser Dirty and Pega Dirty Dialog
- Disabling the Dirty Dialog warnings/pop up
- Use of pega.u.d.gDirtyOverride function
- Use of pega.u.discardHandler function
- Dirty Dialog in Frameless Portal
- Discard Handler incase of Parallel Processing
- Dirty Dialog limitations in modal flow on Grids
- Dirty Dialog in Constellation
What is Dirty Dialog?
Dirty forms appear when a user makes changes in the current rule, and then tries to navigate away or close that rule without saving the data.
Browser Dirty Dialog v/s Pega Dirty Dialog
By default, Pega provides the Pega dirty dialog.
However, for browser popup, use the following script in the in UserWorkForm.
<script>
pega.u.d.bUseNativeDirtyConfirm = true;
</script>
When to use the Browser Dirty vs Pega Dirty Dialog
It is recommended to use the Pega Dirty dialog only instead of the browser dirty popup. However, if the customer wants to use the browser dirty popup, we can set pega.u.d.bUseNativeDirtyConfirm = true; in the UserWorkForm.
Disable the Dirty Dialog warnings/pop up
- To disable the dirty check at the harness level, enable the Do not disable dirty warnings checkbox in the Harness Advanced configuration.
- To disable the dirty check in a particular section, embed the OOTB section rule
@baseclass.pxDisableClientDirtyDetectionin the section. - To disable the dirty check on a button, use the Click event, perform a Run script action, and call the below function.
<script>
function clearDirty(){
pega.u.d.clearDirtyState();
}
</script>
Scenarios
Scenario 1: Dirty Form does not show the dirty popup as expected
Root cause 1: Check if the Dirty Warnings are enabled for the UI screen. Check if the Do not disable dirty warnings checkbox is enabled in the Harness' Advanced configuration.
Solution: Uncheck Do not disable dirty warnings checkbox in the Harness Advanced configuration.
Root Cause 2: Check the Document Type. The behavior changes according to the document type.
Solution:
- Multi Document (Case manager): Typically, the Case Manager portal uses a multi document dynamic container. So, when you have an open case with a dirty form and you click on any left navigation item, you are not taken away from your case. It is still in the DOM, and when you click on that Case ID from the Recents tab section, it will switch right back with your form data intact.
- Single Page Document (Case Worker): The Case worker portal uses the Single document dynamic container. The portal will show a dirty popup, on navigating away from the work object. If the portal does not display the dirty popup, refer to the above scenarios.
- Ajax Container (Theme Cosmos): Ajax Container will show a dirty popup, on navigating away from the work object. If the Ajax Container does not display the dirty popup, refer to the above scenarios.
Scenario 2: Launch Local action and Dirty Popup displays, but on clicking the button in the dirty dialog, user is not directed to the required screen
Root cause: Check if the Layouts used are deprecated.
Solution: Upgrade to the latest layouts.
Scenario 2.1: Discard/Ok (Event: Cancel) is not working
Root cause: Check if the Pega Dirty Dialog is used.
Solution:
If yes, use the browser level Dirty Dialog, which provides the OK button. To use the browser level dirty dialog, use the following script.
<script>
pega.u.d.bUseNativeDirtyConfirm = true;
</script>
Or
Check the action configured on the OK or Discard buttons. The action should be pega.u.d.discardHandler function.
If no, then check the isformDirty function, as this controls the display of the modal dialog.
Scenario 2.2: Save is not working
Root cause: Check if the Pega Dirty Dialog is used.
Solution: If yes, we may need to use the browser level Dirty Dialog, which does not support the Save operation.
To use the browser level dirty dialog, use the following script.
<script>
pega.u.d.bUseNativeDirtyConfirm = true;
</script>
Scenario 3: Form is Dirty and dirty dialog displays; however the dirty dialog is not needed
Refer to Disable the Dirty Dialog warnings/pop up
Use of pega.u.d.gDirtyOverridefunction
If customer does not want to display dirty popup, this flag can be used alternatively. Upon setting this flag to false, the dirty popup will not display.
Use of pega.u.discardHandler function
Upon performing any action, if the dirty popup displays and the user clicks the OK or the Discard button, ideally the action which caused the dirty popup should be executed. For achieving this functionality, the pega.u.d.discardHandler function is used. This is configured for the OK or Discard buttons.
Possible issue when using the pega.u.d.discardHandler APIOn click of the OK or Discard buttons, if the work object is closed instead of performing earlier actions, check if the pega.u.d.discardHandler function is configured in the runScript action upon Click event.
Discard Handler incase of Parallel Processing
The dirty popup appears when a user edits a field in the form or tries to edit a field with the Post-value/Refresh section configured. In both cases, displaying the dirty pop-up is a valid use case.
In the scenario of a local action, as the same thread is present throughout the processing, discard launches the local action. When navigating back to the previous screen, the UI is updated with clipboard data. However, in the case of a parallel process that uses an open assignment, a thread is opened and closed each time, leading to values not being maintained at the thread level.
Dirty Dialog limitations in modal flow on Grids
The dirty popup will not work in scenarios where users want to use a flow in a modal dialog on the data of an optimized table (grid layout).
The flow in modal dialog action is not intended to operate within list (grid) or repeating dynamic layout scenarios. Editing a row will cause a global refresh making the dirty flag dysfunctional. The product is designed to reset the dirty check and discard the changed value.
Workaround
To perform any actions on the optimized grid, use one of the List actions which are specifically for performing actions on the grid, or use the Editable in modal option in the grid operations and add the flow action on the specified field.
Scenario 4: Dirty dialog triggered after Post Value or Refresh Section
In Traditional UI, the Dirty Dialog will be displayed when:
- a Post Value action is triggered
- a Refresh Section action is triggered
- the user subsequently attempts to navigate away from the form or harness
Even if the user did not manually modify any values after the refresh, the system may still consider the harness as dirty.
Why This Happens
The Dirty logic in Traditional UI works by:
- Tracking each form element’s previous value
- Comparing it with the current value
- Marking the harness as dirty if a difference is detected
However, when the Post Value or Refresh Section is executed:
- The server sends back a new DOM structure
- The existing DOM elements are replaced
- Client-side previous value references are lost
Since the framework cannot reliably determine whether the values truly changed or if the DOM was simply re-rendered, the harness is conservatively marked as dirty.
As a result, when the user navigates away after a Post Value or Refresh Section, the Dirty Dialog may appear even though no additional changes were made.
Expected Behavior
This is an expected framework behavior in Traditional UI due to DOM replacement.
How to Suppress Dirty Dialog for These Scenarios
If the business use case requires that navigation after Post Value or Refresh Section should not trigger the Dirty Dialog, you can explicitly clear the dirty state.
Recommended Approach
Add a Run Script action immediately after:
- Post Value
OR - Refresh Section
JavaScript Function
function clearDirty() {
pega.u.d.clearDirtyState();
}
Action Set Configuration
- Open the control's Action Set
- After the Post Value or Refresh Section action:
- Add a Run Script action
- Configure it to execute
clearDirty()
This clears the harness dirty state on the client.
Clearing dirty state removes the safeguard provided by the Dirty Dialog.
Dirty Dialog in Frameless Portal
In Frameless portals (neither Case Manager nor case worker), the dirty popup will not work in all the use cases. This is currently being worked as an enhancement.
To enable the confirmation dialog boxes for frameless portals with work items that include Post value or Refresh local actions, set the following script:
<script>
pega.u.d.handleDirtyForFramelessPortals = true;
</script>
Dirty Dialog in Constellation
In the Constellation, only Browser Dirty Popup will be shown. There are two types of dirty dialogs as below,
- When the case is created: On cancel, this triggers a
CancelALERTAPI. - During the work object processing within the work object: In this, only the browser level dirty popup will be displayed.
@Bhavana_S Thank you for this Post, but I found yesterday maybe an interesting "solution" to a disappearing dirty popup.
When user edited a case, did not save it, and clicked to go to the dashboard, the popup saying "you have unsaved changed, are you sure you want ti proceed?" would appear for a second or so, and then would disappear.
I went through multiple posts in Pega Community, search through rules which referred something about content, or the field value / paragraph used in that popup, nothing.
Then I noticed that in one of our portals this popup worked as expected (I mean, it would not disappear automatically), and i compared this portal with my other portals, and the options in the Dynamic Container of the main section of those portals "Render as single page" and "Allow concurrent work in multiple tabs/browsers" were disabled.
Once I enabled both (i did not test only the first, because the second only becomes visible if the first is enabled), it worked correctly. Obviously, it goes without saying these options should be enabled, portals should render content as single page, and allow concurrent work.