TABLE OF CONTENTS
The Rulesets page allows you to add, configure, and manage rulesets.
The Business Rules Engine (BRE) provides a tool to evaluate user-defined rules against application data, including an easy-to-use rule builder directly within the CafeX Platform. The rules can be used in the traditional sense, to drive decision-making and workflows, or to define next best action and visibilities in user interfaces. The BRE allows non-technical users to design if/then/else style rules that can be used to abstract complex business decision-making into maintainable units known as Rulesets.
Understanding Rulesets
A Ruleset is composed of three main components: one or more Input Facts, one or more Result Facts, and one or more Rules.
Input Facts
Input Facts are the data passed into the BRE from the App. The Input Facts need to provide enough information for the Rules to be able to produce the Result Facts. Each Input Fact is defined within the Ruleset by a name and data type, which can be Text, Number, or Boolean (True/False).
The BRE takes a copy of the Input Facts during the Ruleset execution. If the Rules modify the Input Facts, that modification will only exist within the current execution of the Ruleset and will not affect any other part of the App.
Result Facts
Result Facts are the data emitted from the BRE as the result of the Ruleset execution. These facts are made available to the part of the App that executed the Ruleset. Each Result Fact is defined within the Ruleset by a name, data type (Text, Number, or Boolean), and an optional default value. If the default value is provided, it must match the defined data type. The Result Fact will be set to this value at the start of the Ruleset execution before any Rules are processed.
Rules
Rules represent the business logic within the Ruleset. A Rule is declared as a name and description, which are used for identification but have no impact on execution, along with one or more Conditions and one or more Actions that drive the execution.
Conditions determine whether a Rule will be executed. They are read-only and cannot change the state of any of the facts. If a Condition for a Rule is not met, the Action for that Rule will not be executed.
Actions determine how the facts should be manipulated when a Rule is executed. The value assigned or modified by an Action must match the data type of the fact. For example, a fact with a 'number' data type cannot be assigned a text value.
Creating a Ruleset
The Ruleset editor can be accessed through the Rulesets menu item (
) within the App Studio. Selecting this menu item will display a list of all Rulesets for the current App and provide the option to create a new one using the Add new Ruleset button.
To create a Ruleset:
- Navigate to the Rulesets editor and click Add new Ruleset.
- Specify a Name and a Description to clarify the function of the business rule. While these settings don't affect the operation of the Ruleset, the name is used to reference the Ruleset later, so it should be easily identifiable, especially if you are going to have multiple Rulesets within your App.
- Under Options, you can specify how multiple rules are executed. The default setting is Process all rules. Alternatively, you can choose to stop evaluating the Rules as soon as one Rule matches or to stop evaluating the Rules as soon as one Rule doesn't match. In both cases, the Rules are still evaluated in the same order until the evaluation is terminated. For more details on how evaluating multiple Rules works, check the Evaluating multiple Rules section.
- For Input Facts, specify the Name and Type. Click Add fact to add multiple Input Facts.
- For Result Facts, enter the Fact name, Type, and Default value. Click Add fact to add multiple Result Facts.
- For Rules, enter the Name, Description, and then configure Conditions and Actions. Click Add rule to add multiple Rules. Refer to the Complex Conditions section for details on setting up complex conditions.
- Click Create.
Check the sections below for examples of how Rulesets are configured, ranging from basic to more complex scenarios.
Basic Example
Below is a basic example of a Ruleset that indicates if a motorist was breaking the speed limit.
As seen in the screenshot above, we have defined two Input Facts, both of type Number: one for the speed limit and another for the motorist's speed. We've also defined a Result Fact of type True/False to indicate whether the motorist's speed exceeds the speed limit. In this example, the Result Fact defaults to False.
We have created a simple Rule for our Rule Set that can encapsulate the required logic in a single step. The Condition for this rule checks if the Motorist Speed is greater than the Speed Limit. If this condition is met, the Action sets the Is Speeding value to true.
In this example, you can see that the Facts are referenced by wrapping them in braces. To reference the Motorist Speed Fact, for instance, you would need to enter {Motorist Speed} in the field. This syntax is used for both reading existing values and assigning new ones.
Evaluating Multiple Rules
A Ruleset can consist of many Rules. When there are multiple Rules in a Ruleset, they are executed in order from top to bottom as they appear in the Ruleset editor.
By default, all rules in a Ruleset are executed. However, this behavior can be modified in the Options section of the Ruleset editor. The alternative options are either to stop evaluating the Rules as soon as one Rule matches, or to stop evaluating the Rules as soon as one Rule doesn't match. In both cases, the Rules are still evaluated in the same order until the evaluation is terminated.
For our example we will use the default setting of processing all Rules.
In the jurisdiction for our example Ruleset, there is a law that means that the speed limit for trucks is 10mph lower than the posted speed limit. To handle this condition, we have added an Input Fact named 'Is Truck' and a data type of True/False. This Input Fact is used as a Rule Condition to trigger an Action that reduces the speed limit Input Fact for this Ruleset execution.
We now have the necessary Rules to evaluate the additional condition in the Ruleset. However, the new Rule has been added after the previous one. As the Rules are evaluated in order, this means that the latest rule will execute too late to impact the 'Speed exceeds limit' Rule.
To address this, click on the up and down arrows icon at the top of the Rules list to switch the list into reorder mode, allowing the Rules to be dragged and dropped into the desired order. Once the rules are in the correct sequence, click the tick icon to return the list of Rules from reorder mode to edit mode.
Complex Conditions
The Conditions that we have used so far in our examples have been simple, with a single part to each. However, Rules often require more complex Conditions that consist of multiple parts. A Rule can handle this complex Condition with both AND Conditions, where multiple Conditions must all match for the Rule to evaluate, or OR Conditions, where any matching Condition will result in the Rule evaluating.
Let’s extend our example by introducing a new Result Fact called 'Review Incident', which determines whether the incident for which the Rule is being executed needs to be further reviewed. This Fact should return True if the Motorist’s Speed exceeds the Speed Limit by more than 10 mph. We’ll create a Rule with two Conditions, both of which need to be true. We do this with the Add an additional condition button.
To add more complexity, if the vehicle is an emergency vehicle with its lights on, or if it’s an undercover police vehicle, the incident should not be flagged for review.
To achieve this, we will first add the ‘Is Emergency Vehicle', 'Emergency Lights Active', and 'Undercover Police Vehicle' Input Facts, and then add a Rule that evaluates whether both ‘Is Emergency Vehicle' AND 'Emergency Lights Active' are true, OR if 'Undercover Police Vehicle' is true. You can set up the OR condition by clicking the Add an alternative group button underneath the Conditions section.
Testing a Ruleset
After saving a Ruleset in the Ruleset editor, the Test Ruleset button becomes active at the top of the editor.
Clicking Test Ruleset enters the Ruleset test mode. In this mode, there are fields to enter any of the Input Facts. If you leave an Input Fact blank, its default value will apply, if provided. To test the Ruleset, click the Run button. This will execute the Ruleset, populate the Result Facts, and outline which Rules were evaluated, along with the effects they had on the Facts within the Ruleset.
Adding a Data Set that Evaluates a Ruleset
This section explains how to configure a data set to interact with a ruleset and display a warning message when certain conditions are met. As an example, we’ll walk through how to evaluate a ruleset in App Studio that determines whether a motorist was breaking the speed limit. We’ll be using the ruleset created above which evaluates the speed of a motorist and determines if the motorist is breaking a speed limit. If the motorist's speed is greater than the limit, the ruleset will trigger a violation message.
Configuring a Data Set
The data set evaluates the motorist’s speed when it becomes available.
To configure a data set:
- Go to Explorer > App > Configuration.
- Under Data sets, click Add data set and fill in the following details:
Name: speedViolationDataSet
Type: Ruleset
Ruleset: Motorist speed evaluation
Evaluate Automatically: Enable the toggle to automatically evaluate the ruleset as soon as relevant data becomes available.
For each Input, specify the Location, which is a corresponding field or value from the interface that provides the values for the ruleset’s input fields.
Configuring a Text Component to Display an Error Message
If the speed exceeds the specified limit, the ruleset should return a violation message.
To configure an error message:
- Add a Text Component to your canvas.
- Rename the component to speedViolationText.
- Add the following Mustache expression to the Text Component to display the ruleset's warning message: {{speedViolationDataSet.0.warningMessage}}.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article