Description
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 N8NSECURECOOKIE=false for local HTTP so Safari and other browsers can sign in. To keep secure cookies enabled, set N8NSECURECOOKIE=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 N8NDEVRELOAD=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 HALOBASEURL, HALOCLIENTID, HALOCLIENTSECRET
pnpm test:smoke
Optional: HALOREQUESTTYPEID, HALOOPENONLY (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
- HaloPSA instance with API access
- OAuth 2.0 Client ID and Client Secret from HaloPSA
- Your HaloPSA base URL (e.g., https://your-domain.halopsa.com)
- 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
- HaloPSA API Documentation
- n8n Documentation
- Repository
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. {"clientid": {{ $json.clientid }}}). 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:
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
