> ## 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. # Google Workspace Integration — Integration Contract > Version: 1.0.0 Last Updated: 2026-04-28 Spec: PF-101 Google Workspace Integration Status: Planned Constitution Reference: Section 1.3 (Integration Patterns), S… **Version:** 1.0.0\ **Last Updated:** 2026-04-28\ **Spec:** [PF-101 Google Workspace Integration](../../../specs/pf/specs/PF-101-google-workspace-integration.md)\ **Status:** Planned\ **Constitution Reference:** Section 1.3 (Integration Patterns), Section 4.2 (PHI/PII Handling), Section 5.7 (RLS) *** ## Overview PF-101 defines the tenant-level Google Workspace connector for Admin SDK Directory, Gmail, Calendar/Meet, Drive, Chat, License Manager, and Reports APIs. It consolidates the existing Gmail and Calendar paths into a governed PF integration layer, while HR, CE, PF-10, PF-11, and PF-86 remain consumers. *** ## Integration Points | Consumer | Pattern | Contract | | -------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------- | | HR-01 | Event | `hr_employee_created` and `hr_employee_terminated` drive Workspace provisioning and offboarding. | | HR-01 | API / event enhancement | Employee update sync uses an HR-01-approved update event or read-only lookup; no direct PF import from HR core code. | | CE-07 | Platform layer | CE email flows consume the PF Gmail sender wrapper. | | CE-21 | Platform layer | CE scheduling consumes PF Calendar/Meet wrappers. | | PF-10 | Platform layer / edge | Approved notification templates can route to Gmail or Google Chat. | | PF-11 | Platform layer | Drive mappings support external links/export/import while PF-11 remains canonical document storage. | | PF-86 | Platform layer | Email signatures render before Gmail send. | | PF-35 | Connector registry | Google Workspace appears in Integration Hub status and health surfaces. | | PF-76 | Credential reference | PF-101 stores only credential IDs for service account, OAuth, and webhook material. | *** ## Platform Layer Contract Planned package: `src/platform/integrations/google-workspace/` | API | Purpose | Notes | | ---------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `useGoogleWorkspaceConnection()` | Load current org connector state. | Query key includes `organization_id`; `staleTime` 5 minutes, `gcTime` 10 minutes. | | `useGoogleWorkspaceConnectionMutation()` | Create/update connector metadata. | All mutations enforce `organization_id`. | | `useGoogleWorkspaceCapabilityHealth()` | Load Directory/Gmail/Calendar/Drive/Chat/Licensing/Reports status. | Redacted health details only. | | `sendGoogleWorkspaceEmail()` | Shared Gmail send wrapper. | Applies sender allowlist, BAA gate, PF-86 signature, and redacted audit. | | `queryGoogleFreeBusy()` | Calendar free/busy wrapper. | Batches requests and handles partial failures. | | `createGoogleCalendarEvent()` | Calendar/Meet event creation. | Redacts PHI by default and generates unique Meet request IDs. | | `previewGoogleGroupSync()` | Group membership delta preview. | Required before bulk apply. | *** ## Event Contracts > **HR-01 publisher status (confirmed 2026-04-28):** `hr_employee_created`, `hr_employee_assigned_to_site`, and `hr_employee_terminated` are documented as published by HR-01 in [`HR-01-employee-directory-INTEGRATION.md`](./employee-directory-integration.md) §Events. The canonical-name registry rows for `hr_employee_created` and `hr_employee_assigned_to_site` are added to [`EVENT_CONTRACTS.md`](./EVENT_CONTRACTS.md) §HR Core Events alongside the existing `hr_employee_terminated` row. > > **PF-76 disambiguation:** "PF-76" in this document = **PF-76 Credential Vault** (`specs/pf/specs/PF-76-credential-vault.md`), not PF-76 React 19 Migration. > > **Cross-core column comment:** Migrations creating `pf_google_workspace_user_links.employee_id` MUST add `COMMENT ON COLUMN ... IS 'Cross-core reference to hr_employees.id (HR core); no FK; validated at application layer.'` per `database-patterns`. ### Consumed: `hr_employee_created` **Publisher:** HR-01\ **Subscriber:** PF-101\ **Purpose:** Provision or link a Google Workspace user when tenant policy enables account provisioning. Minimum payload: | Field | Type | Notes | | ----------------- | ----------- | ------------------------------------------------------ | | `event_type` | string | `hr_employee_created` | | `event_version` | string | Start at `1.0`. | | `organization_id` | uuid | Tenant scope. | | `employee_id` | uuid | HR employee UUID; stored as UUID reference without FK. | | `profile_id` | uuid | Optional user profile link. | | `department_id` | uuid | Optional mapping input. | | `position_id` | uuid | Optional mapping input. | | `hire_date` | timestamp | Provisioning policy input. | | `correlation_id` | string | Required for audit trace. | | `timestamp` | timestamptz | Event time. | ### Consumed: `hr_employee_assigned_to_site` **Publisher:** HR-01\ **Subscriber:** PF-101\ **Purpose:** Reconcile site-based group, org unit, Drive, Calendar resource, or Chat mappings when a tenant explicitly enables site mapping sync. Minimum payload: | Field | Type | Notes | | ----------------- | ----------- | ------------------------------ | | `event_type` | string | `hr_employee_assigned_to_site` | | `event_version` | string | Start at `1.0`. | | `organization_id` | uuid | Tenant scope. | | `employee_id` | uuid | HR employee UUID. | | `site_id` | uuid | PF site UUID. | | `assignment_date` | timestamp | Mapping effective date. | | `role` | string | Optional mapping input. | | `correlation_id` | string | Required for audit trace. | | `timestamp` | timestamptz | Event time. | ### Consumed: `hr_employee_terminated` **Publisher:** HR-01\ **Subscriber:** PF-101\ **Purpose:** Suspend/offboard linked Workspace user, revoke licenses, remove groups, and queue Drive transfer review. Minimum payload: | Field | Type | Notes | | -------------------- | ----------- | ------------------------------------------- | | `event_type` | string | `hr_employee_terminated` | | `event_version` | string | Start at `1.0`. | | `organization_id` | uuid | Tenant scope. | | `employee_id` | uuid | HR employee UUID. | | `termination_date` | timestamp | Offboarding policy input. | | `termination_reason` | string | Optional; do not log verbatim if sensitive. | | `correlation_id` | string | Required for audit trace. | | `timestamp` | timestamptz | Event time. | ### Published: `pf_google_workspace_user_provisioned` **Publisher:** PF-101 **Subscribers:** PF-10, HR status consumers **Purpose:** Signal successful Workspace user provisioning without exposing secrets or PHI. **Note:** Subscribers requiring the email address must perform scoped lookups using `google_user_id` or `profile_id`. | Field | Type | Notes | | ----------------- | ----------- | -------------------------------------- | | `event_type` | string | `pf_google_workspace_user_provisioned` | | `event_version` | string | `1.0` | | `organization_id` | uuid | Tenant scope. | | `employee_id` | uuid | Optional source reference. | | `profile_id` | uuid | Optional source reference. | | `google_user_id` | string | Provider ID. | | `correlation_id` | string | Required. | | `timestamp` | timestamptz | Event time. | ### Published: `pf_google_workspace_connector_degraded` **Publisher:** PF-101\ **Subscribers:** PF-10, PF-36\ **Purpose:** Alert admins when credential, scope, quota, BAA gate, or sync health degrades. | Field | Type | Notes | | ----------------- | ----------- | ----------------------------------------------------------------------------- | | `event_type` | string | `pf_google_workspace_connector_degraded` | | `event_version` | string | Start at `1.0`. | | `organization_id` | uuid | Tenant scope. | | `connection_id` | uuid | PF-101 connector. | | `capability` | string | `directory`, `gmail`, `calendar`, `drive`, `chat`, `licensing`, or `reports`. | | `reason_code` | string | Sanitized machine code. | | `correlation_id` | string | Required. | | `timestamp` | timestamptz | Event time. | *** ## Edge Function Contracts | Function | Authentication | Purpose | | ---------------------------------- | -------------------------------- | ----------------------------------------------------------------- | | `google-workspace-test-connection` | JWT + `pf.google_workspace.test` | Validate capability scopes and health. | | `google-workspace-directory-sync` | service role / scheduled | Batch Directory user/group/org unit sync. | | `google-workspace-provision-user` | event consumer + service role | Provision/link one Workspace user. | | `google-workspace-offboard-user` | event consumer + service role | Suspend user, revoke licenses, remove groups, queue Drive review. | | `google-workspace-gmail-send` | JWT + sender policy | Shared Gmail sender path. | | `google-workspace-calendar-sync` | JWT/service role | Calendar/Meet event sync and CE wrapper support. | | `google-workspace-drive-sync` | JWT/service role | Drive metadata and mapping sync. | | `google-workspace-reports-ingest` | service role / scheduled | Reports API audit ingestion. | | `google-workspace-chat-notify` | service role / PF-10 | Send approved notifications to Chat spaces. | All functions must use PF-76 credential retrieval, PF-42 rate limiting where applicable, sanitized errors, and correlation IDs. **Tenant-scoping contract:** Service-role edge functions (`google-workspace-directory-sync`, `google-workspace-provision-user`, `google-workspace-offboard-user`, `google-workspace-calendar-sync`, `google-workspace-drive-sync`, `google-workspace-reports-ingest`, `google-workspace-chat-notify`) MUST include explicit tenant-scoping filters on all queries against multi-tenant tables: * `.eq('organization_id', organizationId)` — REQUIRED on all multi-tenant table queries * `.eq('connection_id', connectionId)` — REQUIRED where applicable (connection-scoped resources) Implementation MUST include validation steps to assert the presence of these filters in all multi-tenant table queries. **Detailed API contracts** (endpoint, request/response schemas, error cases, tenant-scoping requirements) are documented in [API\_CONTRACTS.md §PF-101](./API_CONTRACTS.md#pf-101-google-workspace-integration-edge-functions). *** ## Security and Compliance * No PHI-capable Gmail, Calendar, Drive, Chat, or Meet operation may run unless `pf_google_workspace_connections.baa_attested_at` is set and tenant policy enables the capability. * Raw Google credentials, service account keys, OAuth client secrets, refresh tokens, and Pub/Sub webhook secrets remain in PF-76 only. * Domain-wide delegation scopes are versioned, reviewed, and tested per capability. * Restricted Google OAuth scopes require verification/security-assessment status tracking before production use. * Chat messages, calendar titles, logs, cache keys, and telemetry must not contain PHI/PII. *** ## Testing * Contract tests for each edge function with mocked Google API 200/401/403/429/5xx responses. * RLS tests for all PF-101 tables. * Integration tests for HR event consumption, Gmail send, Calendar free/busy/event, group sync preview, and Reports ingestion. * Manual setup wizard tests using non-PHI tenant data before production enablement.