Halo Ticket Namer Setup Guide

halo-ticket-namer is a small open-source utility for MSP teams using HaloPSA. It listens for new-ticket webhooks, rewrites the subject into something a human can actually scan, and maps the ticket into a valid category_1 value.

That matters more than it sounds. Bad subjects make triage slower, queue views noisier, and reporting worse. If every inbound email lands as help or printer issue please call, your board becomes hard to manage fast. This tool fixes that at the point of intake.

If you want the bigger picture on why this kind of cleanup matters, read 5 Ways AI is Transforming MSPs. If you're already auto-creating tickets from security tooling, pair this with SonicWall's PSA integration with HaloPSA so the ticket arrives automatically and arrives with a usable title.

What the tool does

When Halo creates a new ticket, the webhook sends the payload to halo-ticket-namer. The service reads the ticket context, applies your naming rules, and updates two fields:

• the ticket summary
• category_1

You stay in control of the output. The project uses:

• RULES.md for naming logic and examples
• categories.json for the allowed category list

That keeps the automation constrained. The model is not inventing random categories or writing novels into the subject line. It is choosing from the categories you define and following the patterns you give it.

Before you start

Plan for three things before you deploy it:

1. A reachable webhook endpoint. Halo needs to call your service from the public internet or through a secure tunnel.
2. A category list you actually want. Bad categories in categories.json create bad outputs.
3. A few real ticket examples. Good examples in RULES.md make the naming far more consistent.

Recommended naming pattern:

[System/App] - [Short action-oriented problem]

Example:

• Outlook - Unable to send email
• QuickBooks - Multi-user mode not available
• Printer - Scan to email failing

Step 1: Clone the repository and install dependencies

Repository:

https://github.com/megalath/halo-ticket-namer

Clone it to the host where you want the service to run:

git clone https://github.com/megalath/halo-ticket-namer.git
cd halo-ticket-namer
npm install

If you prefer Docker, clone the repo anyway so you can edit RULES.md, categories.json, and .env locally before building or running the container.

Step 2: Create your environment file

Copy the sample environment file:

cp .env.example .env

Then set the required values:

HALO_BASE_URL=https://yourcompany.halopsa.com
HALO_AUTH_URL=https://yourcompany.halopsa.com/auth/token
HALO_CLIENT_ID=your-client-id
HALO_CLIENT_SECRET=your-client-secret
OPENAI_API_KEY=sk-...
WEBHOOK_SECRET=a-random-secret-string
PORT=3000
LOG_LEVEL=info

What each variable does

• HALO_BASE_URL: your HaloPSA tenant URL
• HALO_AUTH_URL: Halo auth endpoint used to request access tokens
• HALO_CLIENT_ID / HALO_CLIENT_SECRET: credentials from the Halo API application you create in the next step
• OPENAI_API_KEY: used to generate cleaner ticket summaries and category decisions
• WEBHOOK_SECRET: shared secret between Halo and this service
• PORT: local service port
• LOG_LEVEL: logging verbosity; info is a good default

Use a long random WEBHOOK_SECRET. Do not reuse another app secret, and do not commit .env into source control.

Step 3: Create a Halo API application

In HaloPSA:

1. Go to Configuration → Integrations → Halo API
2. Create a new API application
3. Copy the generated Client ID and Client Secret
4. Grant the app permission to read and update tickets

You do not need to overcomplicate the permission set. The service needs enough access to read the inbound ticket and update the subject/category fields. If your Halo permissions are locked down heavily, start with the minimum required scope and test against a non-critical queue first.

Sanity check the auth URL

Most Halo tenants use an auth URL that looks like this:

https://yourcompany.halopsa.com/auth/token

If your tenant uses a different host pattern, use the working auth endpoint from your existing Halo integrations. A wrong auth URL is one of the fastest ways to waste an hour on a setup that otherwise looks correct.

Step 4: Create the Halo webhook

In HaloPSA:

1. Go to Configuration → Integrations → Webhooks
2. Create a webhook for New Ticket Created
3. Set the URL to your deployed endpoint, for example:

https://your-server.example.com/webhook

4. Set the auth token to the same value as WEBHOOK_SECRET
5. Save the webhook

If you are testing locally, use a secure tunnel so Halo can reach your machine. Just make sure the public URL stays stable long enough to complete setup and validation.

Step 5: Define your naming rules and allowed categories

This is the step that decides whether the output is useful.

Configure RULES.md

Your rules file should be short, concrete, and example-heavy. The model follows examples closely, so give it realistic patterns from your own service desk.

Good guidance looks like this:

• Use [System/App] - [Issue]
• Prefer the affected application over vague user wording
• Keep the output under one line
• Remove filler like please help, urgent, or all-caps email subjects
• Normalize synonyms into your team's preferred vocabulary

Bad guidance is vague, like "make titles better." Be specific.

Configure categories.json

Only include categories that already exist in Halo as valid category_1 values. Exact spelling matters.

Example categories:

[
  "Email & Collaboration",
  "Line of Business Apps",
  "Printing",
  "Network",
  "Workstation",
  "Security"
]

If the tool writes a category name Halo does not recognize, the update will fail or produce inconsistent data. Keep this list tight.

Step 6: Start the service

For local development:

npm run dev

For a production-style Node run:

npm run build
npm start

For Docker:

docker compose up -d

Once the service is running, verify the health endpoint:

curl http://localhost:3000/health

Expected response:

{"ok": true}

If you do not get a healthy response, do not move on to webhook testing yet. Fix local startup first.

Step 7: Test with a real ticket

Create a low-risk test ticket in Halo with a messy subject such as:

user cant print to front office copier please call

Then confirm:

1. Halo sent the webhook successfully
2. The service logs show a clean request/response path
3. The ticket summary was updated to a readable format
4. category_1 changed to one of your allowed values

A good first-pass result is not perfection. You are looking for consistency and guardrails. After two or three test tickets, refine RULES.md with examples from anything the model handled awkwardly.

Troubleshooting

The webhook never arrives

Start with reachability:

• confirm the webhook URL is public and correct
• confirm Halo is using the New Ticket Created event
• confirm your firewall or reverse proxy is allowing the request through
• confirm the token in Halo matches WEBHOOK_SECRET

If you are tunneling a local service, remember that temporary tunnel URLs expire or change.

Authentication to Halo fails

Usually one of these is wrong:

• HALO_BASE_URL
• HALO_AUTH_URL
• HALO_CLIENT_ID
• HALO_CLIENT_SECRET

Copy them again carefully. Halo auth problems are usually configuration mistakes, not code problems.

Titles improve, but categories are inconsistent

That is usually a categories.json or RULES.md issue, not an infrastructure issue. Tighten the allowed categories, remove overlapping labels, and add clearer examples that map common ticket types to the exact category you want.

The output is too verbose

Add a rule that explicitly caps title length and forbids extra context unless it materially clarifies the issue.

For example:

• Good: Outlook - Unable to send email
• Too long: Outlook desktop on reception PC cannot send outbound messages after password reset

The tool keeps choosing the wrong system name

Feed it better examples from your own environment. If your users say "email" but your team wants every Microsoft 365 mail issue labeled as Outlook, say that directly in RULES.md and include examples.

Security and operations notes

Treat this like any other service that touches ticket data:

• store secrets in environment variables, not in the repo
• rotate WEBHOOK_SECRET if it is ever exposed
• avoid logging full ticket payloads in production
• keep the host patched if you are exposing it publicly
• test rule changes on a few tickets before rolling them into broad production use

If you want to see why noisy intake data quietly hurts margin later, MSP revenue leakage is the downstream version of this same problem.

When to use this tool vs build it into a broader workflow

Use Halo Ticket Namer when you need a lightweight way to standardize inbound ticket naming now.

Move to a broader workflow when you also want to:

• route tickets across multiple automations
• combine intake cleanup with alert-driven ticket creation
• feed normalized ticket data into reporting, quoting, or profitability workflows
• manage multiple PSA or distributor integrations from one system

That is the difference between a useful utility and an operating layer. The utility is still worth using. Just be clear on what it is supposed to solve.