PSA/docs/plans/2026-06-12-integration-workflow-modules/PRD.md

PRD: Integration Workflow Modules

• Status: Draft
• Owner: Robert Isaacs
• Created: 2026-06-12
• Design: ../2026-06-12-integration-workflow-modules-design.md (architecture authority)
• Branch: feature/integration-workflow-modules off main

1. Problem statement & user value

The workflow designer can host integration-specific "app" modules — palette tiles exposing an integration's operations as typed workflow actions, shown only when that integration is connected — but exactly one exists (NinjaOne, 6 actions), its availability check is a hardcoded if-chain, and its module wiring is inlined in core.ts. Meanwhile the operations MSPs actually orchestrate across tools (run a script on an endpoint, trigger an RMM automation, resolve a security incident, post to a Teams channel, put a technician on the schedule) are absent from the palette, so the "self-healing alert" loop the RMM alert events enable cannot be finished inside Alga.

This project generalizes the module plumbing so each integration is one self-contained registration, then ships four new modules (Tactical RMM, Level, Huntress, Microsoft Teams), expands NinjaOne with script execution, and adds a core scheduling.create_entry action. Incumbent PSAs offer no user-composable canvas over third-party tools; the market's answer is a separate $500–1,500/mo orchestration product. This puts it in the PSA.

2. Goals

• Adding integration #6 requires one file plus one core.ts line — no framework edits, no availability if-chain.
• A connected Tactical RMM tenant can run a stored script or raw command on an agent from a workflow and use its output in later steps.
• A connected Level tenant can trigger a Level automation (optionally scoped to specific devices) and check its run status.
• A connected Huntress tenant can enrich tickets from incident/agent/org data and resolve the Huntress incident when work completes.
• A tenant with the Teams app active can notify a user's activity feed, DM a user via the bot, and post to a channel where the app is installed.
• Workflows can create dispatch-board schedule entries that ride the existing calendar sync to a technician's connected external calendar.
• Palette tiles appear if and only if the integration is available for the tenant; NinjaOne behavior is unchanged (parity regression).

3. Non-goals

• QuickBooks Online / Stripe modules (financial follow-up, deliberately deferred), Tanium (pre-release).
• Email app tile (email.send already covers tenant-provider send) and a direct Calendar app tile (schedule-entry approach chosen instead).
• Huntress remediation approve/reject (sharp edge; revisit on demand).
• DB-backed module catalog or per-tenant module curation.
• Prebuilt workflow recipe gallery (launch follow-up, separate effort).
• New vendor capabilities beyond those listed (e.g. Tactical service control, NinjaOne patch apply).

4. Personas & primary flows

• Automation-minded MSP engineer: builds "disk-full self-remediation": RMM alert trigger → tacticalrmm.agents.run_script (cleanup script) → ticket note with output → levelio.alerts.resolve / alert reset → ticket closes. Builds "Huntress enrichment": ticket-created trigger → huntress.incidents.get + huntress.agents.get → ticket fields/note → on close, huntress.incidents.resolve.
• Dispatcher: escalation workflow posts to the service-desk Teams channel and creates a schedule entry for the on-call technician.
• Tenant admin: connects/disconnects integrations and sees palette tiles appear/disappear accordingly; no configuration beyond the integration itself.

5. Framework changes (build first)

5.1 Availability resolver registry

New registry in shared/workflow/runtime/registries/ (sibling of integrationModuleRegistry.ts): resolver type (knex, tenantId) => Promise<boolean> registered under a module's availabilityKey. loadAvailableFirstPartyIntegrationAppKeys (ee/packages/workflows/src/actions/workflow-runtime-v2-actions.ts) replaces its if-chain with registry lookups; a module whose key has no registered resolver is not available (fail closed). Resolver errors are caught and treated as unavailable (palette listing must not 500 because one vendor table is missing).

5.2 RMM availability factory

rmmIntegrationAvailability(provider) returns a resolver checking rmm_integrations for (tenant, provider) with is_active = true and connected_at IS NOT NULL — used by all four RMM modules.

5.3 One-call module registration + NinjaOne migration

registerIntegrationWorkflowModule({ module, availability, registerActions }) in ee/packages/workflows: registers actions, the module tile, and the availability resolver, idempotently. core.ts becomes one call per integration. NinjaOne migrates onto the helper and the RMM factory; the hardcoded 'rmm:ninjaone' branch is deleted. Regression bar: identical palette/catalog output for connected and disconnected NinjaOne tenants.

6. Modules

Conventions for every action: provider.noun.verb ID, Zod input/output schemas, ui: { label, description, category, icon }, correct sideEffectful, idempotency: { mode: 'engineProvided' }, handler errors thrown (engine normalizes). Vendor endpoint paths marked verify must be confirmed against vendor docs during implementation.

6.1 NinjaOne expansion (app:ninjaone)

FetchNinjaOneWorkflowClient gains runScript (POST /v2/device/{id}/script/run; type SCRIPT|ACTION, parameters, runAs) and a scripting-options discovery call (verify, expected GET /v2/device/{id}/scripting/options). New actions ninjaone.devices.run_script (side-effectful) and ninjaone.devices.scripting_options (read) join the existing six in allowedActionIds.

6.2 Tactical RMM (app:tacticalrmm)

Client: extend TacticalRmmClient (packages/integrations/src/lib/rmm/tacticalrmm/tacticalApiClient.ts) with agent-detail, script-list, run-script, run-command, reboot wrappers (verify paths: /scripts/, /agents/{agent_id}/runscript/, /agents/{agent_id}/cmd/, /agents/{agent_id}/reboot/). The workflows package takes a dependency on packages/integrations; runtime support resolves the integration row + tenant secrets (tacticalrmm_api_key or Knox trio) exactly as the existing sync path does.

Actions: agents.find, agents.get, scripts.list, agents.run_script (returns output), agents.run_command, agents.reboot (last three side-effectful).

6.3 Level (app:levelio)

Client: thin fetch client inside the workflows package (NinjaOne pattern — ee/server client not importable). Tenant secret levelio_api_key; cursor pagination as in the existing client.

Actions: devices.find, devices.get, alerts.list_active, alerts.resolve (side-effectful, POST /v2/alerts/{id}/resolve), updates.list, automations.list (automations + their webhook tokens), automations.trigger (side-effectful, POST /v2/automations/webhooks/{token} with optional device_ids[]; actionable error when the automation has no webhook trigger configured in Level), automations.run_status.

6.4 Huntress (app:huntress)

Client: thin fetch client in the workflows package; Basic auth from tenant secrets huntress_api_key/huntress_api_secret; replicate the 60 req/min throttle and 429 backoff of the ee/server client.

Actions: incidents.find, incidents.get, incidents.resolve (side-effectful; Huntress write API, verify exact endpoint), organizations.list, agents.get, account.get.

6.5 Microsoft Teams (app:teams)

Availability: own resolver — teams_integrations.install_status = 'active' AND the Teams add-on active for the tenant (mirror the delivery path's checks). The workflows package depends on ee/packages/microsoft-teams.

Actions (all side-effectful):

• teams.notify_user — Graph sendActivityNotification through the existing delivery path with a generic template; target is an Alga user with a linked Microsoft account; actionable error otherwise.
• teams.send_dm — proactive Bot Framework message (text + optional card) via stored teams_conversation_references; actionable error if the user has never opened the bot.
• teams.post_to_channel — requires new createConversation support in ee/packages/microsoft-teams (proactive channel conversation via Bot Framework; Graph app-only channel posting is Microsoft-protected, the bot route is deliberate). Works in any channel of a team where the Alga Teams app is installed; actionable error otherwise.

7. Core action: scheduling.create_entry

Shared (CE+EE) action in the scheduling.* business-operations family. Inputs: assigned user(s), title, start/end, optional ticket/project link, optional status/notes. Creates a dispatch-board schedule entry through the same model layer the UI uses; the existing calendar sync pushes it outward to a connected user calendar. Validation errors (unknown user, end before start) are explicit.

8. Designer surface

Icon tokens for tacticalrmm, levelio, huntress, teams added to the designer icon set, reusing the integration logos already shipped in the settings UI. Palette grouping/ordering verified for the new app:* groups (extend PALETTE_CATEGORY_ORDER handling only if required).

9. Error handling conventions

Handlers throw; the Temporal activity layer normalizes to the runtime error payload and stamps workflow_action_invocations FAILED. Vendor HTTP errors surface status + vendor message, never credentials. Most-common failures get explicit messages: integration not connected/inactive; Level automation lacks webhook trigger; Teams user unlinked / no bot conversation / app not in team. Side-effectful actions rely on engine-provided idempotency so retries are safe.

10. Testing & rollout

Unit: handler tests per integration with mocked clients (NinjaOne handler test pattern); availability-registry and resolver tests; helper idempotency; catalog gating matrix. Regression: NinjaOne palette parity. Manual smoke on the local-test stack: palette gating on connect/disconnect, Tactical mock run-script round-trip, Teams notify/DM/channel in a test tenant, schedule entry on the dispatch board. No migrations and no new tables; all gating is read-path, so rollout is inert until an integration is connected.

11. Editor behavior for disconnected integrations

Availability gates ADDING, not VIEWING. The designer catalog keeps first-party integration records when the integration is disconnected, flagged available: false; extension-app filtering is unchanged. The palette excludes unavailable records (the original hide-when-not-enabled decision stands). Existing steps referencing a disconnected integration keep full group context: the grouped action config section renders with an amber "not connected" banner naming the integration, the step card shows a "Disconnected" badge with an explanatory tooltip, and the input-mapping editor remains fully usable (it always resolved schemas from the unfiltered registry). Publish stays allowed; runs fail with the handlers' actionable INTEGRATION_INACTIVE errors. Publish-time and disconnect-time warnings were considered and deferred.