SfSkills Domains Docs GitHub

Home / apex / health-cloud-apex-extensions

health-cloud-apex-extensions

Use this skill when extending Health Cloud via Apex: implementing HealthCloudGA managed-package interfaces, automating care plan lifecycle hooks, processing referrals using Industries Common Components invocable actions, or enforcing HIPAA-compliant logging governance for clinical Apex code.

Open the skill folder on GitHub

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:

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

SituationRecommended ApproachReason
Execute logic when a care plan is activatedImplement HealthCloudGA.CarePlanProcessorCallback and register it in Health Cloud SetupFires reliably within the managed-package lifecycle; Apex trigger on CarePlan does not catch all transitions
Create a care plan from ApexCall the CreateCarePlan invocable action via Invocable.ActionEnforces consent evaluation and lifecycle hooks; raw DML bypasses both
Process an inbound referralUse ICC industries_referral_mgmt__CreateReferral invocable actionApplies provider matching, consent, and routing rules from the ICC framework
Add a goal to an existing care planCall AddCarePlanGoal invocable actionMaintains data model integrity; direct DML on CarePlanGoal may produce orphaned records
Log debug info in a class touching clinical objectsUse conditional debug logging gated by a Custom Setting or Custom Metadata flagPrevents PHI from entering debug logs in production; gate on environment type
Validate care plan Apex in a scratch orgUse a Health Cloud scratch org definition with Health Cloud features enabledEnsures HealthCloudGA namespace and test data factories are available

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:

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

ArtifactDescription
Compliant HealthCloudGA Apex extension classA global Apex class implementing the target HealthCloudGA interface with correct method signatures and Setup registration instructions
Invocable action call patternApex snippet using Invocable.Action to call CreateCarePlan, AddCarePlanGoal, or ICC referral actions with input/output handling
Debug logging governance checklistList of System.debug() statements audited for PHI exposure with recommended Custom Metadata gate pattern
Unit test scaffold@IsTest class covering callback methods and action calls, using Health Cloud test data factories where available

Dependencies

Package files