name: clinical-decision-support description: "Use this skill when implementing clinical decision support in Health Cloud: creating ClinicalAlert records via Apex or Flow, ingesting CareGap records from external clinical rules engines, displaying CDS alerts in FlexCard UIs, and integrating the Business Rules Engine for custom protocol checks. NOT for standard Flow automation unrelated to clinical decision support, or for clinical rules engine design outside of Salesforce." category: apex salesforce-version: "Spring '25+" well-architected-pillars:

• Reliability
• Operational Excellence
• Security triggers:
• "How do I create and display clinical alerts in Health Cloud for protocol compliance checking?"
• "ClinicalAlert and CareGap objects do not have a built-in rules engine — how are they populated?"
• "Integrating an external clinical rules engine with Salesforce Health Cloud ClinicalAlert objects"
• "How to use the Business Rules Engine with Health Cloud for custom care protocol checks"
• "CareGap records cannot be created manually — what is the correct ingestion pattern?" tags:
• health-cloud
• clinical-decision-support
• clinical-alert
• care-gap
• business-rules-engine
• cds-hooks
• protocol-compliance inputs:
• Health Cloud org with ICM enabled (for CareGap, API v59.0+)
• ClinicalAlert accessible (API v51.0+)
• External clinical rules engine or payer analytics system (for CareGap ingestion)
• HealthCloudICM permission set outputs:
• ClinicalAlert creation pattern (Apex trigger, Flow DML, or FHIR API ingest)
• CareGap ingestion architecture (external rules engine → FHIR API → Salesforce)
• FlexCard or LWC display of ClinicalAlert/CareGap records
• Business Rules Engine integration for custom protocol logic dependencies:
• admin/care-coordination-requirements
• apex/health-cloud-apis version: 1.0.0 author: Pranav Nagrecha updated: 2026-04-10

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:

   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

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

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