SfSkills Domains Docs GitHub

Home / apex / fsc-apex-extensions

fsc-apex-extensions

Use this skill when extending Financial Services Cloud (FSC) behavior through Apex: customizing financial rollup recalculation, disabling built-in FSC triggers to write custom trigger logic, implementing Compliant Data Sharing (CDS) participant/role integrations, or building custom FSC action handlers. NOT for standard Apex unrelated to the FSC managed package, standard Salesforce sharing rules, or configuring FSC rollups through the Admin UI — use the admin/financial-account-setup skill for declarative rollup setup.

Open the skill folder on GitHub

FSC Apex Extensions

Use this skill when you need to write Apex that extends or integrates with Financial Services Cloud managed-package behavior: custom triggers that coexist with FSC's built-in trigger framework, post-bulk-load rollup recalculation invocations, or Compliant Data Sharing integrations that must use the CDS participant/role model rather than standard Apex sharing.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

FSC Trigger Management via FinServ__TriggerSettings__c

FSC ships with its own Apex trigger framework. Every FSC-owned trigger checks the FinServ__TriggerSettings__c hierarchy custom setting before executing. If your custom trigger and the FSC trigger both fire on the same object/event, both execute — which causes duplicate processing (e.g., double rollup increments, double notification events).

The correct pattern is to disable the specific FSC trigger for the duration of your custom logic. To disable Account-level FSC triggers:

FinServ__TriggerSettings__c ts = FinServ__TriggerSettings__c.getInstance();
ts.FinServ__AccountTrigger__c = false;
upsert ts;
// ... your DML
ts.FinServ__AccountTrigger__c = true;
upsert ts;

This pattern must be wrapped in a try/finally block to prevent the setting remaining false if an exception occurs. Because the custom setting is org-wide hierarchy type, test classes must also set it up explicitly — do not rely on default values in tests.

Rollup Recalculation is Not Event-Driven at Bulk Scale

FSC financial rollups aggregate values across household members, joint owners, and group relationships. The rollup engine is designed to fire from transactional DML inside Apex triggers. At bulk scale — Data Loader, Bulk API, or any batch that bypasses the standard trigger invocation threshold — FSC rollups do not self-correct. After any bulk insert or update of FinServ__FinancialAccount__c, FinServ__FinancialAccountTransaction__c, or related objects, you must invoke:

Database.executeBatch(new FinServ.RollupRecalculationBatchable(), 200);

This batchable recalculates all pending rollup summaries. The batch size of 200 is the Salesforce-recommended value for avoiding CPU limit violations on complex household graphs. Scheduling this batch immediately after any bulk load is a production requirement, not an optional optimization.

Compliant Data Sharing Cannot Be Overridden with Standard Apex Sharing

When FSC Compliant Data Sharing (CDS) is enabled on an object, the CDS engine owns the share records. Any AccountShare, FinancialAccountShare, or related share object records you insert manually in Apex — including those inserted by standard Apex managed sharing — will be silently removed the next time the CDS recalculation job runs.

To share a record under CDS, you must insert a FinServ__ShareParticipant__c record (or the equivalent native object) that registers the participant relationship. CDS then generates the share records automatically based on the participant's assigned sharing role. The RowCause on CDS-generated shares is CompliantDataSharing — do not attempt to create records with this RowCause manually; the system sets it.

Managed Package API Version Lock

The FSC managed package compiles its Apex at the API version current at the time of the package's release. When the org's Apex version moves ahead of the package's compiled version, type resolution for platform-provided types (custom metadata types, new sObject subtypes, newer Apex system classes) can diverge. The practical impact: if your custom Apex calls FSC managed package classes and passes newly introduced types, you may receive runtime TypeException or method-not-found errors that do not appear in sandbox at the same version. Always test FSC Apex extensions in a full-copy sandbox that mirrors the production FSC package version before deploying.

Common Patterns

Pattern: Safe Trigger Co-Existence with FSC Built-Ins

When to use: You need to add custom business logic to the same object event already handled by an FSC trigger (e.g., before-update on FinServ__FinancialAccount__c).

How it works:

  1. Create a custom trigger that fires on the target object/event.
  2. At the start of the trigger handler, read FinServ__TriggerSettings__c and selectively disable the relevant FSC trigger flag.
  3. Execute your logic.
  4. In a finally block, re-enable the FSC trigger flag.
  5. Allow FSC rollup recalculation to run post-transaction (it will fire naturally for transactional DML, or batch for bulk DML).

Why not the alternative: Simply adding a trigger without disabling the FSC built-in causes both triggers to run for the same records. On Financial Account updates, this results in double rollup increments, which produces incorrect household balance totals that are difficult to detect without dedicated rollup validation tests.

Pattern: Post-Bulk-Load Rollup Reset

When to use: A migration, integration, or scheduled batch performs large-volume DML on FSC financial objects outside the normal transactional trigger path.

How it works:

  1. Complete the bulk DML (Data Loader, Bulk API, or custom batch).
  2. In a separate Apex job (Queueable or scheduled Batch), invoke Database.executeBatch(new FinServ.RollupRecalculationBatchable(), 200).
  3. Optionally chain a validation query to spot-check household totals post-recalculation.

Why not the alternative: Relying on the scheduled nightly rollup batch leaves household totals stale for hours. Financial advisors querying household net worth immediately after a migration will see incorrect values, which in regulated environments constitutes a compliance risk.

Decision Guidance

SituationRecommended ApproachReason
Custom logic on the same object/event as an FSC triggerDisable FSC trigger via FinServ__TriggerSettings__c, run custom logic, re-enable in finallyPrevents double processing without removing FSC trigger permanently
Sharing a Financial Account with a new participantInsert FinServ__ShareParticipant__c record via CDS modelDirect share record inserts are silently reverted by CDS recalculation
Bulk data load of FinancialAccount or related objectsInvoke FinServ.RollupRecalculationBatchable after loadFSC rollups do not auto-fire reliably at bulk scale
Calling FSC managed Apex from org Apex at newer API versionTest in full-copy sandbox; avoid passing newer platform types to managed methodsManaged package is locked to an older API version; type mismatches cause runtime errors
Rollup recalculation taking too long post-loadReduce batch size below 200, or use FSC Admin UI batch trigger for selective recalculationComplex household graphs approach CPU limits at 200 batch size in some orgs

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

  1. Assess trigger landscape — Query FinServ__TriggerSettings__c and list which FSC trigger flags are currently enabled. Cross-reference with the objects your custom Apex will touch to identify all overlap points.
  2. Draft trigger handler with FSC trigger guard — Write the custom Apex trigger handler. Add a try/finally block that disables the relevant FinServ__TriggerSettings__c flags before DML and re-enables them in the finally clause. Never leave FSC triggers permanently disabled.
  3. Add rollup recalculation hook — If the trigger handles bulk DML paths (context isBulk or batch size > 50), enqueue a FinServ.RollupRecalculationBatchable call after DML rather than relying on transactional rollup firing.
  4. Handle CDS participation — If the feature requires sharing records with non-owner users, insert FinServ__ShareParticipant__c records using the correct FinServ__ShareRole__c value. Never insert share records directly on CDS-governed objects.
  5. Write test classes with FSC setting setup — Test classes must explicitly configure FinServ__TriggerSettings__c for the running user context. Do not assume org defaults persist in test execution. Use @TestSetup to initialize the custom setting.
  6. Validate in full-copy sandbox — Deploy to a sandbox whose FSC package version matches production. Run the check_fsc_apex_extensions.py script against the deployed metadata to check for common misconfigurations.
  7. Confirm rollup totals post-deployment — After go-live of any bulk-load-adjacent feature, manually verify household total fields on a sample of affected accounts to confirm rollup recalculation completed correctly.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. FSC Rollups Silent on Bulk Insert — FSC rollup recalculation does not fire reliably when records are inserted via Bulk API or Data Loader at batch sizes beyond what triggers can handle. Household totals remain stale until FinServ.RollupRecalculationBatchable is run. The failure is silent — no error is thrown, rollup fields simply do not update.
  2. CDS Silently Reverts Manual Share Records — Any share record (AccountShare, FinancialAccountShare) inserted manually through Apex on a CDS-governed object will be deleted the next time the CDS recalculation job runs. There is no error; the record simply disappears. The only durable sharing mechanism is the FinServ__ShareParticipant__c participant model.
  3. Managed Package API Version Lock Causes Runtime TypeException — The FSC managed package Apex compiles against the API version active at the time of that package version's release. If org Apex at a newer API version passes a type introduced after that API version to a managed package method, a System.TypeException is thrown at runtime that does not surface during compilation or deploy-time validation.

Output Artifacts

ArtifactDescription
FSC-safe Apex triggerCustom trigger handler with FinServ__TriggerSettings__c guard pattern
Rollup recalculation invocationApex code to explicitly invoke FinServ.RollupRecalculationBatchable after bulk loads
CDS participant insertion snippetApex code to register sharing via FinServ__ShareParticipant__c

Package files