fsc-referral-management

# FSC Referral Management

Use this skill when configuring FSC Referral Management: defining referral types via `ReferralRecordTypeMapping__mdt` custom metadata, routing referrals through Lead Assignment Rules keyed on the `Expressed Interest` picklist, understanding Referrer Score behavior, and enabling partner referral visibility in Experience Cloud. It activates whenever a practitioner needs to wire together the Lead-based referral data model, the custom metadata registry, the picklist-driven routing logic, and downstream queues or partner portals.

---

## Before Starting

Gather this context before working on anything in this domain:

- Confirm the org has Financial Services Cloud provisioned and Referral Management is enabled in FSC Settings (Setup > Financial Services Cloud Settings > Referral Management toggle).
- Identify all referral types the business requires. Each must map to both a Lead record type and a `ReferralRecordTypeMapping__mdt` entry — both are required for routing to function.
- Confirm whether external partners submit referrals via an Experience Cloud site. If so, Referrer Score visibility requires explicit layout or component configuration that is off by default.
- The most common wrong assumption: adding a new queue is sufficient for routing. It is not. The queue must be referenced in an active `ReferralRecordTypeMapping__mdt` entry or routing silently ignores it with no error.
- Do not treat Einstein Referral Scoring as an active feature to configure. It was announced for retirement; Intelligent Need-Based Referrals is the supported scoring capability.

---

## Core Concepts

### The Extended Lead Object

FSC Referral Management does not introduce a separate object. It extends the standard Lead object with 11 custom fields that carry referral-specific data:

- `ExpressedInterest__c` — picklist; the primary routing key for Lead Assignment Rules
- `ReferredBy__c` — lookup to User (internal referrer) or Contact (external partner referrer)
- `ReferrerScore__c` — integer 0–100 reflecting the referrer's historical conversion rate
- `ReferralType__c` — controlled by the record type selected at creation
- `ReferralDate__c`, `ReferralStatus__c`, `ReferralChannel__c`, and four additional contextual fields

Because referrals are Leads, all standard Lead capabilities apply without modification: duplicate rules, validation rules, workflow, Flow, reports, and list views all work as expected. However, referral-specific field visibility and page layouts must be managed per record type, and the referral features are only active when Referral Management is enabled in FSC Settings.

### ReferralRecordTypeMapping Custom Metadata

`ReferralRecordTypeMapping__mdt` is the authoritative registry that tells FSC which Lead record types are valid referral types. Every referral category the business uses must have an active entry. Each metadata record binds together the Lead record type developer name, a display label, and a target queue or owner. The platform reads this metadata at referral creation time to:

1. Confirm the record type is a valid referral type
2. Apply default routing prior to evaluating Assignment Rules
3. Expose the referral type in the FSC referral UI

**Critical behavior:** if a Lead record type is used in a referral but has no active `ReferralRecordTypeMapping__mdt` entry, the platform creates the Lead record silently and performs no assignment — no error, no notification. The referral appears successfully created while routing has completely failed. This is the most common silent production failure in FSC referral configurations.

### Lead Assignment Rule Routing via Expressed Interest

Once a referral type is registered in the metadata, fine-grained routing is controlled by standard Lead Assignment Rules. The `Expressed Interest` picklist is the primary routing key: each Assignment Rule entry filters on one or more picklist values (e.g. "Retirement Planning", "Home Loan", "Auto Loan") and directs the Lead to the appropriate queue or user.

Design implications:
- Routing changes do not require a metadata deployment — only Assignment Rule record updates
- All standard Lead Assignment Rule criteria are available (field values, formula criteria)
- A referral with an `Expressed Interest` value that matches no active rule entry lands in the default Lead owner or remains unassigned
- The Assignment Rule must be active and set as the default rule; having a rule that is not the active default has no effect

### Referrer Score

Referrer Score (`ReferrerScore__c`) is a platform-calculated integer 0–100 representing a referrer's historical conversion rate — how often their submitted referrals result in closed deals. It is read-only from an admin perspective; the platform updates it based on closed referral history.

Key behaviors by referrer type:
- **Internal referrers (employees/advisors):** `ReferredBy__c` is a User lookup; score is visible in standard Lead views without additional configuration
- **External partner referrers:** `ReferredBy__c` points to a Contact record (not User). This is by design — FSC credits the partner's Contact, not a User. `ReferrerScore__c` is not included in default Experience Cloud page layouts and must be explicitly added to the community page layout or a custom LWC

Referrer Score is part of FSC's Intelligent Need-Based Referrals feature, which is the active and supported capability. Do not conflate this with Einstein Referral Scoring, which was a separately-licensed, separately-configured feature that has been announced for retirement.

---

## Common Patterns

### Pattern: Registering a New Referral Type End-to-End

**When to use:** A new business line (e.g. Small Business Lending) needs to accept referrals through FSC Referral Management for the first time.

**How it works:**
1. Create or confirm a Lead record type named (e.g.) `SmallBusinessLending` with appropriate page layout.
2. Add the required picklist values to `Lead.ExpressedInterest__c` that will drive routing for this business line (e.g. "SBA Loan", "Business Line of Credit").
3. Create a `ReferralRecordTypeMapping__mdt` record: set the Lead record type developer name, label, and the target queue.
4. Create Lead Assignment Rule entries filtering on the new `Expressed Interest` values, routing to the Small Business Lending queue.
5. Deploy the custom metadata and picklist values together. Assignment Rule updates can follow in production.
6. Test by creating a referral with each new `Expressed Interest` value and confirming queue assignment via the Lead Assignment Log on the record.

**Why not the alternative:** Skipping the `ReferralRecordTypeMapping__mdt` entry (step 3) causes routing to silently fail. The referral is created and no error surfaces, but no queue assignment occurs. There is no indicator on the record that routing was skipped.

### Pattern: Enabling Partner Referrer Score Visibility in Experience Cloud

**When to use:** External partners or financial advisors submit referrals through an Experience Cloud site and need to see their own Referrer Score.

**How it works:**
1. Confirm that partner referral records use a Contact-based `ReferredBy__c` lookup. This is platform-default for partner referrals; do not change it.
2. In Experience Builder, navigate to the Lead or Referral detail page used by partner users.
3. Add `ReferrerScore__c` to the visible fields on the page layout or the custom component. If using an aura/LWC component, add the field to the component's field list explicitly.
4. Set field-level security: grant Read access to `ReferrerScore__c` for the Experience Cloud community profile (not just the internal admin profile).
5. Test by logging in as a partner community user and verifying the score is visible on their submitted referral records.

**Why not the alternative:** Granting FLS access alone is not sufficient if the field is absent from the page layout or component — the field will not render. Both FLS and layout placement are required.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| New referral type needed for a new business line | Create Lead record type + ReferralRecordTypeMapping__mdt entry + Assignment Rule entries | All three are required; missing either the metadata entry or the assignment rule causes silent failure or unassigned referrals |
| Partner referral Referrer Score not visible in community | Add ReferrerScore__c to Experience Builder page layout and set FLS Read for community profile | Score is on a Contact-linked record; FLS and layout placement are both required |
| Routing logic needs to change without a deployment | Update Lead Assignment Rule criteria only — no metadata deployment needed | Assignment Rules are non-metadata config; ReferralRecordTypeMapping entries still require deployment |
| Einstein Referral Scoring is requested | Redirect to Intelligent Need-Based Referrals; document that Einstein Referral Scoring is retiring | Einstein Referral Scoring is a retiring/retired feature; do not configure or reference as current capability |
| Referral created but assigned to no queue | Check ReferralRecordTypeMapping__mdt for an active entry matching the record type; then check Assignment Rules for matching Expressed Interest values | Silent routing failure is almost always caused by a missing metadata record or an unmatched picklist value |
| Referral routing behaves inconsistently by picklist value | Audit Expressed Interest picklist values against Assignment Rule criteria for exact string match | Assignment Rules use exact picklist value match; any label mismatch causes the rule to not fire |

---

## Recommended Workflow

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

1. **Confirm feature enablement** — Verify FSC is provisioned and Referral Management is enabled in Setup > Financial Services Cloud Settings. Confirm the expected Lead record types for each referral category exist in the org with appropriate page layouts.
2. **Audit ReferralRecordTypeMapping__mdt** — Inspect all `ReferralRecordTypeMapping__mdt` records. Confirm every referral type the business requires has an active entry with the correct Lead record type developer name and a valid target queue or user. Flag any Lead record type used for referrals that is missing an entry.
3. **Audit Expressed Interest picklist values** — Confirm all routing-relevant picklist values exist on `Lead.Expressed Interest`. Any value used as an Assignment Rule filter criterion must exist in the picklist metadata or the rule will never match.
4. **Audit Lead Assignment Rules** — For each active referral type, confirm at least one Assignment Rule entry filters on `Expressed Interest` and routes to the correct queue or owner. Identify gaps and unmatched values.
5. **Verify Referrer Score access** — If partner referrals are in scope, confirm `ReferrerScore__c` is on the Experience Builder page layout for the community referral detail page and that FLS grants Read access to the community profile.
6. **Test routing end-to-end** — Create a test referral for each referral type and `Expressed Interest` combination. Confirm Lead record type, queue assignment, and Referrer Score visibility are all correct. Use the Lead Assignment Log on each record to diagnose any misroutes.
7. **Deploy and document** — Deploy `ReferralRecordTypeMapping__mdt` changes and picklist metadata via change set or source-based deployment. Document the referral type registry, routing matrix, and any Experience Cloud layout changes in the project runbook.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] Every active referral type has a corresponding active ReferralRecordTypeMapping__mdt entry
- [ ] Every Expressed Interest picklist value used in Assignment Rule routing exists in Lead field metadata
- [ ] Lead Assignment Rules cover all active referral types with no routing gaps or unmatched values
- [ ] ReferrerScore__c is visible on Experience Cloud pages if partner referrals are in scope (layout + FLS)
- [ ] Einstein Referral Scoring is NOT referenced in any new configuration, documentation, or automation
- [ ] Test referrals for each referral type result in correct queue assignment (verified via Lead Assignment Log)
- [ ] Field-level security for all 11 referral custom fields is correctly set for all relevant internal and community profiles

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Missing ReferralRecordTypeMapping silently drops routing** — A Lead record type used for referrals with no active `ReferralRecordTypeMapping__mdt` entry causes the platform to create the referral but skip all queue assignment with no error or warning surfaced anywhere on the record or in logs.
2. **Einstein Referral Scoring is retiring** — Einstein Referral Scoring for FSC was a separately-licensed feature announced for retirement. It must not be configured as a new capability or documented as a current feature. Intelligent Need-Based Referrals is the supported path.
3. **Partner referrals credit Contact, not User** — When a partner submits a referral through Experience Cloud, `ReferredBy__c` points to the partner's Contact record, not a User. Referrer Score is attributed to that Contact. Assuming all referrers are Users breaks lookups and score attribution for external partner scenarios.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| ReferralRecordTypeMapping__mdt records | Deployed custom metadata entries registering each referral type and its target queue |
| Lead Assignment Rule configuration | Routing rules keyed on Expressed Interest picklist values directing referrals to the correct queues or users |
| Experience Builder page layout update | Updated community referral detail page surfacing ReferrerScore__c for partner users |
| Referral routing test log | End-to-end test records confirming correct assignment per referral type and Expressed Interest value |

---

## Related Skills

- admin/financial-account-setup — When closed referrals result in new FSC financial accounts, this skill governs account setup
- admin/experience-cloud-setup — For configuring the Experience Cloud site used by partner referrers submitting and tracking referrals