Skip to content

README.md

Latest commit

 

History

History
213 lines (157 loc) · 8.79 KB

README.md

File metadata and controls

213 lines (157 loc) · 8.79 KB

n8n-nodes-halopsacomplete

An n8n community node for integrating with HaloPSA API.

Development

This repo uses pnpm with a committed lockfile and supply-chain controls in pnpm-workspace.yaml (see SECURITY.md). Development requires Node.js 22.22.3+ (CI and dependency engines). After clone:

corepack enable && corepack prepare pnpm@10.19.0 --activate
pnpm install --frozen-lockfile
pnpm run audit:supply-chain
pnpm run build

Use pnpm only for installs in this repo. With Corepack enabled, npm install and yarn install are rejected. Do not commit package-lock.json or yarn.lock (see SECURITY.md).

Testing locally

Unit tests (no HaloPSA credentials required):

pnpm test

Live n8n preview — runs n8n at http://localhost:5678 with this node linked for hot reload:

pnpm run dev

Use Node.js 22 LTS (nvm use reads .nvmrc). Node 23+ is not supported by n8n’s native dependencies.

First run takes several minutes. n8n-node dev downloads n8n via npx into ~/.n8n-node-cli. You will see many npm warn lines about peer dependencies — that is normal. Wait until the n8n panel shows:

Editor is now accessible via: http://localhost:5678

Do not stop the process during the install. If you see Shutting down gracefully with exit code 1, you likely interrupted it with Ctrl+C before n8n finished starting.

Prefer pnpm run dev over a globally installed n8n-node so the CLI version matches this repo.

Configure HaloPSA OAuth credentials in the n8n UI, then test Tickets → Get Many with filters and Return All enabled.

Open http://localhost:5678 (not 127.0.0.1 or a LAN IP). pnpm run dev sets N8N_SECURE_COOKIE=false for local HTTP so Safari and other browsers can sign in. To keep secure cookies enabled, set N8N_SECURE_COOKIE=true yourself and use HTTPS.

If the node does not appear after changes:

rm -rf ~/.n8n-node-cli/.n8n/custom
pnpm run dev

Already running n8n elsewhere (Docker, etc.):

pnpm run build
pnpm run dev:external

Set N8N_DEV_RELOAD=true and point your n8n instance’s custom extensions folder at ~/.n8n-node-cli/.n8n/custom (or symlink this repo into your instance’s custom nodes directory).

Use pnpm run watch for TypeScript watch mode only (no n8n).

Smoke test against a live HaloPSA instance (validates the tickets getAll filter + bulk-fetch query shape):

cp .env.example .env   # fill in HALO_BASE_URL, HALO_CLIENT_ID, HALO_CLIENT_SECRET
pnpm test:smoke

Optional: HALO_REQUESTTYPE_ID, HALO_OPEN_ONLY (see .env.example).

Live preview with n8n-node dev

Same as pnpm run dev above. Requires Node.js 22.22.3+ (22.x LTS recommended).

Installation

Follow the installation guide in the n8n community nodes documentation.

npm install n8n-nodes-halopsacomplete

Prerequisites

Setup

Setting up OAuth 2.0 in HaloPSA

  1. Log into your HaloPSA instance
  2. Navigate to Configuration > Integrations > HaloPSA API
  3. Create a new OAuth 2.0 Client Application
  4. Set the Grant Type to "Client Credentials"
  5. Configure the appropriate scopes (recommend "all" for full access)
  6. Note down the Client ID and Client Secret for use in n8n

Configuring Credentials in n8n

  1. Base API URL: Your HaloPSA instance URL (e.g., https://your-domain.halopsa.com)
  2. Client ID: OAuth 2.0 Client ID from HaloPSA
  3. Client Secret: OAuth 2.0 Client Secret from HaloPSA
  4. Scope: OAuth 2.0 scope (default: "all" for full API access)

Dynamic filters and options (expressions)

Operations that support Filters also expose Filters (JSON) for runtime values (e.g. {"client_id": {{ $json.client_id }}}). JSON keys override the same keys from the UI Filters collection.

Get by ID on Tickets, Users, Assets, Projects, and Ticket Statuses also support Options (JSON) with the same override behavior.

Use the JSON fields when driving values from webhooks, upstream nodes, or expressions; use the UI collections for static values.

Return All on list operations fetches up to 1000 rows in a single request, then continues with paginated requests (100 per page) when more records exist.

Supported Operations

Triggers

HaloPSA Trigger

Receive real-time webhook notifications from HaloPSA for ticket events:

  • New Ticket Logged — New ticket created
  • Ticket Updated by User — User updated a ticket
  • Closed — Ticket closed
  • 1st SLA Warning / 2nd SLA Warning — SLA breach warnings
  • Ticket Deadline — Ticket reached its deadline
  • Ticket Status Changed — Status changed
  • Ticket Deleted — Ticket deleted

The trigger creates and manages webhooks in HaloPSA (subscription and cleanup).

Resources (actions)

Resource Documentation
Action (ticket actions / notes) actions.md
Agent agents.md
Appointment appointments.md
Approval Process approval-processes.md
Approval Process Rule approval-process-rules.md
Asset assets.md
Attachment attachments.md
Automation automations.md
Canned Text canned-text.md
Category categories.md
Client clients.md
Contract contracts.md
Contract Rule contract-rules.md
Contract Schedule contract-schedules.md
Contract Schedule Plan contract-schedule-plans.md
Custom API Call custom-api.md
Feed feed.md
Field Info field-info.md
Holiday holidays.md
Invoice invoices.md
Invoice Payment invoice-payments.md
Item items.md
Notification notifications.md
Knowledge Base knowledge-base.md
Lookup lookups.md
Opportunity opportunities.md
Outcome outcomes.md
Product Branch product-branches.md
Product Component product-components.md
Project projects.md
Purchase Order purchase-orders.md
Quotation quotations.md
Raynet raynet.md
Raynet Details raynet-details.md
Recurring Invoice recurring-invoices.md
Release releases.md
Release Note Group release-note-groups.md
Reporting reporting.md
Sales Order sales-orders.md
Secure Secret Link secure-secret-links.md
Security Check security-checks.md
Site sites.md
Supplier suppliers.md
Survey surveys.md
Tag tags.md
Team teams.md
Top Level top-levels.md
Transcription transcription-store.md
Ticket tickets.md
Ticket Approval ticket-approvals.md
Ticket To-Do ticket-todos.md
To-Do Group todo-groups.md
Ticket Status ticket-statuses.md
Ticket Type ticket-types.md
Timesheet timesheet.md
Timesheet Event timesheet-event.md
User users.md
Webhook webhooks.md
Webhook Event webhookEvents.md

API paths not listed above can be called with Custom API Call. swagger.json at the repo root is the OpenAPI reference for discovering endpoints and payloads.

Resources

License

MIT