PSA/ee/docs/plans/2026-02-16-n8n-ticket-node-crud/PRD.md

# PRD — Alga PSA n8n Ticket Node CRUD

- Slug: `n8n-ticket-node-crud`
- Date: `2026-02-16`
- Status: Draft

## Summary

Build and publish a new npm-distributed n8n community node package for Alga PSA with a single `Alga PSA` node that supports ticket CRUD, ticket comments, and helper lookup operations.

The v1 node will use one credential (`baseUrl` + `apiKey`) and expose:

- Ticket operations: Create, Get by ID, List, Search, Update, Update Status, Update Assignment, Delete, List Comments, Add Comment.
- Helper operations: List Clients, List Boards, List Statuses, List Priorities.
- Dynamic dropdowns for required ticket reference fields (`client_id`, `board_id`, `status_id`, `priority_id`) with manual UUID fallback.

## Problem

Alga PSA users who want automation in n8n currently need to use generic HTTP Request nodes, manually model request payloads, and discover IDs for required ticket fields. This is error-prone and slows down workflow creation.

## Goals

1. Provide a first-party-feeling `Alga PSA` n8n node for ticket CRUD operations.
2. Make the package installable by Alga PSA users via npm without requiring n8n community-portal verification.
3. Minimize setup friction with a single credential and dynamic lookup dropdowns.
4. Support real-world ticket workflow patterns by including status and assignment update operations.
5. Support common ticket collaboration workflows by allowing comment creation and comment retrieval on existing tickets.
6. Return predictable outputs for downstream n8n nodes, including delete behavior.

## Non-goals

- n8n trigger/webhook node support in v1.
- Public submission/verification to n8n community directory in v1.
- Full CRUD for non-ticket resources (clients/boards/statuses/priorities are read-only helpers in v1).
- OAuth2 credential flow in v1.
- Additional ticket-adjacent operations beyond list/add comments (comment update/delete, stats, from-asset) in v1.

## Users and Primary Flows

Primary users:

- MSP operators and automation engineers running self-hosted n8n.
- Alga PSA admins creating internal workflow automations.

Primary flows:

1. Install package from npm on self-hosted n8n and restart n8n.
2. Add `Alga PSA` credential (`baseUrl`, `apiKey`).
3. Build workflow with `Ticket -> Create` using dropdown-selected client/board/status/priority.
4. Build workflow with `Ticket -> List/Search` then branch to `Update Status` or `Update Assignment`.
5. Build workflow with `Ticket -> Add Comment` to append automation notes or customer-facing updates to an existing ticket.
6. Build workflow with `Ticket -> List Comments` to inspect or branch on ticket conversation history.
7. Build cleanup workflows using `Ticket -> Delete` with explicit output for downstream steps.

## UX / UI Notes

- One node name: `Alga PSA`.
- Resource-first UX: `Ticket`, `Client`, `Board`, `Status`, `Priority`.
- Operation list should only show operations valid for selected resource.
- Ticket create/update forms should prioritize commonly-used fields and group optional fields under additional options.
- Ticket comment operations should remain under the `Ticket` resource rather than introducing a separate comment resource.
- `Add Comment` should only expose fields that Alga PSA currently persists (`comment_text`, optional `is_internal`) and must not expose stale fields that are ignored server-side.
- Dropdown-backed fields must still allow manual UUID entry when lookup calls fail.
- Error messages should preserve Alga API details (`error.code`, `error.message`, `error.details`) in n8n-friendly format.

## Requirements

### Functional Requirements

1. Implement package scaffold compatible with n8n custom/community node loading conventions.
2. Implement credential type with fields:
   - `baseUrl`
   - `apiKey` (secret)
3. All requests must include `x-api-key` header and use configured `baseUrl`.
4. Implement `Ticket -> Create` mapped to `POST /api/v1/tickets`.
5. Implement `Ticket -> Get` mapped to `GET /api/v1/tickets/{id}`.
6. Implement `Ticket -> List` mapped to `GET /api/v1/tickets` with filters + pagination options.
7. Implement `Ticket -> Search` mapped to `GET /api/v1/tickets/search`.
8. Implement `Ticket -> Update` mapped to `PUT /api/v1/tickets/{id}` (partial payload support).
9. Implement `Ticket -> Update Status` mapped to `PUT /api/v1/tickets/{id}/status`.
10. Implement `Ticket -> Update Assignment` mapped to `PUT /api/v1/tickets/{id}/assignment`.
11. Implement `Ticket -> Delete` mapped to `DELETE /api/v1/tickets/{id}`.
12. Implement `Ticket -> List Comments` mapped to `GET /api/v1/tickets/{id}/comments`.
13. Implement `Ticket -> Add Comment` mapped to `POST /api/v1/tickets/{id}/comments`.
14. `Ticket -> Add Comment` must send `comment_text` and may optionally send `is_internal`.
15. `Ticket -> List Comments` must expose optional `limit`, `offset`, and `order` query parameters matching the existing API contract.
16. Do not expose `time_spent` in the n8n node because the current Alga PSA ticket comment implementation does not persist or consume it.
17. Implement helper resources:
  - `Client -> List` -> `GET /api/v1/clients`
  - `Board -> List` -> `GET /api/v1/boards`
  - `Status -> List` -> `GET /api/v1/statuses`
  - `Priority -> List` -> `GET /api/v1/priorities`
18. Implement dynamic load-options for `client_id`, `board_id`, `status_id`, `priority_id` in ticket create/update operations.
19. Implement manual UUID fallback entry when load-options cannot populate values.
20. Normalize outputs so successful operations provide usable JSON payloads and delete returns a non-empty success object.
21. Support n8n Continue On Fail behavior for item-level failures.

### Non-functional Requirements

- Use declarative-first node design where feasible; use programmatic logic only where needed for request/response shaping and load-options.
- Ensure compatibility with self-hosted n8n installation paths documented by n8n.
- Maintain readable, stable parameter naming aligned with Alga API payload fields.
- Keep scope to core functionality only; exclude observability/metrics hardening unless later requested.

## Data / API / Integrations

Alga API dependencies (existing in this repo):

- Ticket routes:
  - `GET /api/v1/tickets`
  - `POST /api/v1/tickets`
  - `GET /api/v1/tickets/{id}`
  - `PUT /api/v1/tickets/{id}`
  - `DELETE /api/v1/tickets/{id}`
  - `GET /api/v1/tickets/search`
  - `PUT /api/v1/tickets/{id}/status`
  - `PUT /api/v1/tickets/{id}/assignment`
  - `GET /api/v1/tickets/{id}/comments`
  - `POST /api/v1/tickets/{id}/comments`
- Lookup routes:
  - `GET /api/v1/clients`
  - `GET /api/v1/boards`
  - `GET /api/v1/statuses`
  - `GET /api/v1/priorities`

Known ticket create requirements:

- Required: `title`, `client_id`, `board_id`, `status_id`, `priority_id`.
- Optional include: `location_id`, `contact_name_id`, `category_id`, `subcategory_id`, `assigned_to`, `url`, `attributes`, `tags`.

Known ticket comment requirements:

- `POST /api/v1/tickets/{id}/comments` accepts `comment_text` and optional `is_internal`.
- The API schema currently mentions `time_spent`, but the ticket comment service and `comments` table do not persist or use it; the n8n node should not expose it.
- `GET /api/v1/tickets/{id}/comments` supports optional `limit`, `offset`, and `order`.

Auth model:

- Required header: `x-api-key`.
- `x-tenant-id` is not part of v1 credential UX and is omitted unless required by future tenant-routing changes.

## Security / Permissions

- API key is stored via n8n credential secrets, not plain text node parameters.
- Node must surface auth and RBAC failures clearly:
  - `401` invalid/missing key
  - `403` key user lacks permissions
- Node must not log raw API key values.

## Observability

- v1 scope is limited to node-level error surfaces in n8n executions.
- No additional telemetry/metrics/logging features are included in this plan.

## Rollout / Migration

1. Build and publish npm package under valid n8n naming rules (`n8n-nodes-*` or `@org/n8n-nodes-*`).
2. Document installation options for self-hosted n8n (GUI npm install, manual CLI install).
3. Document that unverified community nodes are self-hosted only and not available on n8n Cloud.
4. Provide a minimal release note and upgrade guidance for future versions.

## Open Questions

1. Final npm package name/scope (`n8n-nodes-alga-psa` vs scoped org package) for best discoverability.
2. Exact minimum n8n version we will officially support in README.
3. Whether to include optional `x-tenant-id` credential field in v1.1 if users report tenant routing ambiguity.

## Acceptance Criteria (Definition of Done)

1. Package can be installed from npm into a self-hosted n8n instance and node appears in UI.
2. Credential setup requires only `baseUrl` and `apiKey` and authenticates against Alga APIs.
3. Ticket CRUD operations execute successfully end-to-end against Alga APIs.
4. Ticket list/search operations return structured outputs usable by downstream n8n nodes.
5. Required ticket reference fields are selectable via dynamic dropdowns with manual UUID fallback.
6. Helper list operations for clients/boards/statuses/priorities are available and functional.
7. Ticket comment list/add operations execute successfully against the existing Alga PSA ticket comment APIs.
8. `Add Comment` only exposes fields backed by current Alga PSA behavior and does not present unsupported `time_spent` UI.
9. Error handling exposes actionable API error details in n8n execution output.
10. Delete operation returns a usable success payload for downstream workflow steps.
11. README includes installation and usage guidance for Alga users, including self-hosted limitation notes.