ConnectWise PSA Connector — Documentation

What this connector does

• Watches the risks table for inserts and updates.
• Fires three event types: risk.created, risk.severity_changed, risk.status_changed.
• Posts a typed payload (risk code, title, severity, score, status, owner email, deep link back to RAIC) to the ConnectWise PSA connector project, which opens or updates a corresponding ticket.
• Each push carries an X-Idempotency-Key so retries never duplicate tickets.

Setup

1. In the ConnectWise PSA connector marketplace, generate an install for your RAIC tenant. The marketplace issues an Install ID and a one-time Secret Key.
2. Open /admin/integrations/connectwise-psa in RAIC.
3. Paste the Install ID and Secret Key, then click Link install.
4. Click Send test event to validate the path end-to-end.

Disable or re-link

Use the toggle on the panel to pause pushes without losing credentials. To rotate the secret, expand Re-link install, paste fresh credentials, and click Replace credentials. The old secret is overwritten in place.

Audit trail

Every successful push emits CONNECTOR_PUSH_SENT and every failure emits CONNECTOR_PUSH_FAILED to the Platform Activity Log, scoped to your organization. Failures also write to the platform error log with the upstream HTTP code and message.

Troubleshooting — Parked pushes & Reconnect required

When a push hits a terminal failure (5xx after retry exhaust, transport error, or auth-class 401/403), it is parked in the dead-letter queue and visible in the Parked Pushes (this install) panel at the bottom of /admin/integrations/connectwise-psa. Use the per-row Retry now button to re-fire the parked payload; on success the row is removed and a CONNECTOR_PUSH_RECOVERED audit is written.

If the ConnectWise PSA connector returns 401 or 403 (credentials revoked, install deleted, or secret rotated), RAIC emits CONNECTOR_INSTALL_AUTH_FAILED and a red Reconnect required banner appears at the top of this page. Open the Re-link install section, paste a fresh Install ID + Secret Key from the connector marketplace, click Replace credentials, then fire Send test event— a successful push clears both the banner and any parked auth-class rows on retry.

Platform operators get a cross-tenant view at /superadmin/engineering/connector-health.

Event subscriptions (per install)

By default, every install receives all nine RAIC event types: risk.created, risk.severity_changed, risk.status_changed, risk.owner_changed, risk.closed, control.failed, control.overdue, nc.opened, and nc.capa_overdue. Use the Event subscriptions card on /admin/integrations/connectwise-psa to narrow the event set or pause all events without disabling the install. The filter runs before the outbound HTTP call inside notify-connector-push, so unsubscribed events produce no CONNECTOR_PUSH_* rows and no parked dead-letter entries. Mutations record a CONNECTOR_INSTALL_TOGGLED audit row with the new subscribed_events_set value (ALL / NONE / comma-list).

Secret expiry & auto-retry

If you set a secret_expires_at on your install, RAIC sends 60/30/7/1-day warnings via the in-app bell + branded email and emits CONNECTOR_INSTALL_SECRET_EXPIRING. On the expiry day the install is auto-paused (enabled flipped to false) and CONNECTOR_INSTALL_SECRET_EXPIRED is emitted — re-link with fresh credentials to resume pushes. Server- and transport-class failures in the dead-letter queue are also auto-retried up to five times by a nightly cron; on the sixth failure CONNECTOR_PUSH_GIVEN_UP is written and the row stays in the DLQ until you click Retry now manually. Auth-class rows (401/403) are never auto-retried — fix credentials first.