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 rules

A Declare OnChange rule automatically executes 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.

No other rules explicitly reference Declare OnChange rules. After you save a Declare OnChange rule, it runs immediately as needed. You can create a new Declare OnChange rule from Dev Studio (Create > Decision > Declare OnChange).

Note: The Properties to Watch should be in the same class as that of Declare OnChange rule, or in the class of an embedded page.

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.

Tip: To only run one activity, enter or select the standard when rule Always.
Note: If a Declare OnChange rule is used to suspend work, the when condition is called a business exception.

To learn more about the Declare OnChange form, see the Declare OnChange form - Completing the OnChange Properties tab community article.

Call activity

Creating Declare OnChange rules to run an activity automatically when the value of a specified property changes, is a form of automatic forward chaining.

Note: 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.

When a user adds some products to a shopping cart, the business requirement may involve complex calculation to determine the subtotal amount, shipping cost, tax and total amount. The complex calculation can be achieved using an activity. In order to solve this business case, Developers can create a Declare OnChange rule and add properties in the Properties To Watch section to execute an activity when those properties change.

Tip: Make sure the Activity type is OnChange. You can set the Activity type in the Security tab of the Activity Rule. The activity can call or branch to other activities, but only if they too have an Activity Type of OnChange.
Caution: Use a Declare OnChange rule for calculations only when a declare expression is not suitable.

Suspend work object

Declare OnChange rules can force all processing on a work item to be suspended pending an independent review of the situation by using one or more flows to support the independent reviews. This feature can support compliance, fraud detection, and quality control staffs.

For example, when an unexpected business exception occurs, such as a negative subtotal in an online shopping cart, you can use a Declare OnChange rule to check changes to the subtotal property. A when rule can be used to check if the subtotal is negative and determine if work needs to be suspended on the object.


Design the OnChange activity to execute quickly, as some properties may change values often.

Properties may change values, and thus cause the rule to run, during development and testing tasks. For example, the preview of a harness or flow action form.

Testing and debugging

Use the Tracer to watch the evaluation of a Declare OnChange rule. Start the Tracer and select a requestor session. In the Tracer Settings, ensure you check Declare OnChange in the Event Types to Trace section. Also check the RuleSet that contains the rule to be traced.

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