Imported from PranavNagrecha/AwesomeSalesforceSkills (skills/admin/referral-management-health/SKILL.md). Install upstream with npx skills add PranavNagrecha/AwesomeSalesforceSkills --skill referral-management-health. Copyright stays with the author.

Referral Management — Health Cloud

Use this skill when configuring Health Cloud referral management: defining referral types, setting up the ClinicalServiceRequest-based workflow, enabling provider search, and managing provider network relationships. This skill covers the clinical referral lifecycle from initiation through completion. It does NOT cover FSC Einstein Referral Scoring (a Financial Services Cloud feature for advisor-client referrals), the Public Sector Solutions Referral sObject, or generic Sales Cloud lead referral tracking.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the org has Health Cloud enabled and the HealthCloudGA managed package installed. Referral management requires specific Health Cloud permission set licenses beyond base Salesforce access.
• Identify whether the org uses Health Cloud's native referral workflow (ClinicalServiceRequest) or a custom object-based approach. The native approach is the only one with long-term Salesforce investment.
• Confirm the Data Pipelines Base User permission set license is provisioned for all users who need to run provider search. Without this license, the Data Processing Engine (DPE) job that populates CareProviderSearchableField will fail silently or throw a license error, making provider search return zero results.
• Distinguish inbound referrals (from external providers to your organization) from outbound referrals (from your clinicians to external specialists). They share the ClinicalServiceRequest object but differ in direction field values and workflow steps.

Core Concepts

ClinicalServiceRequest as the Referral Record

Health Cloud referral management uses the ClinicalServiceRequest object (API v51.0+) as the core referral record. This is a standard Salesforce object — not a managed-package custom object — which means it is available via standard SOQL, reports, and list views once Health Cloud is enabled. Key fields include:

• PatientId — lookup to the patient Account record
• ReferralDate — date referral was initiated
• ReferralType — picklist distinguishing inbound vs. outbound vs. internal
• Status — tracks the referral lifecycle (Draft → Submitted → Accepted → Completed/Cancelled)
• ReferredToId — lookup to the receiving provider (Account or Contact)
• AuthorizationNumber — for payer-authorized referrals requiring prior authorization

The ClinicalServiceRequest object requires the HealthCloudICM permission set to be assigned to users who create or update referral records.

Provider Search and CareProviderSearchableField

Provider search is powered by a denormalized index object: CareProviderSearchableField. This object is NOT populated automatically. It requires a Data Processing Engine (DPE) job to run, which reads the Provider Relationship Management data model and writes denormalized, search-optimized records to CareProviderSearchableField.

The most common implementation blocker: the user running the DPE job (or the automated process credential) must have the Data Pipelines Base User permission set license assigned. Without this license, the DPE job either fails to run or silently produces no output. Provider search then returns zero results even when provider records exist.

The DPE job reads objects, not record types. HealthcareProvider is a standard Health Cloud object — "Represents business-level details about the healthcare organization or the practitioner" — alongside HealthcarePractitionerFacility and the rest of the Provider Relationship Management model; Account represents a healthcare facility or location and Contact represents physicians and other licensed practitioners. There is no HealthcareProvider record type on Account and no HealthcarePractitioner record type on Contact. If provider data has been loaded onto Accounts and Contacts alone without the corresponding PRM object records, the DPE job has nothing to denormalize and provider search returns zero results — which looks identical to the permission-set-license failure above, so check both.

Referral Status Workflow

Health Cloud referral management uses a status-driven workflow on ClinicalServiceRequest. The standard status picklist values are: Draft, Submitted, In Review, Accepted, Declined, Completed, Cancelled. Admins can add custom picklist values but must also update any validation rules or Flow automation that checks for specific status values.

A common pattern is to use Flow to automate status transitions — for example, automatically updating a referral to "Accepted" when the receiving provider logs a response, or "Completed" when a clinical encounter (ClinicalEncounter) is created that references the referral.

Common Patterns

Outbound Referral to Specialist

When to use: A clinician needs to refer a patient to an external specialist and track the referral through acceptance and completion.

How it works:

1. Clinician creates a ClinicalServiceRequest record with ReferralType = Outbound, sets PatientId, ReferredToId (specialist), and ReferralDate.
2. Flow automation fires on record creation to notify the receiving provider (email or Experience Cloud notification).
3. Receiving provider updates status to Accepted via a portal or manual update.
4. When the specialist visit is completed, a ClinicalEncounter record is created referencing the ClinicalServiceRequest. An Apex trigger or Flow updates status to Completed.
5. Care coordinator reviews completed referral and closes care coordination tasks.

Why not the alternative: Using a custom object or Lead-based workflow loses the native provider network integration, FHIR R4 mapping, and reporting on the standard Health Cloud referral dashboard.

Provider Network Search Before Referral

When to use: Care coordinator needs to find in-network specialists before creating a referral.

How it works:

1. Run the DPE job to populate CareProviderSearchableField on a schedule (daily or on-demand after provider record changes).
2. Use the Health Cloud Provider Search Lightning component (or build a custom LWC querying CareProviderSearchableField) to filter by specialty, location, and in-network status.
3. Selected provider's Account/Contact ID populates ReferredToId on the new ClinicalServiceRequest.
4. Network status field on provider record drives in-network filtering logic.

Decision Guidance

Recommended Workflow

Step-by-step instructions for configuring Health Cloud referral management:

1. Verify prerequisites — confirm Health Cloud is enabled, HealthCloudGA managed package is installed, and the HealthCloudICM permission set is available. Check that the Provider Relationship Management objects (HealthcareProvider, HealthcarePractitionerFacility, and the related Account/Contact records) are populated — these are objects, not record types. Confirm Data Pipelines Base User license is provisioned.
2. Configure ClinicalServiceRequest — review and customize the Status picklist values for your referral workflow. Add custom fields if needed. Set up validation rules for required fields (PatientId, ReferralType, ReferredToId). Configure page layouts and record types for inbound vs. outbound referrals.
3. Set up Data Processing Engine job for provider search — in Setup > Data Processing Engine, configure the DPE job that populates CareProviderSearchableField from provider Account/Contact records. Schedule the job to run on a regular basis. Test by running manually and verifying CareProviderSearchableField records appear.
4. Build referral status Flow automation — create a Record-Triggered Flow on ClinicalServiceRequest to automate status transitions, send notifications, and create follow-up tasks. Include an error path for declined referrals.
5. Assign permission sets — assign HealthCloudICM to all referral-creating users. Assign Data Pipelines Base User to all users who run or trigger provider search DPE jobs. Verify in a sandbox before deploying to production.
6. Test end-to-end referral workflow — create a test referral, use provider search to find a provider, submit the referral, and simulate acceptance. Verify all status transitions, automation, and notifications fire correctly.

Review Checklist

• HealthCloudICM permission set assigned to all referral users
• Data Pipelines Base User license assigned for DPE job execution
• DPE job for CareProviderSearchableField is scheduled and successfully populating records
• ClinicalServiceRequest page layouts and record types configured for inbound and outbound
• Referral status Flow automation tested in sandbox
• Provider Relationship Management objects are populated (HealthcareProvider records exist and link to the Account/Contact records the search should return) — do not look for HealthcareProvider / HealthcarePractitioner record types; no such record types exist
• Referral reports and dashboards verified to show correct data

Salesforce-Specific Gotchas

1. Data Pipelines Base User license blocks provider search silently — If the process credential for DPE job execution lacks the Data Pipelines Base User permission set license, the job either fails to run or completes with zero records written to CareProviderSearchableField. Provider search components return empty results with no error message visible to end users. Always verify the license assignment before debugging provider search.

2. ClinicalServiceRequest requires HealthCloudICM permission set — Even with Health Cloud enabled, users without the HealthCloudICM permission set cannot create or update ClinicalServiceRequest records. This affects integration users, automated process users, and any profile-based user who was not explicitly assigned this permission set.

3. CareProviderSearchableField does not auto-refresh — The denormalized provider search index is not updated in real time when provider records change. If a provider's specialty, network status, or location changes, the DPE job must run again before the change is visible in provider search. Design provider record update workflows to trigger a DPE job re-run or build a scheduled refresh cadence.

Output Artifacts

Related Skills

• admin/health-cloud-patient-setup — Patient/person account setup required before referrals can reference a valid PatientId
• admin/care-program-management — Care program enrollment and referral tracking integration patterns
• admin/care-coordination-requirements — Care team coordination workflows that include referral handoffs