Rule types by content

Describes rule types by content in Optimizely Configured Commerce.

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

RuleManager

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.

RuleClause

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.

RuleType

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.

RuleTypeOption

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 its 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.

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.

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 and so on) 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 its 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 (that is 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 will 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 drop-down to select a rule to configure
CriteriaType	This is a pointer back to the CriteriaClass plug-in 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 (that is 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 (that is 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 (that is 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

Updated over 1 year ago