Health Cloud Apex Extensions

Health Cloud Apex Extensions

This skill activates when a practitioner needs to extend Salesforce Health Cloud behavior through Apex, specifically using the HealthCloudGA managed-package namespace, Health Cloud invocable actions for care plan automation, Industries Common Components for referral processing, or when governance of PHI-containing Apex debug logs is required.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the HealthCloudGA managed package is installed and the version number. Interface signatures and available invocable actions vary across package releases.
• Determine whether the org uses the Integrated Care Management (ICM) data model or the legacy CarePlanTemplate__c model. Extension points differ between the two.
• Identify whether Apex debug logs are enabled in production. Logs containing EhrPatientMedication, PatientHealthCondition, or similar clinical objects constitute PHI and require governance.
• Confirm the org has AuthorizationFormConsent properly configured — bypassing consent enforcement through direct DML is a compliance and data integrity risk.

Core Concepts

HealthCloudGA Namespace and Managed-Package Interfaces

Health Cloud ships as a managed package under the HealthCloudGA namespace. Extension points are provided as Apex interfaces and abstract classes within this namespace. The most critical is HealthCloudGA.CarePlanProcessorCallback, which exposes lifecycle hooks for care plan creation, activation, and closure. Implementing this interface requires your class to be declared globally, and the implementation must be registered in Health Cloud Setup — simply deploying the class is insufficient. Interface method signatures are enforced by the managed package; mismatched signatures fail at deploy time.

Care Plan Invocable Actions vs. Raw DML

Health Cloud provides built-in invocable actions — CreateCarePlan, AddCarePlanGoal, AddCarePlanProblem — that encapsulate the full automation logic for care plan records. These actions enforce consent checks via AuthorizationFormConsent, trigger care plan lifecycle events, and maintain data integrity within the Health Cloud data model. Using raw insert or update DML on CarePlanTemplate__c, CarePlan, or related objects bypasses all of this automation. The result is care plan records in an inconsistent state: goals created without the proper problem linkages, consent not evaluated, and lifecycle callbacks not fired. Always invoke care plan changes through the provided invocable actions or the HealthCloudGA Apex service layer.

Industries Common Components — Referral Processing

The Industries Common Components (ICC) framework powers referral processing in Health Cloud. Referrals are represented as ReferralRequest and ReferralResponse records. The framework exposes Apex invocable actions for referral submission, status updates, and routing logic. Apex classes that need to trigger referral workflows must call these invocable actions rather than performing DML on ReferralRequest directly, for the same reasons as care plan invocable actions: the framework enforces business rules, consent, and notification logic at the action layer.

HIPAA Apex Logging Governance

Salesforce Apex debug logs are not subject to field-level security or sharing rules — a log entry that captures a SOQL query result or a variable inspect for EhrPatientMedication, PatientHealthCondition, ClinicalEncounterCode, or similar clinical objects writes PHI as plain text to the debug log store. Under HIPAA, this constitutes a data exposure risk. Production debug logging must be disabled or tightly scoped (specific user, short duration), logs must be purged after use, and no automated process should retain clinical-field variable dumps in long-lived log stores. This applies equally to System.debug() calls in trigger handlers and to Flow-launched Apex actions.

Common Patterns

Implementing CarePlanProcessorCallback

When to use: You need to execute custom logic when a care plan transitions state — e.g., notifying a care coordinator when a care plan is activated, or creating a Task when a care plan closes.

How it works:

1. Declare a global Apex class implementing HealthCloudGA.CarePlanProcessorCallback.
2. Implement the required interface methods: onCarePlanCreate, onCarePlanActivate, onCarePlanClose (exact method signatures depend on the installed package version — always reference the installed namespace documentation).
3. Register the class name in Health Cloud Setup > Care Plan Settings > Custom Apex Callback.
4. Keep callback logic lightweight: avoid synchronous callouts, limit SOQL to selective queries, and delegate heavy work to @future or Queueable Apex to stay within governor limits.

Why not the alternative: Adding an Apex trigger on the CarePlan object fires outside the Health Cloud lifecycle framework. It cannot reliably intercept all state transitions and misses events triggered by managed-package automation.

Referral Invocable Action Pattern

When to use: An Apex class or Flow needs to create or update a referral programmatically — e.g., when a clinical intake process determines that an external specialist referral is required.

How it works:

1. Use Invocable.Action to invoke the industries_referral_mgmt__CreateReferral or equivalent ICC invocable action from Apex rather than performing insert new ReferralRequest__c(...).
2. Populate the input ReferralRequest wrapper object with patient context, referring provider, and target specialty.
3. Evaluate the ReferralResponse output for status and any error messages before proceeding.
4. If the referral fails validation, surface the error to the user via a platform event or record status field — do not silently swallow the response.

Why not the alternative: Direct DML on ReferralRequest__c skips the ICC business rules engine, consent checks, and provider matching logic. The resulting record may be technically valid in the database but functionally broken in the referral management UI and reporting.

Decision Guidance

Recommended Workflow

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

1. Confirm the installed HealthCloudGA package version and identify the specific extension point needed (callback interface, invocable action, or ICC action). Pull the interface signature from the namespace documentation or by inspecting the installed package in Setup > Installed Packages.
2. Determine whether the request involves care plan lifecycle, referral processing, or general clinical data automation. Route to the appropriate pattern: CarePlanProcessorCallback for lifecycle hooks, CreateCarePlan/AddCarePlanGoal invocable actions for care plan data, or ICC actions for referrals.
3. Implement the Apex class: declare it global if it implements a HealthCloudGA interface, use Invocable.Action for action-based calls, and ensure all DML on Health Cloud clinical objects is routed through the appropriate service layer rather than direct DML.
4. Audit all System.debug() calls and SOQL result references in the class — remove or gate any statements that would dump clinical object fields (EhrPatientMedication, PatientHealthCondition, ClinicalEncounterCode, AuthorizationFormConsent) into debug logs. Add a Custom Metadata-based debug gate.
5. Register the callback class in Health Cloud Setup if using CarePlanProcessorCallback, write unit tests using @IsTest with Health Cloud test data factories, and verify that no direct DML on CarePlan, CarePlanTemplate__c, or ReferralRequest__c remains in the code path.

Review Checklist

Run through these before marking work in this area complete:

• Apex class implementing a HealthCloudGA interface is declared global and registered in Health Cloud Setup
• All care plan creation and modification routes through CreateCarePlan / AddCarePlanGoal invocable actions, not direct DML
• All referral creation routes through ICC invocable actions, not direct DML on ReferralRequest__c
• System.debug() calls referencing clinical object fields are removed or gated by a Custom Metadata debug flag
• Production debug log retention policy reviewed — no persistent logs containing PHI
• Unit tests cover callback interface methods and invocable action calls with mock responses
• Consent enforcement via AuthorizationFormConsent is not bypassed by any code path

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. CarePlanProcessorCallback requires Setup registration — Deploying a class that implements HealthCloudGA.CarePlanProcessorCallback is not sufficient. The class name must be explicitly registered in Health Cloud Setup > Care Plan Settings. An unregistered callback silently does nothing; there is no deploy-time or runtime error.
2. Direct DML on clinical objects bypasses consent enforcement — Inserting or updating CarePlan, CarePlanGoal, or CarePlanProblem directly bypasses AuthorizationFormConsent evaluation. The record is created, but the consent check never fires. This is both a compliance gap and a functional gap — Health Cloud UI features that depend on consent state will behave inconsistently.
3. Apex debug logs containing clinical fields are PHI — EhrPatientMedication, PatientHealthCondition, ClinicalEncounterCode, and similar objects contain protected health information. Debug logs are stored in plaintext and are accessible to any system administrator. Production debug logging on clinical Apex classes must be disabled by default, time-limited when enabled for troubleshooting, and purged immediately after use.

Output Artifacts

Related Skills

• admin/care-plan-configuration — Required prerequisite: care plan templates and ICM configuration must be in place before Apex extensions can be effectively implemented or tested
• apex/apex-security-patterns — Security patterns for FLS, CRUD, and sharing enforcement that also apply to clinical Apex classes
• apex/clinical-decision-support — Clinical decision logic patterns that frequently interact with care plan and referral Apex extension points