Skip to content

HaloPSA Setup ​

Junto connects to HaloPSA and HaloITSM to sync tickets, clients, contacts, and notes. Once connected, the AI agent can read ticket details, post notes, create and update tickets, and assign work — directly in Halo. Technicians can also open Junto inside a Halo ticket from a Junto tab.

The HaloPSA integration is in beta.

Prerequisites ​

  • A HaloPSA or HaloITSM instance reachable over HTTPS at a public hostname
  • A Halo administrator account that can open Configuration → Integrations
  • A Junto admin or owner account
  • Your instance URL as an origin only — for example https://acme.halopsa.com

Step 1: Create a Dedicated Junto Agent ​

In Halo, create an agent named Junto and use it for nothing else.

Assign the agent to every team you want Junto to manage. Junto only sees tickets on the teams its agent belongs to — a team left off is invisible to sync, triage, and the agent. Add new teams to the Junto agent as you create them.

Then open Configuration → Teams & Agents → Agents → Junto → Permissions and give it the Administrator role — or, at minimum, full Read and Modify access to the Tickets and Actions modules. To use the Junto ticket tab, the agent also needs permission to manage custom tabs and ticket types.

Everything Junto writes in Halo is attributed to this agent — notes, time entries, and status changes all show Junto as the author. Halo ties attribution to the API application's agent and offers no way to post as another technician.

Step 2: Create the API Application ​

  1. In Halo, go to Configuration → Integrations → HaloPSA API (labelled HaloITSM API on HaloITSM instances).

  2. Note the Resource Server URL — for example https://acme.haloitsm.com/api. Enter the origin of this URL in Junto, without the /api path. If a Tenant value is shown, note it too.

    HaloITSM API page showing the Resource Server URL, Authorisation Server URL, Tenant, and the View Applications button

  3. Click View Applications, then New.

  4. On the Details tab:

    SettingValue
    Application NameJunto
    ActiveChecked
    Authentication MethodClient ID and Secret (Services)
    Agent to log in asThe Junto agent from Step 1

    Add an Application Details tab with the name Junto, Active checked, and Client ID and Secret (Services) selected

  5. On the Permissions tab, check all and admin:webhooks. all is required. admin:webhooks lets Junto register its webhook for you — without it the connection still works, but you set the webhook up by hand.

    Add an Application Permissions tab with the all permission checked

    Can't see admin:webhooks? Uncheck all to reveal the full scope list, tick admin:webhooks, then tick all again.

  6. Click Save, then copy the Client ID and Client Secret. The secret is shown once — copy it before closing.

Step 3: Connect in Junto ​

  1. In Junto, go to Settings → Integrations → HaloPSA and click Connect HaloPSA.

  2. Fill in:

    FieldRequiredValue
    Instance URLYesOrigin only — https://acme.halopsa.com, not https://acme.halopsa.com/api
    Client IDYesFrom Step 2
    Client secretYesFrom Step 2
    TenantNoLeave blank. Fill in the tenant id from Step 2 only if the credentials are rejected

    Connect HaloPSA dialog with the instance URL, client ID, client secret, and optional tenant fields

  3. Click Connect, then Test connection on the card.

Test connection runs a checklist against your Halo instance and shows the result of each check:

CheckWhat it confirms
Data API tokenThe client ID and secret work, and Halo returns your agents
Webhook lifecycle tokenThe admin:webhooks scope is granted. A warning here only affects automatic webhook setup
Acting agentWhich Halo agent Junto writes as — this should be your Junto agent
Ticket picklistsStatuses, priorities, teams, and ticket types are readable
Default ticket categoryA category is available for tickets Junto creates — see Step 8
Note outcomesThe note outcome Junto uses exists in Halo
Customers and contactsClients and contacts are readable
Stored credentialsNo credential error is held for the connection
Webhook signing secretA secret is on file — see Step 4
Status mappingsHalo statuses are mapped — see Step 6
Technician mappingsJunto users are mapped to Halo agents — see Step 7

The card's badge reads Connected when the credentials work, Setup required when something needs fixing, and Disconnected after you disconnect.

Step 4: Set the Webhook Signing Secret ​

Junto registers the Halo webhook automatically. The signing secret has to be set by hand, in both places — pick any value and enter it twice:

  1. In Junto — on the HaloPSA card, click Set webhook secret, enter the value, and save.
  2. In Halo — go to Configuration → Integrations → Webhooks → junto-halo-webhook, enter the same value in Secret Key, and save.

Until both sides match, Junto ignores webhook deliveries and ticket changes arrive through the 15-minute sync instead of in seconds.

Webhook Status on the Card ​

StatusMeaning
Webhooks activeRegistered and a secret is on file
Action needed: set a webhook secretRegistered, but no secret on file — see above. The card also shows the webhook URL
Webhooks updating…A registration or removal pass is running
Webhooks failedThe card shows the reason — set the webhook up manually
Webhook registration is turned offDisabled for this Junto environment. Tickets sync every 15 minutes

Step 5: Run the Initial Sync ​

Click Sync now on the card. The first sync walks all clients and contacts, and tickets over a 90-day window, and fills in default status mappings. After that, Junto syncs every 15 minutes, and webhooks deliver changes in between.

Tickets imported by the first sync don't start triage — Junto doesn't triage your existing backlog. New tickets from then on do.

Step 6: Review Status Mappings ​

Junto maps each Halo status to a Junto status. The first sync fills these in by matching keywords in the status name.

  1. On the HaloPSA card, click Status mappings. The dialog lists your Halo statuses and how many are unmapped.
  2. Adjust any row, or click Auto-map statuses to have Junto suggest mappings. Tick Reassess existing mappings to re-suggest rows you already mapped, too.
  3. Click Save mappings. Nothing changes until you save.
Junto StatusHalo statuses mapped here by default
NewNew, Open, Unassigned, Draft — and any status that matches nothing else. Triggers intake processors (triage, priority, categorization, sentiment)
ActiveIn Progress, Assigned, Working, Active
WaitingWaiting, On Hold, Pending, Scheduled, With User, With Supplier, Awaiting …
ResolvedResolved, Complete, Completed, Done, Fixed — triggers resolution processors
ClosedClosed, Cancelled, Invoiced, Rejected — no processors run
ChildStatuses for tickets merged under a parent

Step 7: Map Members ​

  1. On the HaloPSA card, click Member mappings.
  2. Click Auto-map from Halo, then Auto-map users to confirm. Junto matches Junto users to Halo agents by email, then by name.
  3. Set any remaining rows from the Halo agent dropdown. Choose — Unmapped — to clear one.

Auto-map overwrites existing mappings, including ones set by hand, so it asks for confirmation first. Users whose Halo agent is already taken are skipped. Halo's Unassigned agent and disabled agents are never offered.

Mappings gate ticket assignment, approval routing, and signing in to the Junto tab without an email code. Sync, triage, note writing, and ticket creation work without them.

Step 8: Set the Default Ticket Category ​

Halo requires a category on every new ticket. Under Default ticket category on the card, choose the category Junto uses when it creates a ticket without a technician — for example, from a customer's email reply — and click Save category.

While no default is set, that unattended ticket creation is paused.

Step 9: Add the Junto Tab to Halo Tickets ​

Technicians can open Junto's triage for a ticket in a Junto tab on the ticket itself, without leaving Halo. This requires a paid Junto plan, and only Junto admins and owners can install the tab.

  1. On the Embed Junto in Halo tickets card, click Install tab.
  2. Junto creates the tab in Halo and adds it to every active ticket type.

The card shows Installed when the tab is in place. Needs update means the tab exists but is incomplete or out of date — click Update tab to repair it. Remove tab takes it out of Halo.

How Technicians Sign In ​

Technicians mapped to a Halo agent in Step 7 are signed in automatically from their Halo login. Anyone else signs in once with their Junto email and a 6-digit code, and stays signed in on that browser.

If the card says Techs sign in to this tab with an email code, the tab was added by hand or before automatic sign-in was available. Click Update tab to turn automatic sign-in on.

Adding the Tab by Hand ​

If Junto can't install the tab — usually because the Junto agent can't manage custom tabs — the card shows the tab URL instead:

  1. Copy the URL from the card.
  2. In Halo, go to Configuration → Custom Objects → Custom Tabs → Tickets → New.
  3. Set Type to Iframe, paste the URL, and save.

A tab added this way always signs technicians in with an email code.

Setting Up Webhooks Manually ​

Do this only if the card shows Webhooks failed, or if webhook registration is turned off for your environment.

Create the Webhook ​

In Halo, go to Configuration → Integrations → Webhooks and click New:

FieldValue
Namejunto-halo-webhook
ActiveChecked
URLCopy it from the HaloPSA card in Junto
MethodPOST
Content Typeapplication/json
Authentication TypeSign Request Body with a Secret Key
Authentication Headerx-halo-signature
AlgorithmSHA-256
Secret KeyThe value from Step 4

Add the Events ​

Add one subscription per row:

EventCriteria
New Ticket LoggedNone
Ticket Updated by UserNone
Ticket ChangedStatus → Value changed → To any value
Action added by agentOutcome: Note Added

Ticket Changed needs a criterion — Halo rejects it with "You must choose at least one criteria" if left blank.

Notes written in Halo under a custom outcome won't trigger an immediate delivery, but still reach Junto at the next 15-minute sync.

Check Deliveries ​

Halo's Deliveries view on the webhook lists every attempt with headers, body, and response status, kept for 30 days with a redeliver button per row.

Other Settings on the Card ​

  • Hidden companies — hide clients from the agent's searches and actions.
  • Edit credentials and Rotate client secret — update the connection without reconnecting.
  • Disconnect — pauses the connection and removes the Junto tab from Halo. Your mappings are kept for when you reconnect.
  • Delete — removes the connection, along with the Junto tab and webhook in Halo.

Catchall Ticket Routing ​

If email that doesn't match a known client lands on a catch-all client in Halo, the Catchall Ticket Router can sort it. For each new ticket on a client you mark as a catchall, the agent decides whether to close it as spam or noise, reassign it to the correct client (matching the sender's contact by email), or move it to the right team. It acts only when its confidence meets the processor's threshold, and every decision is recorded in Catchall Audit.

  • Closing sets the Halo status named under Fallback status name in the processor settings (Closed by default).
  • Moving to a team requires Auto-reassign to correct team and a description for each team the agent may route to. Halo unassigns a ticket's agent when its team changes.
  • These changes run without an approval card and are attributed to the Junto agent.

What the Agent Can Do ​

Routine work on the ticket in hand (internal and resolution notes, time entries, attachment uploads, and adding or completing checklist items) runs without an approval prompt by default; see Routine Ticket Work. All other write actions require technician approval before execution. Read-only tools do not require approval. Admins can change either setting per tool under Tool Policies.

Tickets — read and search tickets, create and update them, assign to agents, read and post notes (internal, resolution, and customer-facing), log time, read status options, read and update checklists, bundle and unbundle tickets, move a ticket to another client, and link it to a project.

Clients and contacts — read, search, create, and update clients and contacts, update client billing details, list sites and client alerts.

Scheduling — check agent availability, and book, list, read, and update appointments.

Attachments — list, read, and upload ticket attachments.

Assets — search, read, create, and update assets, link assets to tickets, list asset types and their fields.

Knowledge base — search, read, and create KB articles.

Contracts and billing — search and read contracts, check client entitlements, read ticket billing and invoices.

Catalog and procurement — search, read, and create catalog items, search and read purchase orders.

Projects — search, read, create, and update projects, create a project from a template, add project tasks, list project types, templates, and milestones.

Sales — search, create, and update opportunities, summarize the pipeline, search, read, create, and update quotes.

Time — search time entries and read time logged on a ticket.

Lookups — list agents, teams, categories, priorities, and statuses.

Notes and time entries post as the Junto agent from Step 1. Halo doesn't let an integration post as another technician.

Troubleshooting ​

  • "Halo rejected the client credentials" — Re-check the Client ID. If the secret wasn't captured at creation, generate a new one in Halo and use Rotate client secret on the card. On a shared-cloud instance, add the tenant id.
  • "Authenticated, but the API rejected the token (HTTP 401)" — Check Agent to log in as on the API application, and that the Junto agent is enabled.
  • "The API application is missing required scopes (HTTP 403)" — Grant all on the application's Permissions tab, and admin:webhooks for automatic webhook setup.
  • "Could not reach <host>" — Check the instance URL is the origin only, with no /api path, and that the host is publicly reachable.
  • Rate limit reached — Halo allows 700 requests per rolling 5 minutes. Wait and retry.
  • Tickets arrive slowly — The webhook secret isn't set on both sides. See Step 4.
  • Statuses behaving oddly — Review the status mappings in Step 6.
  • A team's tickets never appear — Add the Junto agent to that team in Halo. See Step 1.
  • Junto doesn't create tickets from customer emails — Set a default ticket category.
  • The Junto tab won't install — The Junto agent needs permission to manage custom tabs and ticket types. Grant it, or add the tab by hand.
  • Technicians are asked for an email code in the Junto tab — Map them to their Halo agent in Step 7. If the card says the tab uses email codes, click Update tab.