PSA/ee/docs/plans/2026-05-10-workflow-integration-modules-ninjaone/SCRATCHPAD.md

Scratchpad — Workflow Integration Modules: NinjaOne First Pass

• Plan slug: 2026-05-10-workflow-integration-modules-ninjaone
• Created: 2026-05-10

What This Is

Rolling notes for adding first-party workflow integration modules and the first NinjaOne workflow module/actions.

Decisions

• (2026-05-10) Use a first-party workflow integration module registry instead of only action-prefix grouping. Rationale: integrations need tenant availability, icon/logo metadata, default action, and future extensibility without hardcoding each integration into the generic designer.
• (2026-05-10) Define NinjaOne “in use” as an active rmm_integrations row with provider = 'ninjaone', is_active = true, and non-null connected_at.
• (2026-05-10) First pass will implement a mixed NinjaOne action set: find/list device, sync single device, reboot device, list active alerts, get alert, acknowledge alert.
• (2026-05-10) Do not add ninjaone.alerts.create_ticket. Users should chain NinjaOne alert outputs into the generic Ticket module (tickets.create, etc.). This keeps PSA ticket behavior generic and avoids duplicated ticket rules.
• (2026-05-10) Label ninjaone.alerts.reset as Acknowledge alert in the UI. The technical action ID can reflect the NinjaOne API reset operation, but users should see MSP/operator terminology.
• (2026-05-10) Any workflow editor can add/use NinjaOne workflow actions. No extra integration/action permission gate in this pass.

Discoveries / Constraints

• (2026-05-10) Review follow-up fixed package typecheck failures caused by Vitest vi.mock third-argument usage for @alga-psa/db/workDate; the package export exists, so the virtual flag was unnecessary.
• (2026-05-10) Review follow-up fixed NinjaOne handler guards: local device query no longer references nonexistent assets.hostname, alert DB reads/updates are scoped by integration_id, timestamp outputs are normalized to ISO strings, and device IDs are coerced/validated as positive integers before side-effect calls.
• (2026-05-10) Existing action catalog builder lives at shared/workflow/runtime/designer/actionCatalog.ts and already groups unknown action prefixes into tileKind: 'app' records.
• (2026-05-10) Existing designer catalog endpoint is backed by listWorkflowDesignerActionCatalogAction in ee/packages/workflows/src/actions/workflow-runtime-v2-actions.ts.
• (2026-05-10) Existing app filtering only checks enabled extension installs via tenant_extension_install and extension_registry; it does not handle first-party integration availability.
• (2026-05-10) Current Workflow Designer icon mapping lives in ee/server/src/components/workflow-designer/WorkflowDesigner.tsx in getPaletteIcon.
• (2026-05-10) NinjaOne integration code already exists under ee/server/src/lib/integrations/ninjaone/, including ninjaOneClient.ts, sync/syncEngine.ts, and alert/webhook handling.
• (2026-05-10) rmm_integrations schema includes provider, is_active, connected_at, instance_url, sync status fields, and tenant-scoped uniqueness on (tenant, provider).
• (2026-05-10) Temporal activities import workflow runtime from @alga-psa/workflows/runtime/core, so worker/runtime bootstrap must be considered carefully when adding EE/server-only NinjaOne registrations.

Commands / Runbooks

• (2026-05-10) Initial context commands used:
  • rg "WorkflowDesignerCatalog|actionCatalog|buildWorkflowDesignerActionCatalog|workflow module" -n server ee shared packages
  • rg "loadAvailableWorkflowDesignerAppKeys|availableAppKeys|integration" ee/packages/workflows/src/actions/workflow-runtime-v2-actions.ts server/src ee/server shared -n
  • rg "rmm_integrations|ninjaone|quickbooks|xero|email_providers|calendar_providers|microsoft_profiles" ee/server/migrations server/migrations packages -n
  • rg "NinjaOne|ninjaone|remote|device|alert|webhook|rmm" ee/server/src/lib/integrations/ninjaone packages/integrations/src/actions/integrations packages/integrations/src/lib/rmm -n

Links / References

• shared/workflow/runtime/registries/actionRegistry.ts
• shared/workflow/runtime/designer/actionCatalog.ts
• shared/workflow/runtime/init.ts
• ee/packages/workflows/src/runtime/bootstrap.ts
• ee/packages/workflows/src/runtime/worker.ts
• ee/packages/workflows/src/actions/workflow-runtime-v2-actions.ts
• server/src/app/api/workflow/registry/designer-catalog/route.ts
• ee/server/src/components/workflow-designer/WorkflowDesigner.tsx
• ee/server/src/components/workflow-designer/GroupedActionConfigSection.tsx
• server/migrations/20251124000001_create_rmm_integration_tables.cjs
• ee/server/src/lib/integrations/ninjaone/ninjaOneClient.ts
• ee/server/src/lib/integrations/ninjaone/sync/syncEngine.ts
• ee/server/src/lib/integrations/ninjaone/alerts/alertProcessor.ts

Open Questions

• Should the first pass render a true NinjaOne SVG/logo asset, or is a ninjaone icon token mapped in the existing palette sufficient?
• Should ninjaone.devices.find be local-only, live API-backed, or support both? Recommendation in PRD: local-first with optional live mode only if low risk.

Progress Updates

• (2026-05-10) Implemented first-party workflow integration module registry in shared/workflow/runtime/registries/integrationModuleRegistry.ts with duplicate-key protection and singleton accessor.

• (2026-05-10) Extended buildWorkflowDesignerActionCatalog to accept explicit first-party app module definitions and produce stable app records from declarative allowedActionIds.

• (2026-05-10) Added server-side first-party availability filtering keyed by availabilityKey in listWorkflowDesignerActionCatalogAction; preserved extension install filtering path.

• (2026-05-10) Registered app:ninjaone first-party workflow module in EE runtime core with icon token ninjaone, default action ninjaone.devices.find, and explicit six-action allow-list.

• (2026-05-10) Added six NinjaOne workflow actions in ee/packages/workflows/src/runtime/actions/registerNinjaOneWorkflowActions.ts:

  • ninjaone.devices.find
  • ninjaone.devices.sync
  • ninjaone.devices.reboot
  • ninjaone.alerts.list_active
  • ninjaone.alerts.get
  • ninjaone.alerts.reset (labelled Acknowledge alert)

• (2026-05-10) Handlers now fail fast for missing tenant and inactive integration, use engine-provided idempotency for side-effectful operations, and return normalized non-secret outputs.

• (2026-05-10) Mapped ninjaone icon token in Workflow Designer palette (WorkflowDesigner.tsx) for a distinct NinjaOne tile icon.

• (2026-05-10) Added registry pattern documentation for future integrations at ee/docs/plans/2026-05-10-workflow-integration-modules-ninjaone/INTEGRATION_MODULE_REGISTRY.md.

• (2026-05-10) Added/updated tests:

  • shared/workflow/runtime/__tests__/workflowIntegrationModuleRegistry.test.ts (duplicate-key + metadata roundtrip)
  • shared/workflow/runtime/__tests__/workflowDesignerActionCatalog.test.ts (explicit module record behavior)
  • ee/packages/workflows/src/actions/workflow-runtime-v2-designer-catalog.integration-filtering.test.ts:
    • T003 active NinjaOne tenant includes app:ninjaone in designer catalog
    • T004 inactive/missing NinjaOne excludes app:ninjaone
    • T005 extension app filtering still works with first-party filtering (app:acme.sync allowed when installed)
  • ee/packages/workflows/src/runtime/__tests__/ninjaOneWorkflowActions.registration.test.ts:
    • T006 verifies bootstrap and worker runtime entrypoints both register exactly the six NinjaOne action IDs
    • T007 verifies side-effect/idempotency metadata and ninjaone.alerts.reset UI label/description (Acknowledge alert)
    • T014 verifies NinjaOne registry action input/output schemas are present and parse representative action.call configuration payloads
  • ee/server/src/components/workflow-designer/__tests__/ninjaOneDesignerCatalog.contract.test.ts:
    • T015 verifies NinjaOne grouped action options and explicit ninjaone icon token mapping contract in WorkflowDesigner.tsx
    • T016 verifies NinjaOne module does not include ticket-creation actions and generic Ticket module remains the tickets.create path
  • ee/packages/workflows/src/runtime/actions/__tests__/ninjaOneWorkflowActions.handlers.test.ts:
    • T008 verifies ninjaone.devices.find happy path (local lookup) returns normalized device output and does not leak secret-like source fields
    • T009 verifies ninjaone.devices.sync delegates to sync strategy and returns synced identifiers
    • T010 verifies ninjaone.devices.reboot inactive-integration guard and successful reboot delegation
    • T011 verifies ninjaone.alerts.list_active output includes alert/device/asset/severity/message fields for ticket mappings
    • T012 verifies ninjaone.alerts.get happy path and not-found behavior
    • T013 verifies ninjaone.alerts.reset calls NinjaOne reset operation and returns acknowledged output

• (2026-05-10) Added targeted unit/integration-style coverage around listWorkflowDesignerActionCatalogAction filter behavior by mocking auth/runtime and exercising rmm_integrations plus extension-install query paths. Rationale: prove regression-safe catalog filtering without requiring full end-to-end server harness for this plan slice.

• (2026-05-10) Added runtime registration coverage using real runtime bootstrap/worker initialization and shared action registry reads. Included virtual test shim for @alga-psa/db/workDate to satisfy shared runtime import graph in package-level Vitest execution.

• (2026-05-10) Added handler-level test harness for NinjaOne actions with mocked integration client/sync strategy imports and action-registry invocation to validate output contracts directly at handler boundary.

Validation Runbook

• npx vitest run --config shared/vitest.config.ts shared/workflow/runtime/__tests__/workflowIntegrationModuleRegistry.test.ts shared/workflow/runtime/__tests__/workflowDesignerActionCatalog.test.ts
• npx tsc -p ee/packages/workflows/tsconfig.json --noEmit
• cd ee/packages/workflows && npx vitest run src/actions/workflow-runtime-v2-designer-catalog.integration-filtering.test.ts
• cd ee/packages/workflows && npx vitest run src/runtime/__tests__/ninjaOneWorkflowActions.registration.test.ts
• cd ee/packages/workflows && npx vitest run src/runtime/actions/__tests__/ninjaOneWorkflowActions.handlers.test.ts
• cd ee/server && npx vitest run src/components/workflow-designer/__tests__/ninjaOneDesignerCatalog.contract.test.ts

Gotchas

• Root vitest config does not discover ee/packages/workflows/src/runtime/__tests__ by default; shared runtime tests were executed via shared/vitest.config.ts.
• createNinjaOneClient second argument is region, not instance URL; workflow action handlers must call it with workflow context rather than raw URL.