Fsc Deployment Patterns

FSC Deployment Patterns

Use this skill when planning or executing metadata deployments for Financial Services Cloud. FSC has strict, irreversible prerequisite steps — particularly around Person Account enablement and Compliant Data Sharing activation — that must be completed in the correct sequence before dependent metadata can land. It also covers the critical namespace incompatibility between managed-package FSC orgs (FinServ__ prefix) and platform-native Core FSC orgs (Winter '23+), which causes metadata artifacts to be non-portable between the two models.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the FSC licensing model in use. Managed-package FSC orgs use the FinServ__ namespace prefix on all FSC objects and fields. Platform-native Core FSC orgs (introduced Winter '23) have no namespace — FSC objects are standard platform objects. Metadata artifacts are incompatible between these two models; a deployment package built for one cannot be applied to the other without an API name audit and rewrite.
• Confirm Person Account status in the target org. Person Account enablement is an irreversible org-level change that cannot be performed via Metadata API. It must be enabled manually through Setup before any household record types, Relationship Groups, or Financial Account metadata can be deployed. If Person Accounts are not enabled, the deployment will fail with a reference error on household record types.
• Check OWD settings for Account, Opportunity, and Financial Deal. Compliant Data Sharing share-table entries are only meaningful when the target objects have Org-Wide Defaults (OWDs) set to Private or Public Read-Only. If OWDs are Public Read/Write, CDS share-table rows are written but have no access-control effect. OWDs must be set before deploying CDS-enabling metadata.
• Know your deployment tool's behavior with IndustriesSettings. The IndustriesSettings Metadata API type controls feature flags for CDS and other FSC capabilities. Deploying IndustriesSettings does not always trigger immediate share-table recalculation — some flags require a post-deploy activation step or sharing recalculation job.

Core Concepts

Irreversible Prerequisite: Person Account Enablement

Person Account enablement is the foundational gate for FSC. Salesforce documentation explicitly states this change is irreversible and cannot be performed via Metadata API. It requires a Salesforce support case or a Setup toggle (depending on org type). Once enabled:

• The Account object gains an IsPersonAccount field.
• Household record types and Relationship Group metadata become deployable.
• The Individual object interaction model changes.

Impact for deployments: If a CI pipeline attempts to deploy household-related record types or page layouts to an org where Person Accounts are not yet enabled, the deployment fails with an entity reference error. The fix is never a code change — it is an org configuration step that must precede the first metadata deploy wave.

Sequential Dependency: Record Types Before Participant Role Custom Metadata

FSC's Compliant Data Sharing model uses Participant Role custom metadata records to define which roles grant share-table access. These records reference Financial Account Role values, which are themselves tied to Account record types. The deployment sequence is therefore:

1. Person Accounts enabled (manual, Setup)
2. Account record types deployed (RecordType metadata)
3. CDS-target objects enabled (OWDs set to Private or Public Read-Only)
4. IndustriesSettings metadata deployed to activate CDS flags
5. Participant Role custom metadata records deployed

Deploying Participant Role custom metadata before the Account record types exist results in a reference error because the custom metadata references record type developer names that do not yet exist in the target org.

Namespace Model: Managed Package vs Platform-Native Core FSC

FSC historically shipped as a managed package with the FinServ__ namespace. Every FSC object, field, and custom metadata type carried this prefix:

• FinServ__FinancialAccount__c
• FinServ__Financial_Account__c.FinServ__Balance__c
• FinServ__ParticipantRole__mdt

Starting with Winter '23, Salesforce introduced platform-native Core FSC, where FSC objects are standard platform objects with no namespace:

• FinancialAccount
• FinancialAccount.Balance
• ParticipantRole (custom metadata without FinServ__ prefix)

A metadata deployment package built for a managed-package org contains FinServ__-prefixed API names throughout. Deploying this package to a platform-native Core FSC org will fail because those namespace-qualified names do not match any metadata in the target. The reverse is equally true. There is no automated conversion — every API name in the package must be audited and rewritten for the target model.

Compliant Data Sharing Activation and OWD Dependency

CDS provides row-level sharing for regulated financial data. The share-table mechanism is controlled by three linked settings:

1. The IndustriesSettings metadata type enables CDS feature flags at the org level.
2. OWDs for Account, Opportunity, and Financial Deal must be Private or Public Read-Only for share-table entries to control access.
3. After CDS is activated, a sharing recalculation job must run to populate share-table rows for existing records.

Deploying IndustriesSettings to activate CDS on an org with Public Read/Write OWDs results in a state where CDS appears enabled but provides no access control — share-table entries exist but are irrelevant because the base OWD already grants access to everyone. This is a silent misconfiguration that will not surface as a deployment error.

Common Patterns

Phased Prerequisite-First Deployment Pattern

When to use: Initial FSC deployment to a new sandbox or production org where FSC has never been configured.

How it works:

Phase 0 — Org prerequisites (manual, cannot be scripted):

1. Enable Person Accounts via Setup or Salesforce support case.
2. Set OWDs for Account, Opportunity, and Financial Deal to Private (or Public Read-Only if full private is not required).
3. Confirm FSC managed package is installed (managed-package model) or Core FSC is provisioned (platform-native model).

Phase 1 — Deploy structural metadata:

sf project deploy start --metadata "RecordType:Account.Household,RecordType:Account.Person_Account" --target-org <alias>

Phase 2 — Deploy Industries settings:

sf project deploy start --metadata "IndustriesSettings" --target-org <alias>

Phase 3 — Deploy Participant Role custom metadata:

sf project deploy start --metadata "ParticipantRole" --target-org <alias>

Phase 4 — Trigger sharing recalculation (manual or via Apex):

// Trigger CDS share recalculation for Financial Accounts
Database.executeBatch(new FinancialAccountShareRecalcBatch(), 200);

Why not a single deploy wave: Because Phase 0 requires manual org changes that block all subsequent metadata, and because Participant Role custom metadata references record types that must already exist in the target.

Namespace Audit and Rewrite Pattern

When to use: Migrating metadata between a managed-package FSC org and a platform-native Core FSC org (or vice versa), or when promoting a pipeline built for one model to an org running the other.

How it works:

1. Export the full metadata package from the source org.
2. Run a namespace audit script to catalog all API names containing FinServ__ (for managed-package to platform-native migration) or to identify bare API names that need the prefix added (for the reverse).
3. Perform a bulk find-and-replace on the metadata XML, updating all API names, field references, and custom metadata type references.
4. Validate the rewritten package against the target org's object model using sf project deploy validate --dry-run.
5. Deploy the validated, rewritten package.

Why not skip the audit: The namespace mismatch is invisible at the tool level — sf project deploy start does not warn you that a metadata API name does not match the target org's model. It simply fails with a generic component-not-found error that can be misdiagnosed as a missing dependency rather than a namespace mismatch.

CDS Post-Deploy Validation Pattern

When to use: After deploying IndustriesSettings to activate CDS in a target org.

How it works:

1. Confirm OWDs are set correctly: Setup > Sharing Settings > check Account, Opportunity, Financial Deal.
2. Create a test Financial Account record and confirm a share-table row is written: SELECT Id, UserOrGroupId, AccessLevel FROM FinancialAccountShare WHERE ParentId = '<test_id>'.
3. Assign a Participant Role to the test record and confirm the share-table row updates.
4. Log in as a test user who should gain access via CDS and confirm they can see the record.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner deploying FSC metadata:

1. Identify the FSC licensing model in the source and target orgs. Check whether objects use the FinServ__ namespace (managed-package) or bare names (platform-native Core FSC). If they differ, run the namespace audit and rewrite before any other step.
2. Confirm Person Accounts are enabled in the target org. Query SELECT Id, Name FROM AccountRecordType WHERE DeveloperName = 'PersonAccount' or check Setup > Person Accounts. If not enabled, stop and enable them via Setup before proceeding. This cannot be automated and is irreversible.
3. Verify OWD settings for Account, Opportunity, and Financial Deal. Navigate to Setup > Sharing Settings and confirm each object is set to Private or Public Read-Only. If OWDs are Public Read/Write, update them before deploying CDS configuration.
4. Deploy structural metadata in sequence: first Account record types, then other FSC object record types. Validate each wave before proceeding: sf project deploy validate --metadata "RecordType" --target-org <alias>.
5. Deploy IndustriesSettings to activate CDS and other FSC feature flags: sf project deploy start --metadata "IndustriesSettings" --target-org <alias>. Confirm the deploy succeeds without errors.
6. Deploy Participant Role custom metadata after record types are confirmed in the target: sf project deploy start --metadata "ParticipantRole" --target-org <alias>.
7. Run CDS post-deploy validation: confirm OWDs, trigger sharing recalculation if needed, and verify share-table rows are populated for test records. Log in as a test user to confirm row-level access is functioning correctly.

Review Checklist

Run through these before marking FSC deployment work complete:

• Confirmed FSC licensing model (managed-package vs platform-native) is the same in source and target orgs, or namespace audit and rewrite has been completed
• Person Accounts are enabled in the target org before any household or Financial Account metadata was deployed
• OWDs for Account, Opportunity, and Financial Deal are set to Private or Public Read-Only before CDS metadata was deployed
• Account record types were deployed and confirmed present before Participant Role custom metadata was deployed
• IndustriesSettings deploy succeeded without errors
• Post-deploy sharing recalculation job was triggered and completed
• Share-table rows verified for at least one test Financial Account record
• Test user login confirmed row-level access is functioning via CDS

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Person Account enablement is irreversible and blocks household metadata — Attempting to deploy household Account record types or Relationship Group metadata before Person Accounts are enabled fails with a generic entity reference error. The root cause is not obvious from the error message. Enable Person Accounts in Setup before the first metadata deploy wave — and understand this change cannot be undone in the org.
2. OWD mismatch silently breaks CDS without a deployment error — Deploying IndustriesSettings to activate CDS on an org with Public Read/Write OWDs for Account succeeds with no errors. CDS appears active. But share-table entries have no access-control effect because the base OWD already grants everyone full access. This misconfiguration does not surface until a security audit or a pen-test reveals the data exposure.
3. FinServ__ namespace renders metadata non-portable between FSC models — A package.xml built from a managed-package FSC org will reference FinServ__FinancialAccount__c. Deploying this to a platform-native Core FSC org fails because that object does not exist under that name. The sf CLI error message ("Component not found") does not mention namespace as the cause, leading practitioners to incorrectly diagnose the issue as a missing dependency or wrong API version.
4. IndustriesSettings does not backfill share-table rows for existing records — After deploying CDS activation via IndustriesSettings, share-table rows are created for new records going forward but are not retroactively created for records that existed before CDS was activated. A sharing recalculation batch job must be explicitly triggered to populate shares for existing records. Skipping this step leaves pre-existing financial accounts invisible to users who should have access via CDS.
5. Participant Role custom metadata silently deploys with wrong record type references — If Account record types referenced in Participant Role custom metadata records do not match the exact developer names in the target org (e.g., due to a record type rename during migration), the custom metadata deploys successfully but the CDS engine ignores those participant roles at runtime. There is no deploy-time validation of custom metadata field cross-references.

Output Artifacts

Related Skills

• fsc-architecture-patterns — for FSC architectural decisions before deployment begins, including CDS design and household model choices
• fsc-data-model — for understanding FSC object relationships, Financial Account roll-up logic, and Relationship Groups that affect what must be deployed
• metadata-api-coverage-gaps — for understanding which FSC metadata types are not supported by the Metadata API and require manual configuration
• permission-set-deployment-ordering — for ordering permission set deployments that grant access to FSC objects and CDS-protected records
• post-deployment-validation — for the general post-deploy validation framework; FSC adds CDS-specific validation steps documented in this skill
• health-cloud-deployment-patterns — parallel skill for Health Cloud (similar Industries Cloud deployment sequencing patterns)