SfSkills Domains Docs GitHub

Home / devops / health-cloud-deployment-patterns

health-cloud-deployment-patterns

Use when planning or executing a Health Cloud deployment to production or a full sandbox, including managed package installation sequencing, Permission Set License assignment, care plan template setup, HIPAA compliance. NOT for Health Cloud data model design or Apex extensions in Health Cloud — use data/health-cloud-data-model.

Open the skill folder on GitHub

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:

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:

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

SituationRecommended ApproachReason
Deploying Health Cloud to a brand-new production orgSequential: packages first, metadata second, then manual post-deploy stepsPackage namespace must exist before metadata references are validated
Refreshing a full sandbox from productionReinstall packages in the sandbox at matching version, reassign PSLs, re-register CarePlanProcessorCallbackSandbox refresh wipes installed packages and configuration registrations
Migrating care plan templates between orgsExport via SOQL, recreate via invocable actions in targetDirect DML is blocked or produces malformed templates
Setting up Shield Encryption for clinical fieldsEnable encryption after package install, before any PHI is importedEncryption must be configured before PHI data is written, not after
Using scratch orgs for Health Cloud developmentLimited support; scratch orgs require Health Cloud features to be declared in project-scratch-def.json and packages installed via sf package installScratch org definition does not automatically provision HealthCloudGA namespace
Change set vs unlocked package for org-specific customizationsUnlocked package for Apex/LWC; change set for one-off configUnlocked packages support version pinning and dependency declaration; change sets have no dependency management

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:

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

ArtifactDescription
Ordered deployment runbookStep-by-step checklist covering package installs, metadata deploys, PSL assignments, and manual post-deploy steps
HIPAA compliance checklistPre-go-live checklist covering BAA, Shield Encryption, debug log restrictions, and audit logging
Care plan template inventoryList of templates to recreate in the target org, with entry and goal details for invocable action calls
Post-deploy validation reportConfirmation that CarePlanProcessorCallback is registered, encryption policies are active, and care plan templates are functional

Dependencies

Package files