StructuredTags Module – RAG Knowledge Base

Chunk 1: Module Overview
Metadata: module=StructuredTags, type=overview, location=CMH.HFA.Accounting.Orchestration/src/StructuredTags
Purpose: Configuration-driven GL account mapping for Oracle Fusion
Functionality: Retrieves memo line configurations from Oracle OIC API, parses structured tags, filters by temporal validity and business criteria, generates transaction lines for invoices/credit memos with correct GL accounts
Key Concepts: memo line lookup, structured tag parsing, GL account mapping, multi-dimensional filtering, temporal validity, distribution calculation

Chunk 2: MemoLookup Service
Metadata: component=MemoLookup, type=service, interface=IMemoLookup, integration=OracleOIC
Description: Retrieves and filters memo line configurations from Oracle Integration Cloud
Methods:

GetMemoLookupAsync(DateTime): Retrieves active memo lines for a date, normalized to Eastern Time, filters by start/end validity
GetMatchingLines(List<MemoLine>, string?, string?, string?, string?, string?, string?, string?, string?): Filters memo lines using up to 8 optional criteria (action, type, productType, org, product, state, percent, to)
Integration: Extends OracleIntegrationBase, calls CHI_LOOKUP_API with LookupType=CHI_HFA_LOOKUPS
Temporal Logic: Compares normalized ET against StartDateActive / EndDateActive for validity

Chunk 3: MemoLine Configuration Model
Metadata: component=MemoLine, type=model, purpose=GLAccountConfiguration
Description: Represents a single GL mapping rule with metadata and structured business rules
Properties: Code, Meaning, Description, EnabledFlag, StartDateActive, EndDateActive, Tag (semicolon-delimited)
Methods: IsAction, IsType, IsProductType, IsOrg, IsState, IsPercent, IsProduct, IsTo (dimension checks), GetDistributionPercentage (allocates percentage from tags)
Pattern: Lazy initialization of StructuredTag parser for performance

Chunk 4: Structured Tag Format
Metadata: component=StructuredTag, type=parser, format=keyValuePairs
Format: Semicolon-delimited key=value pairs, comma-separated values
Example: Actions=Issue,Renew;Types=Premium;Distribution=70;Org=Retail
Syntax:

Inclusion: Key=Value1,Value2 (whitelist)
Exclusion: Key=!Value1 (blacklist)
Mixed: Supports inclusion and exclusion in same tag
Parsing: Case-insensitive, splits semicolons then equals, comma-separated values become collections

Chunk 5: Filtering Dimensions
Metadata: concept=filteringDimensions, type=businessRules, count=8
Dimensions:

action – transaction operation type (Issue, Renew, Endorse, Cancel, BillingPlanChange, BillingTypeChange)
type – line classification (Premium, Fees, AR Clearing)
productType – insurance product filter (VSC, GAP, ESC)
org – organization (Retail, HFA)
product – specific product codes
state – jurisdiction/state code
percent – commission percentage
to – recipient targeting (Assurant, others)
Logic: Missing dimension = wildcard, present dimensions must match

Chunk 6: Distribution Calculation
Metadata: component=MemoLineFilter, type=extensionMethod, purpose=amountAllocation
Method: GetDistributionAmountByAssurantStatus(this MemoLine, decimal) – calculates allocated amounts with recipient-specific rounding
Rounding Rules:

Assurant + 70/30: round up (Math.Ceiling)
Non-Assurant + 70/30: round down (Math.Floor)
Assurant + other splits: away-from-zero rounding
Non-Assurant + other splits: banker's rounding (ToEven)
Purpose: Prevents penny discrepancies, ensures totals net to zero

Chunk 7: TagValue Inclusion/Exclusion Logic
Metadata: component=TagValue, type=collectionLogic, pattern=setMatching
Behavior: Maintains separate inclusion/exclusion sets (HashSet<string>)
Matching Logic:

Empty set → false
Blacklist only → true unless excluded
Whitelist only → true if included
Mixed → true if included AND not excluded
Parsing: Exclamation prefix = exclusion, unprefixed = inclusion

Chunk 8: Use Cases
Metadata: type=useCases, consumers=multiple

Invoice Commission Processing: Filters by action/org/percent/state
Endorsement Processing: Filters by action/type/productType
Billing Changes: Queries BillingPlanChange or BillingTypeChange actions
Cancellation Processing: Filters Cancel action with product/state
Time-Based Retrieval: Uses transaction creation date to fetch historically accurate configurations

Chunk 9: Integration Architecture
Metadata: type=architecture, pattern=configurationDriven
Design: Separates business rules (OIC lookup tables) from code logic
Benefits: Operations teams can modify GL mappings without code deployment; changes effective immediately; maintains audit trail with temporal validity
Pattern: Specification pattern for multi-criteria filtering, lazy loading, permissive defaults
Timezone Handling: Normalizes all dates to America/New_York for consistent evaluation

Chunk 10: Search Queries Supported
Metadata: type=queryPatterns, purpose=RAGRetrieval
Sample Queries:

"How do I filter memo lines by commission percentage?"
"What is the rounding logic for Assurant payable lines?"
"How are structured tags parsed and evaluated?"
"What dimensions can I use to filter GL account mappings?"
"How does temporal validity work for memo line configurations?"
"What is the format of structured tags?"
"How do exclusions work in memo line filtering?"
"Where do memo lines come from in the system?"
"How do I calculate distribution amounts for transaction lines?"
"What is the difference between whitelist and blacklist filtering?"