Fsc Financial Calculations

FSC Financial Calculations

Use this skill when you need custom Apex logic to calculate portfolio performance metrics, recalculate wealth rollups after bulk data operations, or aggregate financial data that falls outside the native FSC Rollup-by-Lookup (RBL) engine. It covers the full decision path from choosing the right calculation mechanism to implementing and testing bulkified Apex batch jobs or Data Processing Engine recipes.

Before Starting

Gather this context before working on anything in this domain:

• Rollup engine in use: Confirm whether the org uses native FSC Rollup-by-Lookup (RBL) triggers, Data Processing Engine (DPE), or both. RBL is the default; orgs on API version 55+ may have migrated to DPE. Check the Wealth Application Config custom setting fields Enable_Rollup_Summary__c and Enable_Group_Record_Rollup__c.
• Object scope: Identify whether the calculation touches only supported objects (FinancialAccount, AssetsAndLiabilities, FinancialHolding) or extends to custom objects or external custodian feed data. Native FSC rollup triggers fire only on the supported set; anything else requires custom Apex or DPE.
• Data volume: Estimate records per household. High-volume orgs (tens of thousands of FinancialHolding rows per account) face row-lock contention when rollup triggers and bulk DML run concurrently. This drives the need for the disable/re-enable pattern.
• Most common wrong assumption: Practitioners assume FSC auto-aggregates all financial data. Native triggers aggregate CurrentValue and QuantityOnHand from FinancialHolding up to the FinancialAccount and household level only. Portfolio performance metrics such as IRR and TWR have no native engine and always require custom implementation.
• Governor limit in play: Each FinancialHolding trigger update fires DML on parent FinancialAccount and potentially the household Account. At scale this exhausts row locks. The fix is to suppress triggers during bulk loads and run FinServ.RollupRecalculationBatchable post-load.

Core Concepts

Rollup-by-Lookup (RBL) Engine

FSC ships with an Apex-trigger-driven aggregation engine called Rollup-by-Lookup (RBL). When a FinancialHolding__c record is inserted or updated, platform triggers increment the CurrentValue__c and QuantityOnHand__c rollup fields on the parent FinancialAccount__c, and then cascade that sum to the household-level Account. This is synchronous and transactional, which works well for single-record or small-batch DML but causes row-lock errors when thousands of holdings are loaded at once. RBL only covers FinancialAccount and Assets & Liabilities object families. Custom objects are out of scope.

Data Processing Engine (DPE) for Large-Scale Aggregation

Data Processing Engine is a batch-mode, no-code/low-code framework that reads source data, applies transformations, and writes results back to Salesforce objects. For FSC, DPE is used either as a replacement for RBL (when migrating away from trigger-based rollups) or as the only viable path for aggregating custom objects and external custodian data. Critical constraint: Salesforce generates a separate DPE definition when converting an existing RBL configuration one-to-one. Running multiple DPE definitions against the same target field concurrently causes lock contention identical to the RBL bulk-load problem. Build DPE recipes from scratch with a single final aggregate node that writes all computed values in one pass.

Custom Apex Batch for Performance Metrics

FSC provides no native calculation engine for time-weighted return (TWR), internal rate of return (IRR), or any holding-period performance attribution. These must be implemented as custom Database.Batchable Apex classes scheduled via System.scheduleBatch or the Apex Scheduler. The batch queries FinancialHolding__c and associated transaction history (stored in custom objects or external objects), performs the calculation in execute() over scope-controlled chunks, and writes results back to a custom performance summary object or directly to FinancialAccount__c custom fields.

Bulk Load Safety Protocol

When loading large volumes of FinancialHolding__c, FinancialAccount__c, or AssetsAndLiabilities__c records via Data Loader or API, the FSC rollup triggers must be disabled for the API user running the load. Disable by unchecking Enable Rollup Summary and Enable Group Record Rollup in the Wealth Application Config custom setting for that user. After the load completes, re-enable the setting and invoke FinServ.RollupRecalculationBatchable to rebuild all aggregates from scratch. Skipping the re-run leaves rolled-up totals stale.

Common Patterns

Pattern 1: Post-Bulk-Load Rollup Recalculation

When to use: Any time records are loaded via Data Loader, Bulk API, or a migration script rather than through the Salesforce UI or a standard single-record API call.

How it works:

1. Before loading, set Enable_Rollup_Summary__c = false and Enable_Group_Record_Rollup__c = false on the WealthAppConfig__c custom setting for the API/integration user.
2. Perform the bulk load.
3. After load completion, re-enable both settings.
4. Invoke FinServ.RollupRecalculationBatchable to rebuild all FSC aggregate values.

// Schedule recalculation immediately after bulk load
FinServ.RollupRecalculationBatchable batchJob =
    new FinServ.RollupRecalculationBatchable();
Database.executeBatch(batchJob, 200);

Why not the alternative: Leaving triggers enabled during bulk load causes row-lock contention on parent FinancialAccount__c records because hundreds of trigger executions try to update the same parent simultaneously within the same transaction window.

Pattern 2: Custom Apex Batch for Portfolio IRR / TWR

When to use: When the org requires performance reporting metrics (IRR, TWR, or custom benchmarking) on client portfolios. No FSC native engine covers these.

How it works:

1. Create a custom object PortfolioPerformance__c (or add fields to FinancialAccount__c) to store computed metrics.
2. Implement Database.Batchable<SObject> with a SOQL start query scoped to FinancialAccount__c records needing recalculation.
3. In execute(), query associated FinancialHolding__c records and any transaction history for each account in the scope chunk.
4. Compute TWR using the modified Dietz method or sub-period linking.
5. DML-write results back in a list (bulkified) at the end of execute().
6. Schedule with System.scheduleBatch or System.schedule for nightly execution.

global class PortfolioTWRBatch implements Database.Batchable<SObject>, Database.Stateful {

    global Database.QueryLocator start(Database.BatchableContext bc) {
        return Database.getQueryLocator(
            'SELECT Id, Name, FinServ__Balance__c ' +
            'FROM FinServ__FinancialAccount__c ' +
            'WHERE FinServ__RecordTypeName__c = 'Investment Account''
        );
    }

    global void execute(Database.BatchableContext bc, List<FinServ__FinancialAccount__c> scope) {
        List<PortfolioPerformance__c> results = new List<PortfolioPerformance__c>();
        for (FinServ__FinancialAccount__c acct : scope) {
            // Query holdings and compute TWR — implementation specific
            Decimal twr = computeTWR(acct.Id);
            results.add(new PortfolioPerformance__c(
                FinancialAccount__c = acct.Id,
                TWR__c = twr,
                AsOfDate__c = Date.today()
            ));
        }
        upsert results FinancialAccount__c;
    }

    global void finish(Database.BatchableContext bc) {}

    private Decimal computeTWR(Id accountId) {
        // Retrieve sub-period returns from transaction history and link
        return 0.0; // placeholder
    }
}

Why not the alternative: Attempting to compute TWR in a trigger or synchronous Apex fails on any meaningful dataset due to SOQL and CPU limits. Batch processing with a manageable scope size (50–200 accounts) is required.

Pattern 3: DPE Recipe for Custom-Object Aggregation

When to use: When aggregation targets custom objects or external custodian data that is not covered by native FSC RBL triggers.

How it works:

1. Build a new DPE definition from scratch — do not convert an existing RBL definition.
2. Source nodes read from the custom object or external data source.
3. Group and aggregate nodes compute the desired rollup (sum, weighted average).
4. A single writeback node at the end of the recipe writes all computed values to the target object.
5. Schedule the DPE batch via the Data Processing Engine configuration in Setup.

Why not the alternative: Converting an RBL definition to DPE one-to-one causes Salesforce to generate a separate DPE definition per RBL rule. Running these concurrently against the same target record causes the same lock contention the pattern is meant to solve.

Decision Guidance

Recommended Workflow

1. Clarify scope and object coverage: Confirm which objects the calculation touches (FinancialHolding, AssetsAndLiabilities, custom, external). Identify whether native RBL is enabled or if the org has migrated to DPE. Check the WealthAppConfig__c setting.
2. Select the right mechanism: Use the decision table above. Bulk load → disable/recalc pattern. Performance metrics → custom batch. Custom objects → DPE recipe from scratch.
3. Implement and bulkify: Write or review the Apex batch or DPE recipe. For Apex batches, verify the execute() scope is bounded (50–200 records for FinancialAccount), DML is outside loops, and Database.Stateful is used only when truly stateful aggregation is required.
4. Handle the disable/re-enable pattern for bulk loads: Update the WealthAppConfig__c setting before and after any bulk DML path. Enqueue FinServ.RollupRecalculationBatchable programmatically or document the manual step explicitly.
5. Write Apex tests with FSC object coverage: Instantiate FinServ__FinancialAccount__c and FinServ__FinancialHolding__c in test data. Assert that computed fields on PortfolioPerformance__c or the target object match expected values after batch execution.
6. Test with bulk volume in a sandbox: Load 5,000+ FinancialHolding rows and verify no row-lock errors occur and rollup totals are accurate post-recalculation.
7. Review governor limit headroom: Confirm the batch does not exceed 50,000 SOQL rows, 10,000 DML rows, or 60-second CPU limit per execute chunk. Adjust scope size if needed.

Review Checklist

Run through these before marking work in this area complete:

• WealthAppConfig__c disable/re-enable pattern is documented or implemented for all bulk load paths
• FinServ.RollupRecalculationBatchable is invoked after bulk loads and tested in sandbox
• Custom Apex batch classes are bulkified — no SOQL or DML inside loops
• DPE recipes use a single writeback node, not one-to-one converted from RBL definitions
• Apex tests cover both the happy path and a bulk scenario (200+ records minimum)
• Performance metric calculations (IRR, TWR) are implemented in scheduled batch, not triggers
• Custom objects and external custodian data are routed through DPE or custom Apex, not assumed to be covered by RBL

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. RBL triggers fire synchronously on every FinancialHolding DML — When any insert, update, or delete on FinancialHolding__c occurs, the FSC trigger immediately updates the parent FinancialAccount__c and household Account. In bulk operations this means hundreds of transactions contending for the same parent rows, producing row-lock errors that roll back the entire batch.
2. DPE auto-conversion from RBL creates one definition per rule — Using the Salesforce migration wizard to convert RBL to DPE generates a separate DPE definition for each RBL configuration entry. Scheduling all of them causes simultaneous writes to the same target fields and replicates the lock contention it was meant to solve.
3. No native FSC engine for IRR or TWR — Practitioners (and LLMs) sometimes assume FSC computes portfolio performance metrics natively. It does not. CurrentValue__c and QuantityOnHand__c are the only aggregated values. IRR, TWR, and benchmark comparisons require fully custom Apex implementation.

Output Artifacts

Related Skills

• admin/financial-account-setup — understand FSC object model and rollup admin configuration before implementing custom calculations