Health Cloud Deployment Patterns

Health Cloud Deployment Patterns

Use this skill when planning or executing a Health Cloud deployment to production or a full sandbox. It covers the strict managed-package installation sequence required before metadata deployment, the manual post-deploy steps that are not captured in any deployable metadata artifact, HIPAA compliance controls that must be configured before PHI is stored, and the care plan template setup constraints enforced by the HealthCloudGA namespace.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the HealthCloudGA managed package version that must be installed and verify whether any dependent industry packages (e.g., Salesforce Industries Common Components) are also required and in what order.
• Determine whether a signed HIPAA BAA is in place before any PHI touches the target org. Salesforce requires a signed BAA before Health Cloud can be used with real patient data. Shield Platform Encryption configuration must follow immediately after.
• Understand that care plan templates (CarePlanTemplate__c) live in the HealthCloudGA namespace and are created only through invocable actions — direct DML is blocked by the platform. They cannot be captured in standard metadata deployments; they are set up as a post-deploy manual step or via Apex that calls the invocable action.
• Confirm that CarePlanProcessorCallback is a class you have authored in your org (or is provided by a package), and that it must be manually registered in Health Cloud Setup under Care Plan Settings after every deploy to a new org. This registration step produces no metadata artifact and is invisible to your CI/CD pipeline.

Core Concepts

Strict Managed Package Installation Order

Health Cloud deployments require the HealthCloudGA managed package to be installed before any dependent custom metadata, permission sets, or Apex classes are deployed. The platform enforces namespace resolution at deploy time: metadata that references HealthCloudGA namespace fields, objects, or classes will fail validation if the package is not present. Installing dependent packages (such as Omnistudio or Salesforce Industries Common Components) out of order causes the same namespace resolution failures.

The canonical install sequence is:

1. Salesforce Industries Common Components (if required by your org)
2. HealthCloudGA managed package
3. Any additional Health Cloud feature packages (e.g., Provider Search, Intelligent Appointment Management) in the order documented in the Health Cloud Administration guide
4. Your org-specific metadata (flows, permission sets, custom objects, Apex classes)

There is no automated way to enforce this order in a standard sf project deploy run. It must be scripted or documented as a pre-deploy checklist step.

Permission Set Licenses Are Assigned Post-Install

After the HealthCloudGA package installs, Health Cloud Permission Set Licenses (PSLs) are available in the org but are not automatically assigned to users. PSL assignment must occur before end-user permission sets that reference Health Cloud features can be assigned. Deploying a permission set that grants Health Cloud object access to a user who has no PSL results in a deployment success but a runtime access failure — the user simply cannot open Health Cloud records.

PSL assignment is done through Setup > Users > Permission Set License Assignments and cannot be captured in metadata. It must be documented as an explicit post-deploy step in every deployment runbook.

Care Plan Templates Cannot Be Deployed as Metadata

CarePlanTemplate__c and its child records (CarePlanTemplateEntry__c, CarePlanTemplateGoal__c) are HealthCloudGA namespace objects. While they can be queried via SOQL and inserted via the API in theory, the platform enforces that care plan templates must be created through the Health Cloud Care Plan Template invocable action (HealthCloud.CreateCarePlanTemplate). Direct DML attempts either fail silently or produce incomplete records. This means care plan templates are not captured in sfdx source format or change sets and must be recreated or migrated using invocable actions or the Health Cloud Setup UI in each new org.

CarePlanProcessorCallback Is a Post-Deploy Manual Registration

CarePlanProcessorCallback is a class that implements the HealthCloud.CarePlanProcessorCallbackInterface interface. After deploying this class to a new org (or after any reinstall of HealthCloudGA), the class must be manually registered in Setup > Health Cloud Setup > Care Plan Settings > CarePlan Processor Callback. This registration writes to a Custom Metadata Type record, but that record is in the HealthCloudGA namespace and is not retrievable as part of your org's metadata via sf project retrieve. If you restore an org from backup or deploy to a fresh sandbox, this step must be repeated.

HIPAA Controls Are Configuration, Not Metadata

HIPAA-relevant controls in Health Cloud are primarily org configuration decisions, not metadata artifacts:

• Signed BAA with Salesforce must precede any PHI storage.
• Shield Platform Encryption must be enabled and tenant secrets generated; encryption policies for clinical fields (e.g., fields on EhrPatientMedication__c, PatientHealthCondition__c, CarePlanActivity__c) must be set in the Encryption Policy UI.
• Debug log restrictions: enabling debug logs on a production Health Cloud org risks capturing PHI in log output. Log levels must be gated and logs purged after debugging. This is an operational control, not a metadata setting.
• Audit trail and event log: Field Audit Trail or Event Monitoring should be configured for access to clinical records.

Common Patterns

Sequential Package-Then-Metadata Deployment

When to use: Every Health Cloud deployment to production or a new full sandbox.

How it works:

1. Install Salesforce Industries Common Components package (if required) via Setup > Installed Packages or sf package install.
2. Install HealthCloudGA managed package at the correct version.
3. Install any additional Health Cloud feature packages.
4. Assign Health Cloud Permission Set Licenses to appropriate users or groups.
5. Run sf project deploy start for org-specific metadata (custom objects, flows, Apex, permission sets).
6. Perform post-deploy manual steps: register CarePlanProcessorCallback in Care Plan Settings, configure Shield Encryption policies, create care plan templates via invocable actions or UI.

Why not a single deploy: There is no way to combine managed package installation with a sf project deploy command. They are separate operations. Any metadata that references the HealthCloudGA namespace must be deployed after the package exists in the target org.

Care Plan Template Migration via Invocable Actions

When to use: When care plan templates must be reproduced in a new sandbox or production org from an existing org.

How it works:

1. Query existing templates in the source org: SELECT Id, Name, HealthCloudGA__Description__c FROM HealthCloudGA__CarePlanTemplate__c.
2. For each template, call the HealthCloud.CreateCarePlanTemplate invocable action in the target org, passing name, description, and entry/goal details.
3. Verify template creation in the target org via the Health Cloud Care Plan Templates list view.

Why not direct insert: Direct DML on CarePlanTemplate__c bypasses the platform's template validation logic and either fails or produces malformed templates that do not function correctly in the Care Plan wizard.

HIPAA Pre-Go-Live Configuration Pattern

When to use: Before Health Cloud goes live with real patient data.

How it works:

1. Confirm signed BAA with Salesforce Account team.
2. Enable Shield Platform Encryption; generate and activate a tenant secret.
3. Define encryption policies for all clinical fields that may contain PHI (patient demographics, medication data, care plan notes).
4. Restrict debug log access: remove Modify All Data or View All Data from debug log profiles; set a post-debug log purge procedure.
5. Enable Field Audit Trail or Event Monitoring for access logging to clinical records.
6. Review all integration users and connected apps for PHI exposure risk.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner deploying Health Cloud:

1. Verify the signed BAA and compliance posture. Confirm that Salesforce has cosigned the HIPAA BAA for this org before any PHI or test PHI is planned for import. If BAA is not signed, halt and escalate.
2. Install managed packages in order. Install Salesforce Industries Common Components (if required), then HealthCloudGA at the target version, then any feature packages. Use sf package install --package <04t...> --target-org <alias> or Setup UI. Verify installed packages list before proceeding.
3. Assign Permission Set Licenses. In Setup > Users > Permission Set License Assignments, assign the Health Cloud PSL to all users or permission set groups that will use Health Cloud features. Document the assignment in the deployment runbook.
4. Deploy org-specific metadata. Run sf project deploy start --target-org <alias> for custom objects, flows, Apex classes, permission sets, and custom metadata. Validate first with sf project deploy validate. Resolve any namespace resolution errors before proceeding.
5. Register CarePlanProcessorCallback. Navigate to Setup > Health Cloud Setup > Care Plan Settings. In the CarePlan Processor Callback field, select and save the callback class. Confirm the class name matches what was deployed. Document this step in the runbook as a required post-deploy action.
6. Configure Shield Platform Encryption. Generate and activate a tenant secret. Define encryption policies for all clinical fields identified in the HIPAA field inventory. Test that encrypted fields are readable by authorized users and blocked from unauthorized profiles.
7. Create care plan templates. Use the Health Cloud Care Plan Templates UI or invoke HealthCloud.CreateCarePlanTemplate to recreate templates in the target org. Verify that templates appear in the Care Plan wizard and that entries and goals are correct.

Review Checklist

Run through these before marking a Health Cloud deployment complete:

• Signed HIPAA BAA confirmed with Salesforce Account team before any PHI is stored
• HealthCloudGA managed package installed at correct version; verified in Installed Packages list
• Health Cloud Permission Set Licenses assigned to all relevant users or groups
• Org-specific metadata deployed and validated; all tests passing
• CarePlanProcessorCallback class registered in Setup > Health Cloud Setup > Care Plan Settings
• Shield Platform Encryption enabled; tenant secret active; encryption policies applied to all clinical fields
• Care plan templates created or verified in target org via invocable actions or UI
• Debug log access restricted; post-debug log purge procedure documented
• Integration users and connected apps reviewed for PHI exposure risk

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. CarePlanProcessorCallback registration is invisible to CI/CD — Registering the callback class in Care Plan Settings writes to a Custom Metadata Type in the HealthCloudGA namespace, which is not retrievable via sf project retrieve. Every deployment to a new org or sandbox refresh requires manual re-registration. CI/CD pipelines that assume a full org restore cannot detect this gap.
2. Care plan templates fail silently on direct DML — Attempting to insert HealthCloudGA__CarePlanTemplate__c records via direct DML either fails with a generic error or produces records that appear valid in SOQL but are non-functional in the Care Plan wizard. Only the HealthCloud.CreateCarePlanTemplate invocable action produces correctly formed templates.
3. PSL assignment required before permission set assignment works at runtime — A user without a Health Cloud PSL can receive a Health Cloud permission set without error, but will receive "insufficient privileges" errors at runtime when accessing Health Cloud features. This silent failure makes troubleshooting confusing. Always confirm PSL assignment before testing permission set access.
4. Sandbox refresh wipes HealthCloudGA package and configuration — A full sandbox refresh from production does not preserve the installed HealthCloudGA package, PSL assignments, or the CarePlanProcessorCallback registration. The post-deploy manual steps must be repeated in full after every sandbox refresh. Partial sandbox refreshes (source sandbox) may preserve packages but still lose configuration registrations.
5. Shield Encryption must precede PHI import — If Shield Platform Encryption policies are configured after PHI data is already present in the org, existing data is not retroactively encrypted. The encryption policy applies only to new writes. Retroactive encryption requires a data re-import or Salesforce support involvement. Always configure encryption before importing any PHI.

Output Artifacts

Related Skills

• devops/permission-set-deployment-ordering — for the detailed rules governing Health Cloud permission set and PSL ordering during deployment
• devops/go-live-cutover-planning — for the broader go-live runbook that wraps this Health Cloud deployment checklist
• data/health-cloud-data-model — for understanding which objects and fields are in the HealthCloudGA namespace and must be treated as managed-package components
• apex/health-cloud-apex-extensions — for Apex-level patterns including CarePlanProcessorCallback implementation and invocable action usage
• devops/deployment-monitoring — for post-deploy health monitoring of Health Cloud orgs