clinical-decision-support

# Clinical Decision Support in Health Cloud

Use this skill when implementing clinical decision support in Health Cloud: creating ClinicalAlert records to surface clinical protocol alerts, ingesting CareGap records from external clinical rules engines, displaying CDS alerts in care coordinator UIs, and using the Business Rules Engine for custom protocol evaluation. This skill covers the implementation of CDS storage and display patterns. It does NOT cover standard Flow automation for non-clinical use cases, or the design of clinical rules logic outside of Salesforce (external clinical rules engines).

---

## Before Starting

Gather this context before working on anything in this domain:

- Understand that `ClinicalAlert` (API v51.0+) and `CareGap` (API v59.0+) are **passive data-model objects** — they are storage records for alerts and gaps, not active rules engines. Salesforce does NOT automatically evaluate clinical logic and create these records. They must be created via Apex, Flow DML, FHIR R4 API ingestion, or external system integration.
- For CareGap records specifically: they **cannot be created manually** by end users. They must be generated by an external clinical rules engine (payer quality analytics, HL7 CDS Hooks service) and ingested via FHIR R4 API or Apex. Any design that requires end-user CareGap creation must be redesigned.
- Confirm whether the Business Rules Engine (BRE) add-on is licensed. BRE is required for implementing declarative Salesforce-native clinical protocol evaluation rules. Without BRE, custom protocol checks must be implemented in Apex.
- Identify how CDS alerts will be displayed: Health Cloud FlexCards (OmniStudio-based), custom LWC, or the built-in ClinicalAlert list view in the care coordinator console.

---

## Core Concepts

### ClinicalAlert and CareGap Are Passive Storage Objects

This is the most critical concept for clinical decision support in Health Cloud:

**ClinicalAlert (API v51.0+):**
- A platform-standard object for storing clinical alerts (protocol deviations, care reminders, drug interactions).
- Has NO built-in rules evaluation engine.
- Records are created by: Apex triggers on clinical data changes, Record-Triggered Flows with DML on ClinicalAlert, or FHIR R4 API ingestion from external systems.
- Fields: `AlertType`, `AlertSeverity`, `PatientId`, `AlertMessage`, `Status`.

**CareGap (API v59.0+):**
- A platform-standard object for storing preventive care quality gaps.
- Has NO built-in rules evaluation engine.
- Records **cannot be created manually** — must be ingested from external clinical rules engines.
- Typically ingested via FHIR R4 API from payer quality analytics systems.

Salesforce does not ship a self-contained clinical protocol evaluation engine. The platform provides storage objects and display UI; clinical rules must come from an external system or be implemented in Apex/Flow.

### Business Rules Engine for Custom Protocol Logic

The Business Rules Engine (BRE) is an optional paid add-on that provides declarative rule evaluation within Salesforce. For clinical decision support use cases, BRE can:
- Evaluate patient record conditions against configured rules (e.g., "if patient has Type 2 Diabetes AND last A1c was > 6 months ago → create ClinicalAlert")
- Trigger alert creation when rules fire
- Support complex condition combinations without Apex code

Without BRE, equivalent logic must be implemented in Apex triggers or Flow decision chains.

### CDS Hooks Integration Pattern

CDS Hooks is the mechanism for integrating Salesforce clinical data into EHR clinical workflows as decision support alerts. The integration flow:
1. EHR clinician opens patient chart → EHR sends CDS Hook POST to MuleSoft endpoint.
2. MuleSoft queries Salesforce ClinicalAlert and CareGap records for the patient.
3. MuleSoft formats CDS card responses with alert summaries and action links.
4. EHR displays CDS cards in the clinical workflow.

There is no native Salesforce CDS Hook service. MuleSoft is required as the intermediary.

---

## Common Patterns

### Creating ClinicalAlert from a Clinical Data Trigger

**When to use:** When a clinical data change (new lab result, updated condition, medication interaction) should create an alert for the care coordinator.

**How it works:**
1. Create an Apex trigger on `CareObservation` (for lab results) or `HealthCondition` (for conditions) with `after insert, after update`.
2. In the trigger, evaluate the clinical logic (e.g., A1c observation value > threshold).
3. If the condition is met, create a `ClinicalAlert` record:
   ```apex
   ClinicalAlert alert = new ClinicalAlert(
       PatientId = observation.PatientId,
       AlertType = 'LabResult',
       AlertSeverity = 'High',
       AlertMessage = 'A1c result ' + observation.Value + ' exceeds threshold — care coordinator review required.',
       Status = 'Active'
   );
   insert alert;
   ```
4. The ClinicalAlert record appears in the care coordinator's alert view.

**Why not the alternative:** Using custom notification objects or Activity/Task for clinical alerts bypasses the standard Health Cloud ClinicalAlert display components in the care coordinator console.

### CareGap Ingestion from External Rules Engine

**When to use:** A payer's quality analytics system generates quality measure gaps that need to appear in Salesforce for care coordinator outreach.

**How it works:**
1. Payer quality system generates FHIR R4 Measure Report or CareGap resources.
2. MuleSoft (or custom integration) receives the gap data on a scheduled basis.
3. MuleSoft maps the FHIR CareGap resource to the Salesforce CareGap object fields.
4. MuleSoft calls the Salesforce FHIR Healthcare API or SObject API (with HealthCloudICM credentials) to create CareGap records.
5. Care coordinators see open CareGap records in their patient views.
6. Care coordinators acknowledge gaps and create outreach Tasks linked to CareGap records.

**Why not the alternative:** CareGap records cannot be created manually. An integration with the quality analytics system is required.

---

## Decision Guidance

| Situation | Pattern | Note |
|---|---|---|
| Create alert from lab result change | Apex trigger → ClinicalAlert insert | Direct platform DML |
| Populate quality measure gaps | External rules engine → FHIR API → CareGap | Cannot create manually |
| Complex protocol evaluation rules | Business Rules Engine (if licensed) | Otherwise: Apex logic |
| Display alerts in EHR workflow | MuleSoft CDS Hooks integration | No native SF CDS endpoint |
| Display alerts in Salesforce UI | FlexCard on ClinicalAlert or custom LWC | Standard console integration |

---

## Recommended Workflow

1. **Confirm clinical alert source** — identify which clinical events or external systems will generate ClinicalAlert or CareGap records. For ClinicalAlert: Apex/Flow on clinical data change events. For CareGap: external clinical rules engine via integration.
2. **Design alert creation mechanism** — for ClinicalAlert: define the trigger event (clinical object change), the clinical logic condition (threshold, rule), and the alert record fields. For CareGap: design the ingestion pipeline from the external rules engine.
3. **Implement ClinicalAlert creation** — build the Apex trigger or Record-Triggered Flow that creates ClinicalAlert records when the clinical condition is met. Ensure bulkification in Apex triggers.
4. **Design CareGap ingestion** — if CareGap records are needed, design the MuleSoft (or equivalent) integration pipeline from the external quality analytics system. Define ingestion schedule, field mapping, and deduplication logic.
5. **Configure alert display** — configure the care coordinator console to display ClinicalAlert records (via built-in components or FlexCards). Define the alert acknowledgment workflow.
6. **Test with representative clinical data** — test ClinicalAlert creation with clinical data records that trigger the alert conditions. Verify CareGap records appear from the integration. Test the alert display and acknowledgment workflow.

---

## Review Checklist

- [ ] ClinicalAlert creation mechanism is Apex/Flow/FHIR API (not manual entry)
- [ ] CareGap records are ingested from external rules engine (not manually created)
- [ ] Business Rules Engine licensed (if declarative rule evaluation is needed)
- [ ] Apex triggers for ClinicalAlert creation are bulkified
- [ ] HealthCloudICM permission set assigned to all API users creating clinical alert records
- [ ] CDS Hooks architecture (if needed) uses MuleSoft as the service endpoint

---

## Salesforce-Specific Gotchas

1. **Health Cloud has no native clinical rules evaluation engine** — ClinicalAlert and CareGap are storage objects only. Salesforce does not automatically evaluate clinical logic. Alert creation requires Apex, Flow, or external system integration. Assuming clinical alerts auto-generate from clinical data changes is the #1 implementation design error.

2. **CareGap records cannot be created manually or via standard DML** — CareGap records are system-generated via FHIR API ingest or external clinical rules engines. Standard Flow "Create Records" on CareGap or direct Apex DML inserts will fail or produce unauthorized records that do not participate in the quality measure lifecycle correctly.

3. **Apex triggers on clinical objects must be bulkified** — Clinical data bulk loads (e.g., during patient data migration or daily EHR sync) can produce large volumes of clinical object records in a single transaction. Apex triggers on CareObservation, HealthCondition, etc. must implement proper bulkification to avoid hitting trigger CPU time limits during bulk operations.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| ClinicalAlert creation trigger | Apex trigger on clinical objects that creates ClinicalAlert records based on threshold logic |
| CareGap ingestion design | Pipeline architecture from external quality system to Salesforce CareGap records |
| Alert display configuration | FlexCard or LWC configuration showing ClinicalAlert/CareGap on patient console |
| BRE rule definitions | Business Rules Engine rule configuration for declarative protocol evaluation |

---

## Related Skills

- admin/care-coordination-requirements — ICM object design including CareGap constraints
- apex/health-cloud-apis — FHIR Healthcare API usage for CareGap ingestion
- apex/fhir-integration-patterns — FHIR integration patterns for clinical data ingestion