Submit Documentation FeedbackJoin Developer CommunityLog In

Rule Types by context

This topic provides an overview of B2B Commerce's rules engine components and Rule Types.

Persona Rule Types

A persona is built on the user and customer characteristics that you add to a persona rule. You select these characteristics from groups of similar characteristics like the data fields on the Customer screen. You can also use characteristics outside of the Admin Console like the shopper's location. The groups of similar characteristics appear in the Rule Type drop down field in the Rules Tab. When you choose a Rule Type the remaining fields in the Rule Tab are updated to display only the fields you need to complete for that Rule Type. The following tables list each Rule Type and the data fields that must be completed to build the persona rule.

User Custom Properties
Custom Property Name
Comparison Operator
Customer Fields
Criteria Property
Comparison Operator
Distance from a Point
Location Phrase
Customer Custom Properties
Custom Property Name
Comparison Operator
Current Location
Criteria Property
Comparison Operator

Rules Engine Components

Rule Manager

RuleManager is the container class that is attached to Entities to allow that Entity to have a RulesEngine, you define 0 or 1 RuleManager per instance of an Entity. For example, you may have several different Persona's and you create a RuleManager for each Persona and define the RuleClauses inside that RuleManager that makes the current user qualify to be of that Persona. Another example is for each different Carrier, you define a RuleManager that makes the current order qualify to be shipped using that Carrier.

Rule Clauses

RuleClause defines the actual rules to be run and the Condition, Grouping, and Order in which they run. CriteriaType is always copied from the CriteriaType in the RuleTypeOption selected for the RuleClause. Depending on the CriteriaType, CriteriaObject and CriteriaProperty may be copied from the RuleTypeOption, if they are copied, then they would not be selectable in the UI. The other properties are set by the user in the UI.

Rule Type

RuleType contains the allowed rules defined for a RuleManager's RuleClauses.

  • Persona - used to assign a person in context within the site context. This is determined on initial access to the site, on sign-on and when the shipping address changes.
  • Category - this is used by the Dynamic Category feature to determine the rules for a given category from which it determines which products to assign it
  • Shipping - this is used by the Shipping Engine for an order to determine which carriers and carrier/services are available to the user based mostly on location and product information
  • Promotion - this is used by the Promotion Engine to determine which promotions are available to an order.

RuleType and its collection of RuleTypeOptions are the definitions for the UI for the available RuleClauses that a user can add to a RuleManager. For example, in the Admin Console you can create a RuleType for Personas. In that RuleType you can add RuleTypeOptions for the Customer object allowing a RuleClause to be created allowing the user to select any field from the Customer and compare the value or range of values of that field. What the RuleTypeOption allows/validates is based on the ICriteriaType the user chooses for that RuleTypeOption.

Rule Type Option

RuleTypeOption defines the rules that are available when adding a RuleClause, the RuleTypeOption for example might be defined that the Criteria Type is Object and the CriteriaObject is Customer and the CriteriaProperty is All Properties, then, when adding a RuleClause, in the UI it would generate the screen such that the user can select one of the properties from the Customer object and compare it's value. The CriteriaType must match the DisplayName field of a registered ICriteriaType.


The base class for all criteria type's.


ICriteriaType implementations get registered in the IOC container and their DisplayName properties populate the drop down to select a CriteriaType for a RuleTypeOption. These classes are the main drivers for the Rules Engine, the Validate method is called returning true to indicate the rule passes or false if the rule fails.

CriteriaTypeObject (example)

Allows creating rules to check values of entity properties. Requires an instance of the entity being checked to be passed in to the rules engine list of context objects.


The concrete implementation and generic Rules Engine for Epi B2B Commerce. Both the Execute and ValidateRule methods in RulesEngine class are defined as virtual. This means that when creating a new RulesEngine it might be beneficial to derive from the RulesEngine base class.

Execute method

Executed the rules and returns the pass or fail result as a Boolean. The input object must have an associated RuleManager object. If the RuleManager is null then a result of true is returned because default objects might not have any associated rules. If a RuleManager is available then the RuleClauses property of the RuleManager is used to then iterate through the rule groups and processes the conditions.

ValidateRule method

Validates one of the rule clauses by calling the appropriate CriteriaType's implementation of the validate method. It first retrieves the valid ICriteriaType object using the CriteriaTyepFactory. The enumerable context is then interrogated to find a context object with a type that matches the object type required for the current RuleClause. If no context is found then the RuleClause is validated without any context.


The RulesEngine.Execute method gets passed in to it the entity containing the RuleManager and a list of objects that contain the context information (like CustomerOrder, UserProfile etc.) that the RuleClauses will validate against.

Field Level Data

The following will define those fields that are not obvious. This is from a data perspective - the next section will define how to implement the UI.

Table/Field or PropertyDescription
CriteriaTypeNote that these fields are not in the database
DependencyNameThis is an attribute of the class and is used to identify the class in RuleTypeOption and RuleTypeClause
LookupObjectThis is used to define a specific entity that will be used to find a single instance of the entity and embed it's Guid (ID) into RulesClause.SimpleValue.
CriteriaObjectThis is the fixed object that must be passed into the rule in order to evaluate the logic. This is used extensively for CustomerOrder-specific rules for Shipping and Promotion engines.
DisplayNameThis is what will display as the criteria in the UI
RequiresCriteriaObjectThis Boolean indicates if the UI needs to prompt for the criteria object itself. Currently, this is only set to True for Object and CustomProperty criteria.

This and CriteriaObject are mutually exclusive - only 1 should be selected in a class but neither needs to be selected if the criteria can be evaluated without a specific object passed in (i.e. context objects)
RequiresCriteriaPropertyBoolean to define for prompting of the CriteriaPriorty in the RuleTypeOption
RequiresCriteriaValueBoolean to define for prompting of the CriteriaValue in the RuleTypeOption
CriteriaValueLabelThis should become obsolete - it is superseded by the parameter descriptions
RequiresValueTypeBoolean to define if a data type will need to be defined for the CriteriaValue - this should mostly be obsolete since the Custom Properties are now aware of their types. Authenticated still may need this but we'll try to eliminate that as well.
RequiresGeoCodeBoolean to define if this is a distance-related rule
ValidRuleClause ComparisonOperatorsThis is used to define the specific comparison values that are valid in the UI. If nothing is specified, all comparisons are available. Examples below:


Parameter DescriptionsExamples below - this is used to explicitly define the parameter values that can be acquired through the UI. This will override the values above and

{ nameof(RuleClause.SimpleValue), new CriteriaTypeParameter { Label = "Category" } },

{ nameof(RuleClause.CriteriaValue), new CriteriaTypeParameter { Label = "Quantity or Amount", PossibleValues = new[] { "quantity", "amount" } } },

{ nameof(RuleClause.ValueMinimum), new CriteriaTypeParameter { Label = "Minimum Value" } },

{ nameof(RuleClause.ValueMaximum), new CriteriaTypeParameter { Label = "Maximum Value" } }
DescriptionThis is used in the rule clause dropdown to select a rule to configure
CriteriaTypeThis is a pointer back to the CriteriaClass plugin using the DependencyName from the class
CriteriaObjectThis is an optional field defining the object to use when applying the criteria. The criteria itself defines if this is captured (i.e. Object, CustomProperty) while most criteria types define this internally.

This currently only applies to CriteriaTypes Object and CustomProperty.
CriteriaPropertyThis field is optional and used differently depending on the nature of the criteria type and is prompted for only if the CriteriaType itself indicates RequiresCriteriaProperty.

If the criteriatype is Object, then this will define a specific property of the CriteriaObject or "All Properties" meaning that the RuleClause can pick it.
ValueTypeIf there is a 'secondary parameter' required or a custom property, this allows the user to select the type of data to acquire in the rule clause. Valid values include String, Decimal, Boolean, and Date)
NameThis is the name of the RuleType for readability - the RuleTypeId is actually the referential link from the RuleType to the RuleManager
ExecutionGroupThis defines a group of rules that have to be evaluated together to get a single Boolean value. Consider this a way to add parenthesis to the logical test
ExecutionOrderThis is the sequence in which the rules are evaluated within a group
ConditionThe valid values are AND and OR. The condition applies to the "next" rule clause, so if this is the last entry in a group, the logical applies to the next group or individual rule.
CriteriaTypeThis is a pointer to the actual CriteriaType class and embeds the DependencyName field into the database as a reference - this is duplicated from the RuleTypeOption for performance
CriteriaObjectThis is the object that will be used to apply the test against the rule.

If the CriteriaType defines RequiresCriteriaObject = true, then it comes from the RuleTypeOption.CriteriaObject, otherwise it comes from CriteriaType.CriteriaObject. This field can be empty.
CriteriaPropertyThis stores the specific object property selected if the criteria type is "Object" and used to store the custom property if the criteria type is "Custom Property".

For CustomProperty it used to store the entity containing the custom property (i.e. ProductProperty, CustomerProperty) but since all custom properties are in the same place, we decided to move the custom property name into the CriteriaProperty field.

This field also stores the "geolocation string" if the CriteriaType defines RequiresGeoCode = true.
CriteriaValueThis stores an "additional value" that must be acquired from the user.

This is driven from the CriteriaType Dictionary if the CriteriaValue is included. An example will be "Distance From a Point" has to capture whether the distance (simple Value) is "Miles" or "Kilometers"
ComparisonOperatorThese are defined as enums and includes:
Not Equals
Matches (a regex expression)
Range (prompts for min and max values)
List (prompts for a comma-separated list)
Contains (better descriptor than 'equals')
DoesNotContain (better descriptor than 'not equals')
SimpleValueThis is the simple value entered for the rule - it is typically a Guid for a lookup or the key value to compare to (i.e. Date >= mm/dd/yy)
ValueListIf the ComparisonOperator = List, then this becomes a list of values that the system will use to look up valid values - this will only work for simple string or number values - it cannot be a list of guids
ValueMinimumThis is used if the ComparisonOperator = Range or for lookups with a secondary value - it is a string value and numbers/dates can be used
ValueMaximumThis is used if ValueMinimum is being used - it is the upper bound of the range

Did this page help you?