Rule types by context
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 | This text box is used to determine the User Custom Property that the rule will attempt to compare using the Comparison Operator and Value |
Comparison Operator | This drop-down is used to select the comparison criteria. The options are: Equals, Not Equals, Less Than, Less Than or Equals, Greater Than, Greater Than or Equals, Matches, Range, List |
Value | This text box will hold a value that the Comparison Operator will attempt to resolve against |
Condition | An And/Or option that is used to determine if the rule is intended to resolve in addition to other rules, or if it is supposed to resolve true in an either/or case |
Customer Fields | |
|---|---|
Criteria Property | This drop-down is used to determine the Criteria Property that the rule will attempt to compare using the Comparison Operator and Value |
Comparison Operator | This drop-down is used to select the comparison criteria. The options are: Equals, Not Equals, Less Than, Less Than or Equals, Greater Than, Greater Than or Equals, Matches, Range, List |
Value | This text box will hold a value that the Comparison Operator will attempt to resolve against |
Condition | An And/Or Option that is used to determine if the rule is intended to resolve in addition to other rules, or if it is supposed to resolve true in an either/or case |
Distance from a Point | |
|---|---|
Location Phrase | This text box is used to enter an address that will be translated into a specific Latitude and Longitude by Google Maps |
Latitude | This text box is used to determine the Latitude for the origination point of this rule |
Longitude | This text box is used to determine the Longitude for the origination point of this rule |
Within/Outside | This selector is used to determine if the distance is intended to be within the area originating from the geographic location, or outside of that area |
Distance | This text box and selector is used to determine the numerical distance from the origination point this rule will resolve true for, and if that distance is in Kilometers or Miles |
Condition | An And/Or Option that is used to determine if the rule is intended to resolve in addition to other rules, or if it is supposed to resolve true in an either/or case |
Customer Custom Properties | |
|---|---|
Custom Property Name | This text box is used to determine the Customer Custom Property that the rule will attempt to compare using the Comparison Operator and Value |
Comparison Operator | This drop-down is used to select the comparison criteria. The options are: Equals, Not Equals, Less Than, Less Than or Equals, Greater Than, Greater Than or Equals, Matches, Range, List |
Value | This text box will hold a value that the Comparison Operator will attempt to resolve against |
Condition | An And/Or option that is used to determine if the rule is intended to resolve in addition to other rules, or if it is supposed to resolve true in an either/or case |
Current Location | |
|---|---|
Criteria Property | This drop-down is used to determine the property type for the Location Criteria. The options available are: City, Country/Abbreviation, IDString, Latitude, Longitude, PostalCode, StateAbbreviation. |
Comparison Operator | This drop-down is used to select the comparison criteria. The options are: Equals, Not Equals, Less Than, Less Than or Equals, Greater Than, Greater Than or Equals, Matches, Range, List |
Value | This text box will hold a value that the Comparison Operator will attempt to resolve against |
Condition | An And/Or option that is used to determine if the rule is intended to resolve in addition to other rules, or if it is supposed to resolve true in an either/or case |
Authenticated | |
|---|---|
Value | This checkbox is used to check and see if the user has been authenticated. |
Condition | An And/Or option that is used to determine if the rule is intended to resolve in addition to other rules, or if it is supposed to resolve true in an either/or case |
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.
CriteriaTypeBase
The base class for all criteria type's.
ICriteriaType
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.
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.
RulesEngine
The concrete implementation and generic Rules Engine for Configured 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.
IRulesEngine
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 Property | Description |
|---|---|
CriteriaType | Note that these fields are not in the database |
DependencyName | This is an attribute of the class and is used to identify the class in RuleTypeOption and RuleTypeClause |
LookupObject | This 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. |
CriteriaObject | This 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. |
DisplayName | This is what will display as the criteria in the UI |
RequiresCriteriaObject | This 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) |
RequiresCriteriaProperty | Boolean to define for prompting of the CriteriaPriorty in the RuleTypeOption |
RequiresCriteriaValue | Boolean to define for prompting of the CriteriaValue in the RuleTypeOption |
CriteriaValueLabel | This should become obsolete - it is superseded by the parameter descriptions |
RequiresValueType | Boolean 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. |
RequiresGeoCode | Boolean to define if this is a distance-related rule |
ValidRuleClause ComparisonOperators | This is used to define the specific comparison values that are valid in the UI. If nothing is specified, all comparisons are available. Examples below: RuleClauseComparisonOperator.Equals, RuleClauseComparisonOperator.NotEquals |
Parameter Descriptions | Examples 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" } } |
RuleTypeOption | |
Description | This is used in the rule clause dropdown to select a rule to configure |
CriteriaType | This is a pointer back to the CriteriaClass plugin using the DependencyName from the class |
CriteriaObject | This 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. |
CriteriaProperty | This 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. |
ValueType | If 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) |
RuleManager | |
Name | This is the name of the RuleType for readability - the RuleTypeId is actually the referential link from the RuleType to the RuleManager |
RuleClause | |
ExecutionGroup | This 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 |
ExecutionOrder | This is the sequence in which the rules are evaluated within a group |
Condition | The 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. |
CriteriaType | This 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 |
CriteriaObject | This 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. |
CriteriaProperty | This 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. |
CriteriaValue | This 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" |
ComparisonOperator | These are defined as enums and includes: Equals Not Equals LessThan LessThanOrEqual GreaterThan GreaterThanOrEqual 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') |
SimpleValue | This 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) |
ValueList | If 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 |
ValueMinimum | This is used if the ComparisonOperator = Range or for lookups with a secondary value - it is a string value and numbers/dates can be used |
ValueMaximum | This is used if ValueMinimum is being used - it is the upper bound of the range |