PSA/packages/n8n-nodes-alga-psa/README.md

n8n-nodes-alga-psa

Alga PSA community node package for self-hosted n8n instances.

What This Package Provides

This package adds one node to n8n:

• Node name: Alga PSA
• Credential: Alga PSA API
• Resources:
  • Ticket
  • Contact
  • Project Task
  • Client
  • Board
  • Status
  • Priority

Requirements

• Self-hosted n8n (community nodes are not available on n8n Cloud when unverified)
• Alga PSA API access with an API key

Installation

Option 1: n8n UI (Self-Hosted)

1. Open your n8n instance.
2. Go to Settings -> Community Nodes.
3. Install package: n8n-nodes-alga-psa.
4. Restart n8n if prompted.

Option 2: Manual npm Install (Self-Hosted)

Install in the n8n environment where your instance runs:

npm install n8n-nodes-alga-psa

Then restart n8n.

For manual/custom installation paths, follow n8n's manual community-node installation guidance for your deployment type.

Credential Setup

Create credential type Alga PSA API with:

• Base URL example: https://algapsa.com
• API Key your Alga PSA key (sent as x-api-key header)
• Field names in node credentials: baseUrl, apiKey

Operation Matrix

Resource	Operations
Ticket	Create, Get, List, List Comments, Search, Update, Add Comment, Update Status, Update Assignment, Delete
Contact	Create, Get, List, Update, Delete
Project Task	Create, Get, List, Update, Delete
Client	List
Board	List
Status	List
Priority	List

Ticket Field Requirements

Ticket create requires:

• title
• client_id
• board_id
• status_id
• priority_id

Create/Update optional fields are grouped under additional options.

Contact Field Requirements

Contact create requires:

• full_name

Contact create/update optional fields:

• email
• primary_email_canonical_type
• primary_email_custom_type
• additional_email_addresses
• client_id
• role
• notes
• is_inactive
• phone_numbers

Contact list supports:

• Page
• Limit
• client_id
• search_term
• is_inactive

phone_numbers is authored as JSON in the first pass and must be an array of objects with a required phone_number field.

additional_email_addresses is authored as JSON and should be an array of objects with a required email_address field plus optional canonical_type, custom_type, and display_order.

Use primary_email_canonical_type for canonical labels such as work, personal, billing, or other. Use primary_email_custom_type when you need a freeform primary label instead.

Project Task Field Requirements

Project Task create requires:

• task_name
• Project ID (resource locator with search or manual UUID)
• Phase ID (within the selected project)
• Status Mapping ID (project-specific task status mapping)

Project Task create/update optional fields:

• description
• assigned_to (user UUID)
• estimated_hours
• due_date (ISO date/time string)
• priority_id
• task_type_key (server defaults to general)
• wbs_code
• tags (comma-separated)
• Update also accepts task_name and project_status_mapping_id in its collection

Project Task list requires a Project ID and supports Page and Limit. The server returns all tasks for the selected project; filter downstream if you need phase-level slicing. Get, Update, and Delete operate on a task UUID regardless of project.

Status Mapping IDs are project-specific. Use the Status Mapping ID lookup after selecting a project, or fetch candidates via GET /api/v1/projects/{id}/task-status-mappings.

Ticket Comment Operations

Ticket comment support stays under the Ticket resource:

• List Comments requires ticketId and supports optional limit, offset, and order.
• Add Comment requires ticketId and comment_text, with optional is_internal.
• time_spent is intentionally not exposed because the current Alga PSA ticket comment implementation does not persist or use it.

Lookup Fields and Manual Fallback

For ticket client_id, board_id, status_id, and priority_id, plus contact client_id:

• Use dynamic list lookups (From List) when available.
• Use manual UUID input (By ID) if lookups fail or if you already know the ID.

Board-Scoped Ticket Statuses

Ticket statuses in Alga PSA are owned by a board. This changes how ticket status lookups work:

• Ticket -> Create: the Status ID dropdown is filtered by the selected Board ID. Pick the board first.
• Ticket -> Update: when changing status_id inside the update fields, also include board_id (destination board) so the status dropdown can list valid options. A status is only valid for the ticket's current or updated board.
• Ticket -> Update Status: use the optional Board ID (for Status Picker) field to filter the Status ID dropdown to the ticket's board. The value is not sent in the request — the server validates against the ticket's existing board. Manual UUID entry still works without this helper.
• Status -> List with type Ticket requires a Board ID. Use type Project, Project Task, or Interaction for tenant-wide (non-board-owned) statuses.

Output and Error Behavior

• API responses unwrap { data: ... } for easier downstream use.
• Paginated list responses, including Contact -> List, preserve pagination metadata.
• Delete, including Contact -> Delete, returns a non-empty success object containing success, id, and deleted.
• Continue On Fail is supported with item-level error objects containing error.code, error.message, and error.details when available.

Example Workflows

Four minimal importable examples are included:

• examples/create-update-assignment.workflow.json
• examples/search-update-status.workflow.json
• examples/add-comment-then-list-comments.workflow.json
• examples/create-update-contact.workflow.json

These demonstrate:

1. Ticket create -> update assignment
2. Ticket search -> update status
3. Ticket add comment -> list comments
4. Contact create -> update