Matrix Logic - ExecuteMatrixLogic

This document details the functionality of the Matrix Logic, specifically the ExecuteMatrixLogic method and its associated helper functions. It explains how matrix parents (headers), children (rows), and items are generated and managed within the App4Sales platform. This process involves retrieving item data, applying user-defined formulas, and persisting the resulting matrix structures. The documentation is aimed at application administrators and implementation consultants to help them understand configuration, predict outcomes, and troubleshoot potential issues.

1. Data Source Configuration

The matrix logic primarily sources its data from the App4Sales internal item database. Configuration settings and formulas are retrieved from various sources, including the Matrix Settings UI, KeySettings, and SyncSettings. The system pulls item data and uses these configurations to generate matrix structures.

2. Data Mapping Table

Axis Formulas

App4Sales Axis	Formula Source	Logic/Notes
Z-axis (Matrix Parent)	MatrixSettings UI (SelectedFieldZ, InstructionZ, OptionalZ) or KeySettings (MatrixFormula_Z)	Determines the top-level grouping (e.g., Style) based on item data. Formulas can involve field extraction (left, right, split), regex, and item class lookups. If null, item is added to itemsToReset.
Y-axis (Matrix Child)	MatrixSettings UI (SelectedFieldY, InstructionY, OptionalY) or KeySettings (MatrixFormula_Y)	Defines the rows describing variant dimensions (e.g., Color). Supports field extraction, regex, and translation via DescriptionFieldLanguageCodes/ItemClassTranslations.
Y-axis Description (Matrix Child Description)	MatrixSettings UI (SelectedFieldY2, InstructionY2, OptionalY2) or KeySettings (MatrixFormula_Y2)	Provides a descriptive label for the Y-axis. Supports translation.
X-axis (Matrix Header)	MatrixSettings UI (SelectedFieldX, InstructionX, OptionalX) or KeySettings (MatrixFormula_X)	Represents columns for another dimension (e.g., Size). Supports field extraction, regex. Headers are de-duplicated.
Matrix Item Code	KeySettings (MatrixFormula_ItemCode)	The actual item code used for the matrix item.
Matrix Description	KeySettings (MatrixFormula_Description)	Description for the matrix.

Item Data Dependencies

Matrix Structure Field	ItemsService Property	Notes
MatrixId	Item.MatrixId	Used for linking items to matrix parents.
HeaderId	Item.HeaderId	Used for linking items to matrix headers.
ChildId	Item.ChildId	Used for linking items to matrix children (rows).
FreeItemFields	Item.FreeItemFields	Customizable fields on the item that can be used in matrix formulas.
ItemClassValues	Item.ItemClassValues	Values used for item class lookups in formulas.
ItemDescription	Item.ItemDescription	Description of the item, potentially used in formulas.
ItemCode	Item.ItemCode	Unique identifier for the item.

Settings Impacting Matrix Generation

Setting Name	Purpose	Default	Impact on Matrix Generation
Sync Matrix Logic Standard	Controls whether the standard matrix logic is executed during a scheduled synchronization.	True	If set to 'False' and `saveResults` is true, the matrix processing will be aborted.
Allow Single Cell Matrix Products	Determines if matrices with only a single cell (one item) are allowed to be created or preserved.	False	If 'False', single-cell matrices will be removed during processing.
Matrix Formula X, Y, Y2, Z, ItemCode, Description	Defines the formulas used to derive matrix axes and item properties during scheduled runs.	(Dependent on configuration)	These KeySettings override MatrixSettings UI fields when processing scheduled synchronizations.
Description Field Language Codes	Specifies language codes for translating description fields used in formulas.	(Empty)	Enables multilingual support for Y-axis descriptions and Z-axis descriptions.
Item Class Translations	Provides translation mappings for item class values.	(Empty)	Used to translate item class values when they are part of a matrix formula.
Customer Item Filter	Filters items based on customer-specific criteria.	(Empty)	If configured, only items matching the filter will be considered for matrix generation.
Selected Field X, Y, Y2, Z, Instruction, Optional	User-defined fields and instructions for formulas within the Matrix Settings UI.	(Dependent on UI selection)	These settings are used when previewing matrices manually and can be overridden by KeySettings during scheduled syncs.

3. Special Logic & Filters

Entry Conditions & Guards: Processing is aborted if Sync Matrix Logic Standard is 'False' and saveResults is 'True'. The saveResults flag determines if changes are persisted, and refreshItemsCacheFirst controls whether the item cache is refreshed prior to processing.
Cache Refresh: If refreshItemsCacheFirst is 'True', the CacheManager.Instance.RefreshDataServiceCache is invoked, using specific URLs and portal authentication to ensure up-to-date item data.
Script Hooks: Custom scripts can be executed before and after the matrix processing via CheckForMatrixItems hooks, allowing for flexible extensions or validations.
Conditional Logic: Filters skip or include records based on formula evaluations. For instance, if a Z-axis formula evaluates to null, the item is skipped for matrix generation and marked for reset.
Error Handling: The system handles cases like missing mandatory formulas, missing item class lookups, and situations where all items would be reset. Duplicate cell detection is also performed during preview.
Single-Cell Matrix Removal: If the Allow Single Cell Matrix Products setting is 'False', any generated matrices containing only one item will be automatically removed.

4. Domain Specifics / Extension Section

Configuration Inputs

The generation of matrix structures is heavily influenced by various configuration inputs, allowing administrators to customize how items are grouped and displayed.

MatrixSettings UI: When manually previewing matrices, the system uses fields configured directly in the Matrix Settings user interface, such as SelectedFieldX, Instruction, and Optionals, to define the matrix formulas.
KeySettings: For scheduled synchronizations, specific KeySettings override the UI settings. These include MatrixFormula_X, MatrixFormula_Y, MatrixFormula_Y2, MatrixFormula_Z, MatrixFormula_ItemCode, and MatrixFormula_Description. These settings define the formulas for each axis and other item properties.
SyncSettings: The Sync Matrix Logic Standard setting within SyncSettings plays a critical role in enabling or disabling the execution of the standard matrix logic during automated synchronization processes.
Scripts: The platform supports custom script execution via CheckForMatrixItems hooks. These scripts can introduce additional logic before and after matrix processing, allowing for advanced validations or data manipulations.

Formula Logic

Matrix formulas are the core of how items are structured into matrices. They define how data from item fields is used to create the X, Y, and Z axes, as well as descriptions and item codes.

Valid Columns: Formulas can reference standard item fields such as itemcode, description, itemclass, and values within freeitemfields.
Instructions: A variety of instructions are available for processing field values:
- left: Extracts a specified number of characters from the beginning of a field.
- right: Extracts a specified number of characters from the end of a field.
- split: Divides a string into parts based on a delimiter and selects a specific part.
- splitleft: Splits a string and takes the left part.
- splitright: Splits a string and takes the right part.
- regex: Uses a regular expression to extract or transform parts of a string.
- Item Class Lookups: Special instructions can be used to perform lookups against item class translations.
Optional Parameters: These parameters fine-tune instruction behavior, controlling aspects like substring lengths, delimiters for split operations, or specific groups for regex matches.
Translation Support: Formulas for descriptions (Y-axis and Z-axis) and item class lookups can leverage translation dictionaries configured via DescriptionFieldLanguageCodes and ItemClassTranslations. This ensures that matrix elements can be displayed in multiple languages.

Processing Flow

The ExecuteMatrixLogic method orchestrates a multi-step process to generate and update matrices:

Entry Conditions Check: Verifies critical settings like Sync Matrix Logic Standard and flags like saveResults and refreshItemsCacheFirst to determine if processing should proceed.
Cache Refresh: If refreshItemsCacheFirst is true, the CacheManager.Instance.RefreshDataServiceCache is called to ensure all item data is current.
Pre-processing Script: The CheckForMatrixItems script hook is invoked, allowing for custom logic before item evaluation.
Item Data Retrieval: Item data is retrieved from ItemsService.GetAllSync, specifically selecting properties relevant to matrix generation such as ItemCode, MatrixId, HeaderId, ChildId, FreeItemFields, ItemClassValues, and ItemDescription.
Item-by-Item Evaluation: Each item is processed individually by GenerateMatrixDataForItem:
- Z-axis (Parent) Evaluation: The formula for the Z-axis is evaluated. If it results in a null value, the item is added to an itemsToReset list and skipped for matrix generation.
- Y-axis (Child) Evaluation: Formulas for the Y-axis and its optional description are evaluated, incorporating translation dictionaries if configured.
- X-axis (Header) Evaluation: The formula for the X-axis is evaluated, and unique headers are identified and created.
- Object Construction & Re-use: Matrix parent, child, and header objects are built. Existing entries are re-used from internal dictionaries to maintain consistency and assign unique IDs.
- Item Linking: The current item is linked to its corresponding matrix child via MatrixChild.Children.
- Translation Tracking: Translations for matrix parents and children are tracked and associated.
- Reset Tracking: Items for which formulas failed or resulted in null values are captured for potential resetting.
Post-processing Script: The CheckForMatrixItems script hook is invoked again after item evaluation.
Persistence: If saveResults is true, the UpdateAllMatrixData method writes the generated matrix structures to the database. This includes:
- Updating matrix parents, their translations, children, child translations (MatrixChildrenEx), and headers.
- Updating item links via ItemsContext.UpdateMatrixLinks for new item-matrix pairings.
- Performing resets for parent IDs or individual items as identified during evaluation.

Safety Checks & Resets

The system incorporates several safety checks to ensure data integrity and prevent unintended operations:

Mandatory Formula Check: Processing is aborted if mandatory matrix formulas are missing, ensuring that incomplete configurations do not lead to partial or incorrect matrix generation.
Item Class Lookup Failure: If required item class lookups fail, the process is halted.
Mass Reset Detection: The system detects scenarios where all items would be reset due to formula failures. If this occurs, processing is aborted to prevent accidental data loss.
Duplicate Cell Detection: During matrix preview, the system identifies and flags duplicate cells, helping administrators refine their formulas to ensure unique item placement.
Single-Cell Matrix Handling: If the setting Allow Single Cell Matrix Products is 'False', any matrices that would result in only a single item are automatically removed, preventing the creation of trivial matrices.

Outputs

The output of the matrix logic includes the structured matrix data that is persisted in the App4Sales database, as well as preview information for administrators.

Matrix Parent/Header/Child Records: The core output consists of the created or updated matrix parent (Z-axis), header (X-axis), and child (Y-axis) records, which define the structure of the matrices.
Translations: Associated translation records for matrix parents and children are generated and stored, supporting multilingual displays.
Previews: The ShowMatrixPreview and GetCmsNGMatrixPreview functions consume the generated matrices to provide administrators with a visual representation of how their configurations will appear. These previews include row and column ordering, error collection, and item mapping, allowing for validation before full synchronization.
CMS Previews: Changes made by the matrix logic directly affect how matrices are presented in the Content Management System (CMS) previews, ensuring a consistent view for users.

5. Related Settings & Prerequisites

For the matrix logic to function correctly, several settings and prerequisites must be in place:

Sync Matrix Logic Standard: (SyncSettings) - Controls the execution of standard matrix logic during sync operations.
Allow Single Cell Matrix Products: (Application Setting) - Determines if matrices with only one item are permitted.
Matrix Formula X, Y, Y2, Z, ItemCode, Description: (KeySettings) - Define the core formulas for matrix generation during scheduled runs.
SelectedFieldX, SelectedFieldY, SelectedFieldY2, SelectedFieldZ, Instruction, Optional: (Matrix Settings UI) - User-configurable fields for manual matrix preview and formula definition.
Customer Item Filter: (Application Setting) - Can restrict the items considered for matrix generation.
Description Field Language Codes: (Application Setting) - Enables translation for description fields.
Item Class Translations: (Application Setting) - Provides translations for item class values used in formulas.

6. Known Limitations

The documentation assumes that all referenced item fields in formulas (e.g., itemcode, description, freeitemfields) contain valid and expected data.
Complex regex patterns in formulas may require thorough testing to ensure desired outcomes.
The system's behavior regarding edge cases with extremely large datasets and complex formulas is assumed to be handled, but may require performance monitoring.