Financial Account Migration

Financial Account Migration

This skill covers bulk migration execution for FSC financial data — the correct object insert sequence, how to suppress Rollup-by-Lookup (RBL) triggers during load to prevent row-lock errors, and how to handle balance history differently depending on whether the org runs the managed package or Core FSC (API v61.0+). It does not cover FSC configuration, object model reference, or non-financial data migration.

Before Starting

Gather this context before working on anything in this domain:

• Confirm whether the org uses the FSC managed package (FinServ__ namespace) or Core FSC standard objects (available from API v61.0 / Spring '25). The balance history migration approach differs fundamentally between the two.
• Check whether "Enable Rollup Summary" is active in Wealth Application Config. If it is, Apex RBL triggers will fire on every DML row and will cause record-lock timeouts at bulk-load volumes.
• Verify that FinancialSecurity records (instrument master data — stocks, funds, etc.) already exist in the target org before any FinancialHolding insert. FinancialHolding has a required lookup to FinancialSecurity; missing records cause immediate load failures.

Core Concepts

1. Six-Layer Insert Order

FSC financial data has strict parent-child and lookup dependencies. The correct order is:

1. Account / PersonAccount — the client record. Every FinancialAccount requires an Account parent.
2. FinancialSecurity — instrument master. Must pre-exist before FinancialHolding can reference it. If your source system includes positions, load securities first even if they appear to be a child concept.
3. FinancialAccount — the account (brokerage, checking, insurance policy, etc.). References Account.
4. FinancialAccountRole — the Primary Owner and any additional roles. References both FinancialAccount and Contact/Account. Load at least the Primary Owner role before loading FinancialHolding or FinancialAccountTransaction.
5. FinancialHolding — individual positions held within a FinancialAccount. References both FinancialAccount and FinancialSecurity.
6. FinancialAccountTransaction — transaction history entries. References FinancialAccount (and optionally FinancialHolding). Load last.

Inverting any step creates foreign-key lookup failures that can only be resolved by deleting and re-inserting downstream records.

2. Rollup-by-Lookup (RBL) and Bulk Load

FSC's Rollup-by-Lookup feature aggregates holding values and transaction totals up to the FinancialAccount and then to the household. The aggregation is implemented as Apex triggers (FinServAssetsLiabilitiesTrigger, FinancialHoldingTrigger, and related classes). During bulk ETL, these triggers fire row-by-row inside the DML transaction and compete for the same FinancialAccount record, causing UNABLE_TO_LOCK_ROW errors at virtually any load volume above a few hundred rows per batch.

Mitigation — pre-load: Disable RBL for the ETL integration user via the Wealth Application Config custom setting (FinServ__WealthAppConfig__c). Set FinServ__EnableRollupSummary__c = false for the dedicated ETL user's profile or use the OmniStudio / Apex custom setting API to set it programmatically before the load job runs.

Mitigation — post-load: After all records are committed, run FinServ.RollupRecalculationBatchable (managed package) or the equivalent Data Processing Engine (DPE) job (Core FSC) to rebuild all rollup values from scratch. This produces a clean, consistent state without incremental trigger races.

3. Balance History: Managed Package vs Core FSC

The two FSC deployment models store balance history differently:

If you apply the managed-package single-field strategy to a Core FSC org you will discard all historical balance data and the org's balance trend charts will be permanently empty.

4. FinancialAccountTransaction — Standard vs Custom

FinancialAccountTransaction is a standard object in Core FSC (API v61.0+). In the FSC managed package it is the custom object FinServ__FinancialAccountTransaction__c. Both exist natively in their respective deployment models; neither is a practitioner-created custom object. Do not attempt to create a replacement custom object — use the platform-provided object for your deployment model.

Common Patterns

Pattern A: RBL-Safe Bulk Load (Managed Package)

When to use: Any bulk insert of FinancialHolding or FinancialAccountTransaction in a managed-package FSC org.

How it works:

1. Before the ETL job: query FinServ__WealthAppConfig__c and set FinServ__EnableRollupSummary__c = false for the ETL user via Apex or the Tooling API.
2. Run Data Loader / Bulk API 2.0 jobs in dependency order (see Six-Layer Insert Order).
3. After all jobs complete: re-enable the setting, then invoke Database.executeBatch(new FinServ.RollupRecalculationBatchable(), 200) via Anonymous Apex or a scheduled job.
4. Validate: query aggregate holding balances and compare to source system totals.

Why not the alternative: Loading with RBL enabled causes UNABLE_TO_LOCK_ROW errors after the first few hundred rows of FinancialHolding in most orgs. Disabling it at the org level (not just the user level) also risks disrupting live advisor users; the per-user setting is the safe scope.

Pattern B: Core FSC Balance History Snapshot Load

When to use: Migrating historical balance data into a Core FSC (v61.0+) org where balance history must be preserved.

How it works:

1. Load FinancialAccount records first (no balance field needed at this stage).
2. For each historical balance snapshot in the source system, create one FinancialAccountBalance record with FinancialAccountId, Balance, BalanceDate, and CurrencyIsoCode.
3. Load snapshots in ascending date order to avoid any UI anomalies in trend charts.
4. The most recent snapshot value is the current balance visible in the UI; no separate field update is needed.

Why not the alternative: Writing a single balance value to the FinancialAccount record (the managed-package approach) is not wrong in Core FSC but discards all historical data. Balance history drives advisory analytics; losing it is typically unacceptable in a migration.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Confirm deployment model and RBL status — Determine whether the org uses the FSC managed package (FinServ__ namespace) or Core FSC standard objects (API v61.0+). Query FinServ__WealthAppConfig__c to check whether FinServ__EnableRollupSummary__c is true. Document the current value so it can be restored after load.
2. Pre-load: disable RBL for the ETL user — Set FinServ__EnableRollupSummary__c = false on the Wealth Application Config custom setting for the ETL integration user before any bulk DML begins. For Core FSC orgs, confirm the equivalent DPE recalculation job is identified and ready to run post-load.
3. Load objects in strict dependency order — Execute bulk loads in this sequence: Account/PersonAccount → FinancialSecurity → FinancialAccount → FinancialAccountRole (Primary Owner first) → FinancialHolding → FinancialAccountTransaction. Use Bulk API 2.0 with UPSERT on an external ID field where possible to support re-runnable loads.
4. Handle balance history per deployment model — For managed-package orgs, write the current balance to FinServ__Balance__c during the FinancialAccount load. For Core FSC orgs, load FinancialAccountBalance child records after FinancialAccount, one row per historical snapshot in ascending date order.
5. Post-load: run rollup recalculation — Re-enable RBL for the ETL user, then run FinServ.RollupRecalculationBatchable (managed package) or the configured DPE job (Core FSC) to rebuild all aggregated balances. Do not skip this step; FinancialAccount and household totals will be zero or stale until recalculation completes.
6. Validate and reconcile — Query total record counts per object and compare to source. Spot-check holding balances and transaction counts for a sample of accounts. Verify that household-level rollups reflect correct totals after the recalculation batch completes.

Review Checklist

Run through these before marking work in this area complete:

• RBL was disabled for the ETL user before any FinancialHolding or FinancialAccountTransaction DML
• FinancialSecurity records were loaded before FinancialHolding
• FinancialAccountRole (Primary Owner) was loaded before FinancialHolding
• Balance history strategy matches the deployment model (snapshot rows for Core FSC, single field for managed package)
• RollupRecalculationBatchable or DPE recalculation job ran to completion post-load
• Record counts reconcile between source and target for all six object layers
• Household-level balance rollups are non-zero and match expected totals

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. RBL triggers fire on every single DML row — The FSC Rollup-by-Lookup implementation uses synchronous Apex triggers, not platform roll-up summary fields. At bulk volumes, multiple load threads updating holdings under the same FinancialAccount compete for a row lock on that parent record, producing UNABLE_TO_LOCK_ROW exceptions. Disabling the setting does not remove the trigger; it adds a guard condition checked at runtime.
2. FinancialSecurity is a silent prerequisite — The FinancialHolding object has a required lookup (FinancialSecurityId) that is easy to overlook in data mapping. If FinancialSecurity records do not already exist in the target org, every FinancialHolding row will fail with a foreign-key error. Source systems often call these "instruments" or "securities" in a separate catalog table.
3. Core FSC balance history is a child object, not a field — Practitioners familiar with the managed package assume they can write Balance__c on FinancialAccount and be done. In Core FSC orgs, the FinancialAccountBalance child object is the canonical store for balance data. Writing only to a top-level field (if one exists) does not populate history and advisor analytics will show empty trend charts.

Output Artifacts

Related Skills

• admin/financial-account-setup — configure FSC financial account types, roles, and household rollup behavior (use before migration to confirm target configuration is correct)
• admin/fsc-data-model — FSC object model reference; use to identify correct API names and relationship fields before building data mapping