284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
48 lines
3.5 KiB
Markdown
48 lines
3.5 KiB
Markdown
# Calendar Sync Operations Runbook
|
||
|
||
This runbook covers the day-to-day operational tasks for the Google and Microsoft calendar integrations. It pairs with the UI updates delivered in Phase 4 so operators can onboard tenants, monitor sync health, and respond to incidents without engineering support.
|
||
|
||
## Prerequisites
|
||
- Tenants must configure vendor OAuth credentials via tenant secrets (same flow for hosted and on-prem deployments).
|
||
- Background jobs MUST be running so webhook renewals and delta token updates proceed automatically.
|
||
- Verify Redis and the `CALENDAR_OAUTH_ENCRYPTION_KEY`/`NEXTAUTH_SECRET` variables are present in the environment.
|
||
|
||
## Connecting A Provider
|
||
1. Navigate to **Settings → Calendar Integrations**.
|
||
2. Select either **Add Google Calendar** or **Add Outlook Calendar**.
|
||
3. For Google: ensure **Settings → Integrations → Providers** is configured first (tenant-owned OAuth client + redirect URI).
|
||
4. Complete the configuration form:
|
||
- Give the provider an operator-friendly name.
|
||
- Supply the external calendar identifier (use `primary` for the default Google calendar or `calendar` for Outlook).
|
||
- Choose the desired sync direction and enable the provider.
|
||
5. Press **Authorize**. A vendor popup appears; complete the OAuth consent flow.
|
||
6. After a successful callback you will see the `OAuth Complete` badge. Save the form to persist changes.
|
||
|
||
## Monitoring Sync Health
|
||
- Each provider card now shows **Connection Status**, **OAuth badge**, **Last Sync**, and **Sync Direction** at a glance.
|
||
- Trigger a manual sync with **Sync Now**. While the job executes the button displays `Syncing…` and a spinner badge appears.
|
||
- Successful runs emit a green confirmation banner; any issues surface as a red alert and the provider status flips to `Error` until the next healthy sync.
|
||
- Error text in the card mirrors backend status details, making it easy to copy into incident tickets.
|
||
|
||
## Conflict Handling
|
||
- When both systems edit the same entry the subscriber marks the mapping as `Conflict` and emits a notification event.
|
||
- UI surfaces show `Conflict` badges and direct users back to Calendar Settings to resolve.
|
||
- Operators should review the mapping, decide which side wins, and re-run the manual sync once conflict remediation is complete.
|
||
|
||
## Deleting A Provider
|
||
1. Select **Delete** in the provider card.
|
||
2. A confirmation dialog explains the blast radius (webhooks removed, sync halted). Confirm to proceed.
|
||
3. The provider is removed and a toast confirms success. Any scheduled jobs referencing the provider will skip automatically.
|
||
|
||
## Troubleshooting Checklist
|
||
- **Authorization failures**: ensure the OAuth popup is not blocked and that tenant secrets are valid.
|
||
- **Stale last sync**: run a manual sync to force a pass; if the timestamp does not advance check webhook subscriptions.
|
||
- **Webhook errors**: consult the `calendar-webhook-maintenance` job logs. Google uses Calendar “watch” channels (webhook) and Microsoft uses Graph subscriptions; both are renewed by maintenance jobs.
|
||
- **Multi-tenant bleed**: confirm the provider belongs to the active tenant. All actions enforce tenant scoping; mismatches result in `Forbidden` errors.
|
||
- **Conflicts stuck**: if repeated conflicts appear, reset the mapping’s `sync_status` through the conflict resolution workflow and retry.
|
||
|
||
## Escalation
|
||
- Pager duty rotation: **Platform Integrations**.
|
||
- Slack channel: `#calendar-sync-ops` (monitor for automated alerts from the webhook maintenance job).
|
||
- Include provider name, tenant, last sync timestamp, and any alert messages when escalating.
|