hipaa-workflow-design · diff
v1.0.0 to v1.0.1
106 added, 69 removed. Audit A to A.
---
name: hipaa-workflow-design
description: "Use this skill when designing HIPAA-compliant workflow requirements for Health Cloud: minimum necessary access design, audit trail requirements mapping, access control patterns, and BAA dependency identification. NOT for org-level HIPAA architecture or Shield encryption configuration — use architect/hipaa-compliance-architecture. NOT for care team and SDOH process design — use admin/care-coordination-requirements."
category: admin
salesforce-version: "Spring '25+"
well-architected-pillars:
- Security
- Operational Excellence
triggers:
- "How do I design HIPAA-compliant workflows in Health Cloud for minimum necessary access?"
- "What are the HIPAA audit trail requirements in Salesforce and how do they map to platform controls?"
- "BAA with Salesforce prerequisites for storing PHI in Health Cloud"
- "Why is Field Audit Trail required for HIPAA instead of standard Field History Tracking?"
- "HIPAA Security Rule mapping to Salesforce Shield controls for healthcare implementation"
+ - "tag PHI fields with the HIPAA compliance group in field metadata"
+ - "keep field history for clinical fields longer than 18 months"
tags:
- health-cloud
- hipaa
- phi-compliance
- audit-trail
- shield
- baa
- access-control
inputs:
- Health Cloud org (BAA signed or in process with Salesforce)
- PHI field inventory (which fields contain protected health information)
- Documented user role taxonomy
- HIPAA compliance requirements from legal/compliance team
outputs:
- HIPAA workflow requirements mapped to Salesforce platform controls
- PHI access control design (OWD + sharing + permission sets)
- Audit trail requirements specification (Shield Field Audit Trail vs. standard field history)
- Event Monitoring retention policy requirements
- BAA dependency checklist
dependencies:
- admin/health-cloud-patient-setup
- admin/health-cloud-consent-management
- version: 1.0.0
+ version: 1.0.1
author: Pranav Nagrecha
- updated: 2026-04-10
+ updated: 2026-10-03
---
# HIPAA Workflow Design for Health Cloud
- Use this skill when designing HIPAA-compliant workflow requirements for Health Cloud: defining minimum necessary access patterns, identifying audit trail requirements, designing access controls for PHI, and mapping HIPAA Security Rule provisions to Salesforce platform controls. This skill focuses on requirements design and mapping. It does NOT cover the technical implementation of security controls (Shield Platform Encryption field configuration, Event Monitoring stream setup, field-level security configuration) — those are implementation-layer skills.
+ Use this skill when designing HIPAA-driven workflow requirements for Health Cloud: minimum necessary access, audit trail requirements, PHI access controls, and the mapping from HIPAA safeguards to Salesforce controls. It covers requirements design and mapping. It does NOT cover the build of security controls (Shield Platform Encryption configuration, Event Monitoring pipelines, field-level security setup), which belong to implementation skills.
+ Grounding note: retention, field tracking, encryption, and Event Monitoring facts here are grounded in the Salesforce Security Guide, Object Reference, and Metadata API Developer Guide (Summer '26). HIPAA regulation text (45 CFR Part 164) and the Salesforce BAA terms did not fetch for this pass, so regulatory citations and BAA scope statements carry UNVERIFIED markers. Legal counsel owns those interpretations.
+
---
## Before Starting
- Gather this context before working on anything in this domain:
+ - Confirm the Business Associate Agreement (BAA) status with Salesforce and which services it covers. UNVERIFIED (2026-10-03): BAA coverage is product-specific and must be in place before PHI is stored; this is a contractual matter not described in the technical guides read.
+ - Inventory every field that holds PHI and tag it in metadata. `CustomField.complianceGroup` accepts `HIPAA` (with `CCPA`, `COPPA`, `GDPR`, `PCI`, `PII`), and `securityClassification` accepts `Public`, `Internal`, `Confidential`, `Restricted`, and `MissionCritical`.
+ - Check which PHI fields can be history-tracked at all. Field history cannot track formula, roll-up summary, or auto-number fields, Created By and Last Modified By, long text fields, or multi-select fields. Clinical notes in long text fields need another audit approach.
+ - Confirm Shield licences (Platform Encryption, Event Monitoring, Field Audit Trail) are in the contract. UNVERIFIED (2026-10-03): that Shield is never included in any edition is a commercial claim not in the guides read.
- - Confirm that a Business Associate Agreement (BAA) has been signed with Salesforce OR is in the procurement pipeline. No PHI may legally reside in any Salesforce org until the BAA is executed. This is a hard prerequisite.
- - Identify which Salesforce products are covered under the BAA. Only specific Salesforce products are BAA-eligible. PHI stored in non-covered services (certain Chatter features, some AppExchange products) voids HIPAA coverage even with Shield enabled.
- - Inventory all PHI fields. PHI includes all 18 HIPAA identifier categories: names, dates (except year), geographic data below state, phone/fax, email, SSN, medical record numbers, health plan numbers, account numbers, certificate/license numbers, VINs, device identifiers, URLs, IP addresses, biometric identifiers, full-face photos, and any unique identifying code.
- - Confirm Shield Platform Encryption, Field Audit Trail, and Event Monitoring licenses are in the contract. Shield is a paid add-on not included in any Salesforce edition.
+ ---
+ ## Questions to Ask Before Configuring
+
+ Ask these before designing access or audit controls. Each one traces to a gotcha in `references/gotchas.md`.
+
+ | Question | Why it matters | What a good answer adds | What proper configuration adds over just doing it |
+ |---|---|---|---|
+ | "How long must field change history be kept, and who decides when it may be deleted?" | Without Field Audit Trail, history lasts 18 months (24 via API); with it, archived history is kept until deleted (gotcha 1) | A retention period, an owner, and a deletion procedure | Audit evidence that exists when an investigator asks |
+ | "Which PHI fields are long text, multi-select, or formulas?" | Those fields cannot be history-tracked (gotcha 2) | A list of untrackable PHI fields and the alternative evidence for each | No false assumption that every PHI change is audited |
+ | "How long must access logs be kept, and where?" | Event Log Files are kept one year by default for Shield and Event Monitoring customers; streaming events three days; Event Log Objects 30 days (gotcha 3) | A log retention target and an external store | Access history that survives past the platform window |
+ | "Will Platform Encryption be turned on after history is already archived?" | Previously archived field history stays unencrypted (gotcha 4) | An encryption timeline aligned with archiving | No unencrypted PHI left in the archive |
+ | "Which roles need which PHI fields?" | Minimum necessary access is field-level as well as record-level (gotcha 6) | An access matrix per role and field | Permission sets that grant only what each role needs |
+ | "Are PHI fields tagged so they can be found later?" | `complianceGroup` and `securityClassification` live on the field definition (gotcha 7) | A tagging rule applied in every field deploy | A PHI inventory that maintains itself |
+
+ What a proper HIPAA design adds over "just turning on Shield": every PHI field is tagged, its history is kept as long as policy requires, access logs leave the platform before they expire, and each role sees only the fields it needs.
+
---
## Core Concepts
- ### HIPAA Shared Responsibility Model
+ ### Shared responsibility
- Salesforce is responsible for infrastructure security (data center, network, platform availability). The customer is responsible for application-level controls: who can access PHI, encryption configuration, audit trail setup, consent workflows, and policies/procedures. The BAA documents this shared responsibility. A signed BAA does not make the org HIPAA-compliant — the customer must implement all required technical safeguards.
+ Salesforce runs the infrastructure; the customer configures who can access PHI, encryption, audit retention, consent workflows, and policies. UNVERIFIED (2026-10-03): the BAA documents this split; its text was not read for this pass.
- ### HIPAA Security Rule to Salesforce Control Mapping
+ ### HIPAA safeguard to Salesforce control mapping
- | HIPAA Requirement | Salesforce Control |
- |---|---|
- | Access Control (§164.312(a)(1)) | OWD = Private + sharing rules + permission sets + care team role-scoped access |
- | Audit Controls (§164.312(b)) | Shield Field Audit Trail (10-year retention); Event Monitoring for system access logs |
- | Integrity (§164.312(c)(1)) | Shield Platform Encryption for PHI at rest; TLS for data in transit |
- | Transmission Security (§164.312(e)(1)) | TLS enforced; no PHI in HTTP headers or query strings |
- | Minimum Necessary (§164.514(d)) | OWD-Private + care team role scoping |
+ | HIPAA safeguard (as cited by earlier versions of this skill) | Salesforce control | Grounded platform fact |
+ |---|---|---|
+ | Access control | Private org-wide defaults, sharing, permission sets with field-level security | Permission sets carry `fieldPermissions` and `objectPermissions` |
+ | Audit controls | Field history tracking with Field Audit Trail; Event Monitoring | Retention figures in gotchas 1 and 3 |
+ | Integrity and encryption at rest | Shield Platform Encryption (`encryptionScheme` on fields) | `ProbabilisticEncryption`, `CaseSensitiveDeterministicEncryption`, `CaseInsensitiveDeterministicEncryption` |
+ | Minimum necessary | Role-scoped records plus field-level permission sets | Same as access control |
- ### Standard Field History Tracking Does NOT Satisfy HIPAA
+ UNVERIFIED (2026-10-03): the section numbers earlier versions of this skill attached to these safeguards (§164.312(a)(1), §164.312(b), §164.312(c)(1), §164.312(e)(1), §164.514(d)) and the "6-year" retention figure come from HIPAA regulation text that did not fetch. The 6-year figure is commonly attributed to the documentation retention rule in 45 CFR 164.316(b)(2); confirm with counsel whether it applies to raw audit logs.
- HIPAA requires audit log retention for 6 years from the date of creation or last effective date. Standard Field History Tracking retains only 18 months. Shield Field Audit Trail provides up to 10 years of field-level change history. Using standard Field History Tracking for PHI fields will fail a HIPAA audit — this is one of the most consequential architectural mistakes in Health Cloud implementations.
+ ### Field history retention
- ### Event Monitoring Log Expiration
+ | Setup | Retention | Fields per object |
+ |---|---|---|
+ | Field history tracking without Field Audit Trail | Up to 18 months, and up to 24 months through the API | Up to 20 |
+ | Field Audit Trail on | Archived history kept until you delete it; by default history moves to the `FieldHistoryArchive` big object after 18 months in production and 1 month in sandboxes | Up to 200 |
- Event Monitoring logs in Salesforce are retained for only 30 days by default. HIPAA requires 6-year retention for access audit logs. Event Monitoring logs must be streamed to an external SIEM (Security Information and Event Management) system within 30 days. Salesforce does not provide long-term storage — this is an ongoing operational requirement, not a one-time configuration.
+ A `HistoryRetentionPolicy` sets `archiveAfterMonths` (1 to 18, default 18) and `archiveRetentionYears` (a reminder for manual deletion; data is not deleted automatically). Earlier versions of this skill said Field Audit Trail keeps history "up to 10 years"; the Summer '26 Security Guide says archived data is kept until you delete it.
+ ### Event Monitoring retention
+
+ | Source | Retention |
+ |---|---|
+ | Event Log Files | "All Shield and Event Monitoring customers have 1 year of Event Log File storage enabled by default" |
+ | Real-time event streams | "Streaming events are retained for up to three days" |
+ | Event Log Objects (Hyperforce) | "Log data is retained for up to 30 days" |
+ | LoginHistory and LoginEvent | 6 months |
+
+ Earlier versions of this skill said Event Monitoring logs expire after 30 days by default; that is true of Event Log Objects and of the Login event log lines in one comparison table, but not of Event Log File storage for Shield and Event Monitoring customers. Multi-year retention still requires an external store.
+
---
## Common Patterns
- ### Minimum Necessary Access Design
+ ### Minimum necessary access design
- **When to use:** Designing the permission model for a Health Cloud org with multiple user roles and varying PHI access needs.
+ **When to use:** Several roles need different slices of PHI.
**How it works:**
- 1. Define user roles: primary care clinicians, specialists, care coordinators, administrative staff, billing staff, compliance officers.
- 2. Set OWD to Private for Account (patient records) and all clinical objects.
- 3. Use care team role-based sharing: each care team member gets read/edit access to their assigned patient records only. Non-care-team users have no default access.
- 4. Use permission sets (not profiles) to control field-level access to PHI fields — administrative staff get demographic PHI access but not clinical PHI; billing staff get billing codes but not diagnosis notes.
- 5. Document the access matrix.
-
- **Why not the alternative:** Public OWD or over-broad permission sets violate the minimum necessary standard by exposing all PHI to all users regardless of care role.
+ 1. Define roles: clinicians, specialists, care coordinators, front desk, billing, compliance.
+ 2. Set org-wide defaults to Private for patient accounts and clinical objects.
+ 3. Grant record access through care team or role-based sharing.
+ 4. Grant field access with permission sets, one per role, from the access matrix; front desk gets demographics, billing gets billing codes, neither gets clinical notes.
+ 5. Tag every PHI field with `complianceGroup` HIPAA and a `securityClassification` (deployable example in `references/metadata-examples.md`).
- ### HIPAA Audit Trail Architecture
+ ### Audit trail architecture
- **When to use:** Specifying audit trail controls for a production Health Cloud org.
+ **When to use:** Specifying audit controls for production.
**How it works:**
- 1. Shield Field Audit Trail for all PHI fields — set retention to 10 years.
- 2. Event Monitoring enabled for Login, Logout, Report, API Access, and field access events.
- 3. Event Monitoring logs streamed to an external SIEM within 30 days.
- 4. SIEM retention policy set to 6 years minimum.
- 5. Document the complete audit trail architecture in the BAA/compliance record.
+ 1. Track history on every trackable PHI field (`enableHistory` on the object, `trackHistory` on the field).
+ 2. With Field Audit Trail, set a `HistoryRetentionPolicy` per object and a documented deletion procedure for archived data.
+ 3. List untrackable PHI fields (long text, multi-select, formulas) and define alternative evidence.
+ 4. Export Event Log Files to an external store before the one-year window ends, and subscribe to real-time events if near-real-time alerting is needed.
+ 5. Set the external retention period from counsel's interpretation.
---
## Decision Guidance
| Situation | Recommended Approach | Reason |
|---|---|---|
- | PHI field change history | Shield Field Audit Trail | 10-year retention; standard Field History = 18 months |
- | System access log retention | Event Monitoring + SIEM streaming | Logs expire in 30 days without external streaming |
- | PHI at-rest encryption | Shield Platform Encryption | Required HIPAA technical safeguard |
- | Patient record access control | OWD-Private + care team sharing | Minimum necessary access enforcement |
- | BAA not yet signed | Do not store PHI | Hard regulatory prerequisite |
- | AppExchange product used with PHI | Verify BAA coverage for that product | Not all AppExchange products are BAA-eligible |
+ | PHI field change history beyond 18 months | Field Audit Trail with a `HistoryRetentionPolicy` | Standard history lasts 18 months (24 via API) |
+ | PHI in a long text field | Alternative evidence (versioned records, an audit object, or Event Monitoring) | Long text fields cannot be history-tracked |
+ | Access logs beyond one year | Export Event Log Files to an external store | One year of Event Log File storage by default |
+ | Turning on encryption after archiving | Plan re-encryption of archived history with Salesforce | Archived history stays unencrypted |
+ | PHI inventory upkeep | `complianceGroup` HIPAA on every PHI field | The tag travels with the field definition |
+ | BAA not yet signed | Do not store PHI | Contractual prerequisite (UNVERIFIED (2026-10-03): legal) |
---
## Recommended Workflow
- 1. **Verify BAA status** — confirm the Salesforce BAA is executed or in process. Document which products are BAA-covered. Flag any products or integrations that may not be covered.
- 2. **Complete PHI field inventory** — catalog all fields across all objects containing PHI using all 18 HIPAA identifier categories. This inventory drives all downstream security control configuration.
- 3. **Design access control model** — define user role taxonomy, set OWD to Private for all PHI-containing objects, design care team role-based sharing, and document the access matrix per role.
- 4. **Map HIPAA controls to Shield** — map each HIPAA Security Rule technical safeguard to a Shield component. Identify all PHI fields for encryption and Field Audit Trail coverage.
- 5. **Design Event Monitoring streaming** — identify the SIEM target, define log types to stream, design the streaming pipeline, and establish a 6-year retention policy.
- 6. **Produce implementation requirements specification** — document the HIPAA controls specification for the security implementation team, including the PHI field inventory, access matrix, audit trail scope, and SIEM streaming requirements.
+ 1. **Verify contractual prerequisites.** BAA status and covered services, confirmed by the account team and counsel.
+ 2. **Build the PHI field inventory as metadata.** Tag every PHI field with `complianceGroup` HIPAA and a `securityClassification`, and flag untrackable types.
+ 3. **Design access.** Private org-wide defaults, sharing per care relationship, and a field-level access matrix turned into permission sets.
+ 4. **Design field audit.** History on trackable PHI fields, Field Audit Trail policies with `archiveAfterMonths`, a deletion procedure, and alternatives for untrackable fields.
+ 5. **Design log retention.** Event Log File export before the one-year window, real-time streams if needed, and an external retention period from counsel.
+ 6. **Specify encryption order.** Enable Platform Encryption before history is archived, or plan re-archiving, and record which fields use which `encryptionScheme`.
---
## Review Checklist
- - [ ] BAA with Salesforce executed before any PHI is stored
- - [ ] All PHI-containing Salesforce products confirmed as BAA-covered
- - [ ] PHI field inventory completed (all 18 HIPAA identifier categories reviewed)
- - [ ] OWD-Private designed for all PHI-containing objects
- - [ ] Care team role-based sharing designed for minimum necessary access
- - [ ] Shield Field Audit Trail scoped for all PHI fields (NOT standard Field History Tracking)
- - [ ] Event Monitoring streaming to SIEM designed with 6-year retention policy
- - [ ] Shield Platform Encryption scoped for all PHI at-rest fields
+ - [ ] BAA status and covered services confirmed in writing
+ - [ ] Every PHI field tagged `complianceGroup` HIPAA with a `securityClassification`
+ - [ ] Untrackable PHI fields listed with alternative evidence
+ - [ ] Private org-wide defaults on PHI objects; sharing designed per care relationship
+ - [ ] Field access matrix implemented as role permission sets
+ - [ ] History tracking and Field Audit Trail policies defined, with a deletion procedure
+ - [ ] Event Log Files exported before the one-year window
+ - [ ] Encryption timeline aligned with history archiving
---
## Salesforce-Specific Gotchas
- 1. **Standard Field History Tracking does not meet HIPAA 6-year retention** — 18-month standard retention fails the audit log requirement. Shield Field Audit Trail (10 years) is required. This is the #1 HIPAA architectural mistake in Health Cloud implementations.
-
- 2. **Event Monitoring logs expire in 30 days** — without streaming to a SIEM, all access audit logs are permanently lost. This is an ongoing operational requirement, not a one-time setup step.
+ The deep versions, with sources, live in `references/gotchas.md`.
- 3. **BAA coverage is product-specific** — using PHI with an uncovered Salesforce product or AppExchange package breaks HIPAA coverage even with Shield enabled. Verify BAA coverage for every product and service that touches PHI.
+ | # | Gotcha | One-line consequence |
+ |---|---|---|
+ | 1 | History lasts 18 months without Field Audit Trail | Older PHI change evidence is gone |
+ | 2 | Long text, multi-select, and formula fields cannot be tracked | Clinical notes changes leave no history |
+ | 3 | Log retention differs by source: 1 year, 30 days, 3 days | Access evidence expires on different clocks |
+ | 4 | Archived history is not encrypted retroactively | Unencrypted PHI stays in the archive |
+ | 5 | Deleting a record does not delete its archived history | Archive needs its own deletion procedure |
+ | 6 | Field limits: 20 tracked fields, or 200 with Field Audit Trail | Large PHI objects exceed standard tracking |
+ | 7 | PHI tags live on the field definition | Untagged fields fall out of the inventory |
+ | 8 | Retention policy metadata has documentation conflicts | Hand-written policies may not deploy |
---
## Output Artifacts
| Artifact | Description |
|---|---|
- | PHI field inventory | Complete catalog of PHI fields across all org objects |
- | HIPAA controls specification | HIPAA Security Rule safeguard to Salesforce control mapping |
- | Access control matrix | Role-by-role PHI access requirements for OWD and permission set configuration |
- | Event Monitoring streaming requirements | SIEM target, log types, 6-year retention policy |
+ | PHI field inventory | Field metadata tagged with `complianceGroup` and `securityClassification` |
+ | HIPAA controls specification | Safeguard-to-control mapping with grounded platform facts |
+ | Access control matrix | Role-by-field access implemented as permission sets |
+ | Audit and log retention requirements | History policies, deletion procedure, Event Log File export, external retention |
---
## Related Skills
- - admin/health-cloud-patient-setup — PHI field configuration on patient records
- - admin/health-cloud-consent-management — HIPAA Privacy Rule consent controls
- - admin/hipaa-compliance-architecture — Full HIPAA compliance architecture design
+ - `admin/health-cloud-patient-setup`: PHI field configuration on patient records
+ - `admin/health-cloud-consent-management`: consent records and their history
+ - `architect/hipaa-compliance-architecture`: org-level HIPAA architecture and Shield configuration