Skip to main content
Verify the version tags to ensure you are consuming the intended content or, complete the latest version.

Declare OnChange Rules

Declare OnChange rule automatically runs an activity or suspends the current work object, when the value of a specified property changes. For example, a Declare OnChange rule can compute the average dollar amount of work items entered by a team in real-time or it can force all processing on a work item to be suspended pending an investigation or review of a situation. If a Declare OnChange rule is used to suspend work, the when condition is called a business exception.

No other rules explicitly reference Declare OnChange rules. You can create a new Declare OnChange rule from Dev Studio (Create > Decision > Declare OnChange).

Note: To learn more about the Declare OnChange form, see Declare OnChange form - Completing the OnChange Properties tab.

Declare OnChange rules allow you to specify a when condition to test one or more property values and run different activities based on a true or false result for the condition. With a Declare OnChange rule, when conditions are evaluated at the time a property value changes.


OnChange activities could have performance implications if the properties to watch change frequently. Consider adding when conditions and designing the action activity to complete within agreed upon performance thresholds.

Note: To learn more about Declare OnChange rules and performance, see More about Declare OnChange rules.

OnChange properties and conditions

To facilitate addressing when conditions when property values change, define what properties to watch for changes and the conditions for taking action when the properties change. 

Properties to watch 

Identify a property on the top-level page or a page that is identified by the Page Context field on the Pages & Classes tab. Some restrictions apply: 

  • If you list more than one property, the properties must be on the same page (either the top-level page or a common embedded page).
  • If you list more than one property, when two or more of the properties change value (for example, within a single step of an activity), this OnChange activity runs only once.
  • Start each property reference with a dot. You cannot reference a property on a page other than the page corresponding to the applies to key of the rule or on a page identified by the Page Context field on the Pages & Classes tab.


Configure conditions for Declare OnChange rules to evaluate as running Always, based on a when condition rule to be evaluated at the time a property value changes, or by entering a simple Boolean expression in one of two formats:

  • property = "constant value"
  • property1 > property2
Caution: To avoid impacting performance, do not use a complex Java expression under the when condition in the Conditions field of the On Change Properties tab.

Actions for changing property values

Select from two actions when any of the specified properties change. 

Call activity 

Developers can create a Declare OnChange rule, add properties in the Properties To Watch section, and run an activity when those properties change. This is helpful in situations that require enhanced auditing capabilities where specifications require recording every time a property value changes along with the conditions that existed when that property value changed, such as time of day, who changed it, and the values of other corresponding properties. 

To call an activity when a property value changes, the following requirements are necessary:

  • Ensure that the activity type is OnChange.
Note: You can set the activity type in the Security tab of the activity rule.
  • Ensure that branches or other activities that the activity can call have an OnChange activity type.
  • Enter or select the standard Always when rule to run only one activity.
Caution: Use a Declare OnChange rule for calculations only when a declare expression is not suitable.

Check your knowledge with the following interaction:

Suspend work object

When an unexpected business exception occurs, such as if fraudulent activity is detected or data is provided that causes a compliance violation, you may elect to suspend the work object. Use a Declare OnChange rule to check changes to the property. By selecting Suspend work object, you force all processing on a work item to be suspended when the condition is met. 

Caution: Be careful not to start an infinite processing loop within declarative rules. For example, in an OnChange activity, do not update any of the properties that caused the activity to start. You can update other properties in the OnChange activity.

Check your knowledge with the following interaction:

This Topic is available in the following Module:

If you are having problems with your training, please review the Pega Academy Support FAQs.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega Academy has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice