> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CL–HR: Provider Productivity Analytics Integration

> Status: 📝 Planned Created: 2026-03-02 Source: specs/cl/CL-STRATEGIC-ROADMAP-20260302.md Constitution Reference: Section 1.3 (Integration Patterns); no direct…

**Status:** 📝 Planned\
**Created:** 2026-03-02\
**Source:** [specs/cl/CL-STRATEGIC-ROADMAP-20260302.md](../../../specs/cl/CL-STRATEGIC-ROADMAP-20260302.md)\
**Constitution Reference:** Section 1.3 (Integration Patterns); no direct core-to-core imports.

***

## Purpose

Clinical supervisors and HR workforce planners need provider-level productivity metrics: notes completed per week, documentation timeliness (binned/rounded intervals — e.g. \<24h, 24–48h, >48h), active caseload (aggregated to non-clinical buckets where needed), no-show rates, and session volume by category. This data exists in CL (e.g. CL-04 note metadata, PM scheduling) but HR has no access layer. This contract defines a **read-only** platform layer so HR can consume aggregate productivity data without direct CL/PM table access and without PHI (only aggregate counts and timeliness metrics). **Privacy controls:** Minimum-threshold suppression — do not publish provider metrics for providers with \<5 patients in the period. Remove or aggregate "active caseload by severity" to a higher-level bucket to avoid re-identification. A privacy impact assessment is required; specify de-identification approach (HIPAA Safe Harbor or Expert Determination). For behavioral health data, 42 CFR Part 2 review is required before release.

**Tracked compliance actions (link from this doc):**

1. **PIA-CL-HR-01** — Privacy Impact Assessment (PIA) for provider productivity metrics. *Owner:* Compliance/Privacy Officer. *Due:* Before first production release. *Acceptance criteria:* PIA document completed; risks and mitigations documented; approved by designated authority.
2. **PIA-CL-HR-02** — Select de-identification method (HIPAA Safe Harbor vs. Expert Determination). *Owner:* Compliance/Privacy Officer. *Due:* Before first production release. *Acceptance criteria:* Method selected and documented; applied to provider productivity outputs.
3. **PIA-CL-HR-03** — 42 CFR Part 2 legal review for behavioral health workforce metrics. *Owner:* Legal/Compliance. *Due:* Before release of metrics that could identify SUD/MH treatment. *Acceptance criteria:* Legal opinion or checklist completed; disclosure/consent requirements documented.
4. **PIA-CL-HR-04** — Document results in a compliance artifact and link it from this integration doc. *Owner:* Compliance. *Due:* With PIA completion. *Acceptance criteria:* Artifact (e.g. PIA document, compliance checklist) stored in repo or designated location; this integration doc updated with permalink.

**Regulatory driver:** AZDHS facility staffing standards; AHCCCS contract staffing requirements; CARF HR standards (§§5.A–5.B).

***

## Integration Type

* **Platform layer (read-only):** CL (and optionally PM) expose a provider productivity summary view or API consumed by HR.
* **No events required:** HR can query on demand (e.g. dashboard load) or via scheduled report.

***

## Platform Integration Layer

### API / View: provider\_productivity\_summary

**Provider:** CL (and PM for scheduling data if needed) via Platform Integration Layer\
**Consumer:** HR\
**Status:** 📝 Planned

#### Purpose

HR needs read-only access to aggregate provider productivity metrics: note count per provider per period, average documentation lag (session end to note signed), active caseload count, no-show count/rate, session count by service type. No PHI—only provider\_id, org\_id, site\_id, and aggregates.

#### Contract

* **Location:** `@/platform/workforce` — chosen as the canonical module for provider productivity and other workforce metrics (multi-metric pattern). See [PLATFORM\_INTEGRATION\_LAYERS.md](PLATFORM_INTEGRATION_LAYERS.md) for integration guidance.
* **Function/hook:** e.g. `getProviderProductivity(organizationId, options?: { siteId?, providerId?, periodStart, periodEnd }): Promise<ProviderProductivitySummary[]>`.
* **Return shape (conceptual):**\
  `{ provider_id, site_id, organization_id, period_start, period_end, notes_completed_count, avg_documentation_lag_hours, active_caseload_count, no_show_count, no_show_rate, session_count_by_category?: Record<string, number> }`.\
  Use non-clinical category buckets (e.g. "Individual Therapy", "Group Services", "Case Management"); only include a category if count ≥ 5 (minimum-threshold suppression).
* **Security:** Organization-scoped; caller must have HR role or permission to view productivity. Use a **SECURITY DEFINER** function that performs server-side aggregation and returns only non-PHI aggregates. RLS alone is insufficient — SECURITY DEFINER ensures aggregation logic runs with elevated privileges to read CL/PM data while returning only aggregated, non-PHI results to the caller.

#### Data Sources

* **CL-04:** Note finalized timestamps, session dates, provider (created\_by or assigned clinician).
* **PM-03 (scheduling):** See [PM-03-appointment-scheduling-INTEGRATION.md](appointment-scheduling-integration.md) (or PM-03 spec). Consumed fields: `pm_appointments.status` → appointment status; `pm_encounters` or `pm_appointments.attendance_flag` → no-show indicator; `pm_appointments.service_type` → service type. These feed CL-04 provider productivity metrics (finalized timestamps, session dates, created\_by/assigned clinician, caseload). Access is abstracted via `getProviderProductivity()` in the Platform Integration Layer.
* Caseload: count of distinct patients with activity in period (from CL chart or encounter).

***

## Implementation Notes

* **Preferred approach:** Implement a **SECURITY DEFINER** SQL function (e.g. `get_provider_productivity(period_start, period_end, org_id, site_id)`) that performs server-side aggregation and parameter validation for dynamic period filtering and real-time results. **Alternative:** A materialized view is only for use cases with fixed pre-defined periods and strict performance needs (with scheduled refreshes). Trade-offs: real-time vs refresh latency, security boundaries, and encapsulation — the RPC approach is preferred for this integration.
* **Platform layer:** Expose `getProviderProductivity()` in `@/platform/workforce`; HR imports from platform only.
* **HR side:** Call platform API from HR dashboard or report; no direct CL/PM imports.

***

## Testing Requirements

* [ ] getProviderProductivity returns only org-scoped data; no PHI in response

* [ ] Aggregates match source data (note count, lag, caseload)

* [ ] Tenant A cannot see Tenant B’s productivity

* [ ] **Small-n suppression:** Providers with \<5 patients in period are suppressed or aggregated

* [ ] **Service-type sensitivity:** session\_count\_by\_category uses non-clinical buckets; no raw service-type granularity that could leak behavioral-health details

* [ ] **Documentation-lag:** Documentation lag metric does not correlate to identifiable sessions in output

* [ ] **Permission boundary:** Unauthorized roles cannot call getProviderProductivity

* [ ] **Cross-site isolation:** Site A cannot see Site B productivity even within same org (when siteId filter applied)

* [ ] **Parameter injection:** Fuzzing for periodStart/periodEnd/providerId (SQL-injection resistance)

* [ ] **Performance:** Response \<2s for \~50 providers (benchmark)

* [ ] **Data lineage:** Aggregates traceable to CL-04 notes and PM appointments

* [ ] **Audit logging:** Every access records caller identity and context

***

## References

* [CL-04-progress-notes-session-documentation-INTEGRATION.md](progress-notes-session-documentation-integration.md)
* [PLATFORM\_INTEGRATION\_LAYERS.md](PLATFORM_INTEGRATION_LAYERS.md)
* [CROSS\_CORE\_INTEGRATIONS.md](CROSS_CORE_INTEGRATIONS.md)
* specs/cl/CL-STRATEGIC-ROADMAP-20260302.md