Chartwell/Books/Accounting/Endorsement.txt

Endorsement Module – Optimized RAG Knowledge Base

Chunk 1: Module Overview
Metadata: module=Endorsement, type=overview, location=CMH.HFA.Accounting.Orchestration/src/Endorsement, domain=monetaryEndorsements, purpose=midTermAdjustments, count=4
Purpose: Lambda functions and services for processing monetary policy endorsements (mid-term premium/fee changes requiring accounting transactions)
Scope: Handles both upward endorsements (premium increases) and downward endorsements (premium decreases) through dual invoice/credit memo workflow
Components: MonetaryEndorsementLambda, MonetaryEndorsementService, EndorsementIssuedEventPayload, IMonetaryEndorsementService
Integration Points: Oracle Fusion AR (invoice/credit memo posting), Oracle OIC (memo line lookups), endorsement event workflows
Key Concepts: Monetary endorsement, mid-term adjustment, premium/fee change, invoice generation, credit memo creation, transaction line building, bidirectional adjustments

Chunk 2: MonetaryEndorsementLambda Functions
Metadata: component=MonetaryEndorsementLambda, type=Lambda, operations=2, pattern=serviceWrapper, deployment=serverless
Description: Lambda wrapper providing endpoints for endorsement processing
Operations:

GetCreditMemoForEndorsement: Handles net decreases (Premium + Fee < 0), delegates to MonetaryEndorsementService.MapCreditMemo, returns CreditMemo or null
GetInvoiceForEndorsement: Handles net increases (Premium + Fee > 0), delegates to MonetaryEndorsementService.MapInvoice, returns OracleInvoice or null
EndorsementDto Model: Contains OracleCustomer, OracleInvoice, EndorsementIssuedEventPayload; supports tuple deconstruction
Lambda Config: Execution role policies, 256 MB memory, 30 sec timeout

Chunk 3: EndorsementIssuedEventPayload Model
Metadata: model=EndorsementIssuedEventPayload, type=eventPayload, requiredFields=4, purpose=endorsementData
Properties:

AccountIdentifier: Required
PolicyNumber: Required
PremiumAmount: Decimal (positive = charge, negative = credit)
FeeAmount: Decimal (positive = charge, negative = credit)
Use Cases: Coverage additions/removals, premium adjustments, fee changes, any mid-term change affecting accounting
Validation: Required enforced via required keyword

Chunk 4: MonetaryEndorsementService Core Logic
Metadata: component=MonetaryEndorsementService, interface=IMonetaryEndorsementService, pattern=multiStage, purpose=documentGeneration
Description: Transforms endorsement events into Oracle AR documents
Processing Flow: Initializes EndorsementArgument, retrieves memo lines, builds transaction lines, generates CreditMemo or OracleInvoice, returns null if no lines
Memo Line Retrieval: Calls IMemoLookup.GetMemoLookupAsync filtered by action, lineType (Premium/Fees), productType, state, organization, commission percent
Document Construction: Maps transaction type, sets business unit/legal entity, links to original invoice
Null Return: Returns null if validation fails or amounts zero

Chunk 5: Transaction Line Building Logic
Metadata: operation=BuildTransactionLines, pattern=conditionalGeneration, lineTypes=2, validation=multiCriteria
Processing Stages:

Skip Validation: Skip if zero total amount or opposite sign amounts
Premium Lines: Generate if PremiumAmount ≠ 0
Fee Lines: Generate if FeeAmount ≠ 0
Commission Enrichment: Apply commission metadata
Line Numbering: Sequential numbering
Details: Uses GetPremiumLookups/GetFeeLookups, calculates distribution percentage, uses C# yield return

Chunk 6: Zero Amount and Validation Rules
Metadata: validation=endorsementRules, skipCondition=zeroAmount, errorCondition=oppositeSigns

Zero Total Amount: Premium + Fee = 0 → skip transaction lines
Opposite Sign Validation: Throws InvalidOperationException if Premium and Fee have opposite signs
Error Message: "Premium and fee amounts cannot have opposite signs"
Skip Decision: ShouldSkipProcessing method combines checks

Chunk 7: Memo Line Filtering Dimensions
Metadata: operation=GetMemoLines, dimensions=7, pattern=multiDimensionalFiltering
Filtering Parameters: Action, LineType, ProductType, State, Organization, Percent, To (not used)
Methods: GetPremiumLookups / GetFeeLookups
Purpose: Ensures correct GL account selection based on endorsement context

Chunk 8: Commission Line Detection and Enrichment
Metadata: operation=commissionEnrichment, detection=descriptionBased, types=2
Detection: MemoLine.Description contains "Retail Commission" or "HFA Commission"
Fields Applied: BusinessGroup, NewOrRenewal, CommissionPercent, AgencyFirstWrittenDate
Retail Commission: Producer=Clayton Retail, SubProducer/CommissionReference included
HFA Commission: Producer=HFA, SubProducer/CommissionReference empty
Purpose: Ensures commission metadata propagated to transaction lines

Chunk 9: Amount Distribution and Rounding
Metadata: operation=CalculateUnitPrice, rounding=differential, recipients=3
Distribution: amount * distributionPercentage / 100
Rounding Rules:

Assurant Payable → Round UP (Math.Ceiling)
Commission Lines → Round DOWN (Math.Floor)
Other Lines → Banker's rounding (MidpointRounding.ToEven)
Purpose: Penny-perfect allocations matching original invoice

Chunk 10: Credit Memo Construction
Metadata: operation=BuildCreditMemo, documentType=CreditMemo, purpose=downwardEndorsement
Properties: TransactionId empty, TransactionType from mapping, BusinessUnit HFA BU, CurrencyCode USD, GenerateBill=No
Customer References: PurchaseOrderNumber=PolicyNumber, CustomerAccountNumber, Bill-To site
Dates: TransactionDate=Today, AccountingDate=Today
Original Invoice Link: PolicyTermOriginalInvoice
Transaction Lines: ReceivablesCreditMemoLines array from BuildTransactionLines

Chunk 11: Invoice Construction
Metadata: operation=BuildInvoice, documentType=OracleInvoice, purpose=upwardEndorsement
Properties: TransactionId empty, TransactionType mapped, PaymentTerms=1 Pay Plan, ProductType/PremiumPayable/InstallmentFee inherited
Customer References & Dates: Same as CreditMemo
Original Invoice Link: PolicyTermOriginalInvoice
Transaction Lines: Sorted & renumbered array from BuildTransactionLines
Physical Address State: From original invoice for tax continuity

Chunk 12: Transaction Type Mapping
Metadata: concept=transactionTypeMapping, dimensions=2, values=InternalExternal
Invoice Types: HfaInvEndorseInt / HfaInvEndorseExt
Credit Memo Types: HfaCmEndorseInt / HfaCmEndorseExt
Logic: Switch on original invoice TransactionType; internal sources → Int-suffixed, external → Ext-suffixed
Purpose: Maintains Internal vs External classification

Chunk 13: Transaction Line Ordering
Metadata: operation=ArrangeTransactionLines, sorting=multiCriteria, renumbering=sequential
Priority: 1. Premium-Assurant Payable, 2. Commission, 3. Fees, 4. Other
Tie-Break: Original insertion order
Post-Sort: LineNumber reassigned sequentially
Purpose: Consistent invoice presentation, downstream processing

Chunk 14: EndorsementArgument Helper Class
Metadata: class=EndorsementArgument, visibility=private, pattern=contextObject, purpose=encapsulation
Properties: Customer, OriginalInvoice, Payload, TransactionLines
CommissionLine Property: Returns commission line if present; else default with 30% commission
Purpose: Simplifies service method signatures, safe commission access

Chunk 15: Bill-To Site Resolution
Metadata: operation=GetBillToSiteNumber, pattern=LINQ, errorHandling=exception
Logic: Traverse Customer → Accounts → Sites → SiteUses where Purpose="Bill To", select Site, throw if not found
Error Message: "No Bill To site found for customer"
Purpose: Oracle site number for invoice/credit memo

Chunk 16: Organization Determination
Metadata: operation=GetOrg, values=2, source=commissionLine
Logic: CommissionLine.CommissionOrganization = "Clayton Retail" → "Retail", else "HFA"
Purpose: Organization context for memo line filtering & GL selection

Chunk 17: Endorsement Workflow Integration
Metadata: workflow=endorsementProcessing, trigger=endorsementIssuedEvent, outputs=2possible
Trigger: EndorsementIssuedEvent from policy system
Decision: Caller determines GetCreditMemo vs GetInvoice based on net amount
Paths: CreditMemo if net decrease, Invoice if net increase
Downstream: Oracle OIC → Fusion AR
Audit Trail: PolicyTermOriginalInvoice link

Chunk 18: Use Case Examples
Metadata: useCases=endorsementScenarios, frequency=midTerm, complexity=variable

Coverage Addition → Invoice with premium + commission
Coverage Removal → CreditMemo reversing premium + commission
Premium Adjustment (risk change) → Invoice/CreditMemo based on direction
Fee Adjustment → Appropriate document with fee lines
Combined Changes → Single endorsement with net premium/fee change
Validation → Premium increase + fee decrease of equal amount → exception

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

"How are monetary endorsements processed?"
"What creates endorsement invoices vs credit memos?"
"How are endorsement transaction lines built with GL accounts?"
"What validation rules apply to premium and fee amounts?"
"How is commission metadata applied?"
"What rounding logic is used for endorsements?"
"How are Internal vs External transaction types determined?"
"What happens if premium + fees = 0?"
"How do endorsements link to original invoices?"
"What memo line filtering criteria are used?"
"How are commission lines detected/enriched?"
"What is the transaction line sorting order?"
"How does the service handle missing commission lines?"
"Which Lambda functions process endorsements?"
"How are Bill-To sites resolved?"
"What default commission % is used?"
"How does organization determination affect processing?"
"What exception occurs with opposite sign premium/fee?"
"How are endorsement dates set?"
"Which Oracle document properties inherit from original invoice?"