Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

When condition rules

Updated on May 31, 2022

A When condition rule evaluates a Boolean logic statement that involves comparisons among field values, to return true or false. As a result, you deliver flexible software that adjusts to changing business circumstances.

For example, a When condition rule returns true if a job applicant has more than ten years of experience, and if the applicant speaks French fluently. As a result, an application performs a specific action, such as starting an optional process in a case.

You can apply When condition rules in multiple places in your application. To create more sophisticated logic, you can create multiple conditions, and then apply grouping that meets your business requirements.

Elements of When condition rules

When condition rules are Boolean expressions that consist of three elements:

  • An input value to compare at run time, for example, the value of a field that a user completes.
  • A comparator, for example is greater than or is equal to.
  • A value to compare against the input value from the condition. This value can be a constant that you enter or a reference to another field.
For example: Consider a scenario in which an HR worker can start a background check of a job candidate only if the candidate applies for a managerial position. You can create a When condition rule Position is equal to "Manager", where Position corresponds to a field with which a user interacts at run time. If the user selects Manager as the field input, the When condition rule evaluates to true. The following figure presents this When condition:
Sample when condition
A rule form of a when condition with labels.

Input for When condition rules

As an input value for a When condition rule, you can use any of the following information:

  • A field value
  • A configuration
  • Another When condition
As you build a When condition by applying another When condition, you define whether the input When condition needs to evaluate to true or false at run time instead of selecting a comparator and a test value.

For example, you can create a When condition rule CaseStatus is true, where CaseStatus is another When condition defined as CaseStatus is equal to "Pending-Review". In this scenario, CaseStatus is true evaluates to true if the case status at run time is Pending-Review. For more intuitive development experience, you can easily preview the When condition that you apply as an input value, as shown in the following figure:

When condition preview
When condition rule form showing a preview of an input when rule.

Grouping conditions

You can group conditions by applying AND and OR conjunctions. When you apply AND conjunctions, all grouped conditions need to evaluate to true for a When condition rule to return true. For example, in an application to review job candidates, if you create the conditions French skill is equal to "10" and Work experience is greater than or equal to "10", and you use an AND conjunction, both conditions need to evaluate to true for the When condition to return true. If only one condition evaluates to true, for example, if a candidate has more than ten years of work experience, but the French skill is below 10, overall the When condition evaluates to false.

If you group conditions by using an OR conjunction, any grouped condition needs to evaluate to true for the When condition rule to return true. For example, if you create the conditions German skill is equal to "10" and French skill is equal to "10" and you use an OR conjunction, the When condition evaluates to true if a candidate fluently speaks German or French.

You can mix comparators to meet your business requirements. For example, you can create a When condition rule that determines that a job candidate needs to have at least ten years of work experience and needs to be fluent in either French or German, as shown in the following figure:

Mixed conjunctions
When condition rules showing three conditions and AND and OR conjunctions.

To resolve complex business scenarios, you can use advanced logic to group conditions by entering a logic string. When you apply advanced logic, every condition has an integer assigned that you use in the logic string. In logic strings, you can subgroup conditions and apply nested levels of grouping. A sample logic string is 1 AND (2 OR (3 AND 4)). In advanced logic, you can also use the NOT conjunction.

Referencing When condition rules

Rules of many other rule types can reference When condition rules. For example, you can reference When condition rules in activities, processes, and through the <pega:when> JSP tag in HTML and XML rules in your applications based on Theme UI-Kit.

For example, you can use a When condition rule to define when an optional process starts in a case. For more information, see Conditionally starting a process.


After you complete initial development and testing, you can delegate selected When condition rules to line managers or other non-developers. Consider which business changes might require rule updates and if rule delegation to a user or group of users is appropriate.

For more information, see Delegating a rule or data type.

Conditions in activity steps

Each activity step can reference one or several When condition rules, as preconditions for a method, or transitions between the completed method and the next step.

As a precondition, a When condition rule determines whether the method in the activity step runs. Referenced in a transition, a When condition determines which activity processing runs after the completion of the current activity step.

For more information, see Creating an activity and Configuring steps in an activity.

Standard function

To run a When condition rule in an expression or in the context of Java code, call the standard function callwhen() in the Pega-RULES Default library.

You can view the generated Java code of a rule by clicking ActionsView Java. You can use this code to debug your application or to examine how rules are implemented.


When condition rules are part of the Decision category. A When condition rule is an instance of the Rule-Obj-When rule type.

  • Creating a When rule

    Evaluate a Boolean logical statement that involves comparisons among values of properties, to return true or false, by creating a When rule.

  • Defining conditions for a When rule

    Enter or revise a When rule that can be expressed as a single Boolean expression or the conjunction (AND or OR) of one or more Boolean expressions.

  • Editing a When rule in the legacy mode

    Apply functions and more advanced logic in When rules by editing the conditions in the legacy authoring mode.

  • Configuring advanced options of a When rule

    Define complex logic strings and use functions in conditions by configuring advanced options of a When rule.

  • Specifying pages and classes of a When rule

    Ensure that a When rule accesses or updates information on clipboard pages by specifying the page name and class of the pages. At run time, these pages contain the properties that are referenced on the other tabs of a When rule.

  • More about When Condition rules

    When condition rules help you build application logic so that you can deliver software that dynamically responds to changing business scenarios. When condition rules compare the value of one property reference against a constant, or against the value of another property reference. If you define more than one comparison, you can combine the results with AND, OR, and NOT operations to determine the final true/false outcome.

  • Performing unit testing on a When rule

    For more efficient and detailed debugging, you can test a When rule individually before testing it in the context of the application that you develop. You can also convert the test into a Pega unit test case to validate application data by comparing the expected property values to the actual values that the test returns.

  • Debugging When rules with the Tracer tool

    If your When rule returns unexpected results, and you cannot determine the problem by running the rule and examining the clipboard pages, run the Tracer tool. Using Tracer, you can watch each step in the evaluation of a When rule, and as a result, you can find and then fix issues in your application faster.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us