Websockets

WebSockets provide a persistent, two-way connection between the user's browser and the server. ActiveManage uses them for everything real-time: chat messages, live notifications, presence indicators, collaborative edits, dashboard refreshes.

Why WebSockets

• Push, not pull: Server pushes events instantly; no polling delay.
• Bidirectional: Client can send commands too (e.g. typing indicator).
• Low overhead: Single long-lived connection vs many short-lived requests.
• Real-time UX: Chat that feels instant, notifications that arrive without refresh.

How the Platform Uses Them

• Chat: Message delivery, read receipts, typing indicators.
• Notifications: In-app notification badge updates.
• Collaboration: When multiple users edit the same record, changes broadcast to others' open sessions.
• Dashboards: Live-updating KPIs and charts.
• Activity feeds: New events appear without page reload.
• System alerts: Critical errors pushed to ops users.

Fallback to Polling

Some networks block WebSockets (corporate proxies, captive portals). The platform automatically falls back to long-polling or short-polling when the WebSocket fails to establish, so the user experience degrades gracefully.

Worked Examples

• Chat app: Two colleagues messaging — each typed character flows to the server and back as a typing-indicator event; each sent message arrives in under 100ms.
• Live ops dashboard: 24/7 status board with no refresh button — incident counts and queue lengths update in real time.
• Multi-user record edit: Sales rep is editing a customer record; another user opens the same record and sees a banner “Alice is also editing this”. As Alice saves, the other user's view auto-updates.
• Order-tracking page: Customer's order goes from “picked” to “packed” to “shipped” without them reloading.

“Channels” are the named streams that carry real-time events between the server and connected browsers. Subscribing to a channel is how a page receives the events relevant to it.

Channel Conventions

• user.{id} — events for a single user (own notifications, own DMs).
• tenant.{slug} — events visible to anyone in that tenant.
• group.{name} — events for a security group.
• record.{table}.{id} — changes to one specific record.
• thread.{id} — chat thread messages.
• dashboard.{id} — dashboard widget updates.
• system — platform-wide announcements (rare; admin only).

Subscription Process

1. Browser opens WebSocket to /ws with its session cookie.
2. Server authenticates the connection.
3. Browser sends subscribe commands for each channel it wants.
4. Server validates each subscription against the user's permissions; rejects unauthorised channels.
5. Server starts sending events on accepted channels.
6. Browser unsubscribes when navigating away.

Permission Enforcement

Every channel has an implicit permission check:

• user.{id} — only the user with that ID can subscribe.
• record.{table}.{id} — only users with view access to that record.
• tenant.{slug} — only users in that tenant.

Bypassing these checks is impossible — the server is the authority.

Worked Examples

• User opens app: Subscribes to user.{me} for notifications, tenant.{my_tenant}.activity for feed updates.
• User opens a customer record: Adds record.customers.{id} subscription; sees real-time edits from others.
• User opens chat: Subscribes to thread.{id} for the active thread.
• User opens dashboard: Subscribes to dashboard.{id} so live blocks update without reload.

Tip: Unsubscribe when leaving a page. Lingering subscriptions waste server resources and may deliver irrelevant events to stale UIs.