Customer Segmentation and Catalog Link Rules

This section documents the Maho-specific modules for advanced customer targeting and automated catalog management. These systems extend the core Mage_Rule engine to provide dynamic customer grouping and rule-based product relationships.

Customer Segmentation

The Maho_CustomerSegmentation module allows administrators to group customers dynamically based on various conditions (demographics, purchase history, shopping cart contents). These segments can then be used to target specific shopping cart price rules or trigger automated email sequences.

Core Architecture and Data Flow

The segmentation system relies on a background refresh process that evaluates customers against defined rules and persists the relationships in index tables for high-performance frontend lookups.

Key Classes and Models

• Maho_CustomerSegmentation_Model_Segment: The primary model representing a segment, containing logic for matching and lifecycle management.
• Maho_CustomerSegmentation_Model_Resource_Segment: Handles the heavy lifting of SQL-based matching and persistence to the customer_segment and customer_segment_customer tables.

Segmentation Data Schema

The system uses dedicated tables to manage segment definitions and customer memberships:

Table	Purpose
customer_segment	Stores segment metadata, priority, and serialized rules.
customer_segment_customer	Index table mapping customer_id to segment_id for fast lookups.
customer_segment_email_sequence	Configuration for automated emails triggered by segment entry/exit.
customer_segment_sequence_progress	Tracks customer progress through multi-step email drip campaigns.

Segmentation Execution Flow

The following diagram illustrates how a customer is matched against a segment and how that information is utilized by the system.

Segmentation Matching Logic

Email Automation and Coupon Generation

Maho introduces an automated email sequence system within the Customer Segmentation module. This allows for "Drip Campaigns" where customers receive a series of emails after entering or exiting a segment.

Automation Components

• Trigger Events: Customers can trigger sequences on enter (added to segment) or exit (removed from segment).
• Step Management: Sequences are composed of steps with specific delay_minutes and max_sends per customer.
• Coupon Generation: Steps can be configured to generate unique coupons using a coupon_sales_rule_id and optional coupon_prefix. The Mage_SalesRule_Model_Resource_Coupon resource handles persistence of these unique codes app/code/core/Mage/SalesRule/Model/Resource/Coupon.php13-23

Coupon Persistence and Rules

Maho utilizes the standard Mage_SalesRule resource models to manage rule-based pricing and coupons.

• Mage_SalesRule_Model_Resource_Rule: Manages the persistence of shopping cart rules, including their association with websites and customer groups app/code/core/Mage/SalesRule/Model/Resource/Rule.php13-31
• Mage_SalesRule_Model_Resource_Coupon: Ensures coupon code uniqueness and handles expiration dates app/code/core/Mage/SalesRule/Model/Resource/Coupon.php33-42

Sources: app/code/core/Mage/SalesRule/Model/Resource/Rule.php13-54 app/code/core/Mage/SalesRule/Model/Resource/Coupon.php13-42

Product Relationship Rules

The Maho_CatalogLinkRule module allows for the automated creation of product relationships such as Up-sells, Cross-sells, and Related Products.

Core Logic and Controllers

Admin management of these rules is handled by Maho_CatalogLinkRule_Adminhtml_Cataloglinkrule_RuleController app/code/core/Maho/CatalogLinkRule/controllers/Adminhtml/Cataloglinkrule/RuleController.php14 The controller handles CRUD operations and AJAX rendering for dynamic rule conditions and actions app/code/core/Maho/CatalogLinkRule/controllers/Adminhtml/Cataloglinkrule/RuleController.php182-192

Rules are applied by mapping POST data to the rule model via loadPost($data) app/code/core/Maho/CatalogLinkRule/controllers/Adminhtml/Cataloglinkrule/RuleController.php85

Entity Relationship: Catalog Link Rules

Sources: app/code/core/Maho/CatalogLinkRule/controllers/Adminhtml/Cataloglinkrule/RuleController.php14-112 app/code/core/Maho/CatalogLinkRule/controllers/Adminhtml/Cataloglinkrule/RuleController.php22-23

Directory Region Management

While not a rule engine, Maho provides advanced management for geographic regions via Mage_Directory. This includes a sophisticated import tool for ISO 3166-2 standards.

Region Import System

The system allows importing states/provinces with localized names from a central repository lib/MahoCLI/Commands/SysDirectoryRegionsImport.php27-32

• CLI Entry Point: SysDirectoryRegionsImport command handles batch imports with options for specific countries and locales lib/MahoCLI/Commands/SysDirectoryRegionsImport.php63-70
• Localization Logic: The importer fetches data and filters names that differ from the English default to populate localized region names lib/MahoCLI/Commands/SysDirectoryRegionsImport.php151-174
• Translations: Uses Mage_Core_Model_Translate to handle the multi-locale nature of the directory data app/code/core/Mage/Core/Model/Translate.php13-28

Region Data Flow

Sources: lib/MahoCLI/Commands/SysDirectoryRegionsImport.php27-32 app/code/core/Mage/Core/Model/Translate.php81-122 app/locale/en_US/Mage_Directory.csv69-87

Catalog Rules and Pricing

Catalog rules provide dynamic discounts at the product level, calculated during indexing or on-the-fly for frontend display.

Core Logic and Persistence

• Mage_CatalogRule_Model_Resource_Rule: Manages the persistence of catalog rules and their application to products. It handles the association between rules, websites, and customer groups app/code/core/Mage/CatalogRule/Model/Resource/Rule.php25-36
• insertRuleData: This method performs the actual insertion of rule results into the catalogrule/rule_product table, considering date ranges and sort orders app/code/core/Mage/CatalogRule/Model/Resource/Rule.php163-188
• Frontend Price Calculation: The Mage_CatalogRule_Model_Observer listens to catalog_product_get_final_price to apply active rules to product prices during storefront rendering app/code/core/Mage/CatalogRule/Model/Observer.php131-169

Rule Date Handling

Maho handles rule validity periods by converting dates to GMT timestamps and ensuring they cover the full day (up to 23:59:59) for the end date app/code/core/Mage/CatalogRule/Model/Resource/Rule.php170-176 Dates are formatted using the locale's database format app/code/core/Mage/Rule/Model/Resource/Abstract.php43-57

Sources: app/code/core/Mage/CatalogRule/Model/Resource/Rule.php13-72 app/code/core/Mage/CatalogRule/Model/Observer.php13-48 app/code/core/Mage/CatalogRule/Model/Resource/Rule.php163-188 app/code/core/Mage/Rule/Model/Resource/Abstract.php43-61

Summary Table: Rule-Based and Dynamic Systems

Feature	Primary Model / Controller	Persistence Table
Customer Segments	Maho_CustomerSegmentation_Model_Segment	customer_segment
Product Relationships	Maho_CatalogLinkRule_Adminhtml_Cataloglinkrule_RuleController	catalog_link_rule
Catalog Price Rules	Mage_CatalogRule_Model_Rule	catalogrule
Shopping Cart Rules	Mage_SalesRule_Model_Rule	salesrule
Region Management	Mage_Directory_Model_Region	directory_country_region

Sources: app/code/core/Maho/CatalogLinkRule/controllers/Adminhtml/Cataloglinkrule/RuleController.php35 app/code/core/Mage/CatalogRule/Model/Resource/Rule.php71 app/code/core/Mage/SalesRule/Model/Resource/Rule.php39