HaloPSA integration

What it does

The HaloPSA integration connects your xClause account to your Halo instance using a Halo API application (Client ID and Client Secret).

Creates an opportunity in Halo when you create a contract. When an MSA or SOW is created in xClause for one of your clients, xClause finds the client in Halo by name, or creates it if it does not exist. It then creates an opportunity for the contract and tries to create a linked quotation. The same happens when a SOW is submitted, when a SOW is created by a workflow, and when a SOW is built through quick start.
Closes the Halo record when the contract is fully signed. When a SOW is signed and its linked MSA is already signed, or an MSA is signed and a linked SOW is already signed, xClause sets the status of the stored Halo record to Closed.
Syncs existing contracts on demand. The Sync all contracts button creates Halo opportunities for contracts that do not have one yet.
Shows Halo data inside xClause. The Data management tab lists your Halo clients, opportunities, and invoices (read-only).
Links Halo items to xClause products. The Halo item catalog is available when you link products and when you import line items into a SOW.
Reads recurring invoice lines nightly to record contracted license quantities from Halo.

If a Halo call fails during contract creation or signing, the contract is still created or signed. The Halo failure is not shown to the user, so check Halo after creating a contract if you rely on the opportunity being there.

Before you start

In xClause

The Integrations page is not available on the MSP Starter plan unless your account has been given integrations access. If you are on that plan, opening Settings > Integrations sends you to the billing page with an upgrade prompt.
You must be signed in as a user who belongs to your MSP company. The connect action checks company membership only. It does not check for an admin role.

In Halo

A Halo instance you can sign in to as an administrator.
A Halo API application that uses Client ID and Secret (Services) authentication, with Login Type Agent and an API-only agent assigned. See step 3 below.
The API application's permissions must cover the areas in the permissions table below.

Your Halo URL must be reachable over HTTPS on the standard port (443), by host name. xClause refuses IP addresses, local or internal addresses, and plain http://.

Connect

HaloPSA lives in two places:

Settings > Integrations, on the Halo PSA tile (category PSA & RMM).
The dedicated page at /integrations/halo, which has three tabs: Connection settings, Data management, and Testing & debug.

To connect:

In Halo, go to Configuration > Integrations > HaloPSA API and create a new API Application.
Select Client ID and Secret (Services) as the Authentication Method.
Set Login Type to Agent and select your API-only agent.
Copy the Client ID and Client Secret. Halo shows the secret only once.
In Halo, open API Details on the same page and copy the Resource Server (for example https://yourcompany.halopsa.com/api). Use your agents' login address, not your customer portal.
In xClause, open the Halo PSA integration and click Connect to Halo PSA.

Fill in the fields (all are required):

Field	What to enter
Client ID	The Client ID from step 4.
Client Secret	The Client Secret from step 4.
Halo URL	Either your subdomain on its own (for example `yourcompany`, which xClause treats as `yourcompany.halopsa.com`) or the full address of your Halo instance (for example `https://halo.yourcompany.com`). A trailing `/api` or slash is ignored.

As you type the Halo URL, xClause shows the API address it will call ("xClause will call ..."). If the URL is refused, the reason appears under the field and the connect button stays disabled.
Click Connect to Halo PSA. xClause saves the credentials (encrypted), requests an access token from your Halo instance, and shows Halo PSA connected successfully! on success.

When the connection works, the card shows a Connected badge, your Halo URL, Connected Since, Last Synced, and Data sync (Enabled or Disabled).

xClause only checks that Halo issues an access token when you connect. It does not test individual permissions. A missing permission shows up later, the first time xClause calls that area of Halo. Use the Testing & debug tab to check permissions right away.

To change credentials or the URL, click Update connection and re-enter all three fields. The button in the dialog is Save connection.

Permissions the API account needs

xClause requests a token with the client_credentials grant and the scope all, so the permissions that apply are the ones set on your Halo API application and its agent. The table lists every Halo area xClause calls that you can reach from the xClause interface.

Halo area	What xClause does there	Access
Clients	Searches for the client by name when a contract is created or synced; creates the client if none matches. Lists clients in Data management.	Read and write
Sites	Looks up the client's sites; creates a site named "Main Site" if the client has none.	Read and write
Users (client contacts)	Looks up the client's users; creates a user from the client contact if none matches. Reads the first user in Halo as a fallback contact for the opportunity.	Read and write
Agents	Reads the first agent as a last-resort contact for the opportunity.	Read
Opportunities	Creates the opportunity for a contract. Lists opportunities in Data management. Used as the fallback record to close when a contract is fully signed.	Read and write
Quotations	Creates a quotation linked to the opportunity. Sets a record's status to Closed when the contract is fully signed.	Write
Invoices	Lists invoices in Data management and in the full integration test.	Read
Items	Lists items from the Halo item catalog when you link products or import items into a SOW.	Read
Recurring invoice lines	Reads recurring invoice lines for the nightly license sync.	Read

The error messages xClause shows name three Halo permission groups: AgentCustomers (Clients), AgentQuote (Quotations), and AgentSales (Opportunities). Each is described there with a Read level for GET requests and a Modify level for POST and PATCH requests. Grant the API account at least those, plus the access shown in the table for the other areas: read and write for sites and users, and read for agents, invoices, items, and recurring invoice lines.

xClause never deletes anything in Halo from the interface.

After you change permissions in Halo, click Refresh connection in xClause so it requests a new token.

What syncs, and which direction

Most data flows from xClause to Halo. The exceptions are client and contact import, and the read-only lists noted below.

What	Direction	Trigger
Clients and their contacts	Halo to xClause	You pick them in Clients & users > Manage. A Halo client is linked to an existing xClause client with the same name rather than duplicated. Contacts without an email address are skipped.
Client, site, and contact	xClause to Halo (created only if missing)	A contract is created or synced
Opportunity (title, value, a description with the contract ID and type, 75% probability, target date)	xClause to Halo	A contract is created; a SOW is submitted, built through quick start, or created by a workflow; or you click Sync all contracts
Linked quotation	xClause to Halo	Created right after the opportunity, when permissions allow
Closed status on the Halo record	xClause to Halo	The final signature that makes both the MSA and the SOW signed
Clients, opportunities, invoices (50 per list)	Halo to xClause (display only)	You open the tab or click the refresh button on it
Item catalog	Halo to xClause (display only)	You open the product picker or the SOW import
Recurring invoice lines (up to 500)	Halo to xClause	A nightly job, once a day at 03:00 UTC

Details that affect what you see in Halo:

Client matching. xClause matches the client by name, ignoring case. If exactly one Halo client is returned and its name contains, or is contained in, the xClause name, xClause uses it. Otherwise it creates a new client.
Default client. If xClause cannot find or create the client, it uses a Halo client named XClause Default Client, creating it if needed. If that also fails it uses the first client Halo returns.
Target date. The opportunity's target date is the contract's expiration date, or 30 days after creation if the contract has none.
One opportunity per contract. xClause stores the Halo ID on the contract. A contract that already has an ID is skipped by Sync all contracts.
Sync all contracts processes up to 100 of your most recent contracts and updates Last Synced. It is disabled when Data sync is Disabled. The toast reports how many contracts synced and how many failed.
Closing needs a stored ID. A contract created before you connected Halo has no stored Halo ID. Run Sync all contracts to give it one, or xClause has nothing to close when it is signed.
License sync. The nightly job reads recurring invoice lines and records each line's item and quantity as a contracted quantity. It does not write quantities back to Halo.

Troubleshooting

Messages appear as notifications in xClause. Where a message includes your Halo address, it is shown as the address xClause called.

Connecting

Message	What to do
Please provide Client ID, Client Secret, and Halo URL	Fill in all three fields.
Halo instance "..." is not usable: ...	The Halo URL is malformed. Enter your subdomain on its own (for example `acme`) or the full https address of your instance.
xClause only calls Halo over https, so ... is refused.	Use an `https://` address.
xClause only calls Halo on the standard https port (443), so ... is refused.	Remove the port from the URL.
... is an IP address. Enter your Halo host name instead	Use the host name, not an IP address.
... is a local or internal address, so xClause will not call it.	xClause cannot reach internal-only hosts. Use the public host name of your Halo instance.
A Halo URL cannot carry a user name or password.	Remove anything before an `@` in the URL.
xClause could not find (host). Check the Halo URL.	The host name does not resolve. Check for typos.
(host) points to a private or internal network address, so xClause will not send your Halo credentials there.	The host name resolves to a private network. Use your public Halo address.
Halo redirected (address) to (path), so this address is not Halo's API. Check that the Halo URL is the Resource Server from Halo's API Details.	Copy the Resource Server from API Details in Halo.
Halo answered (host) with a redirect (HTTP n) and no usable address, so xClause stopped. Check the Halo URL.	Same as above.
Couldn't reach (token address); check the Halo URL.	The address did not answer. Check the Halo URL.
Couldn't get a token from (token address) (HTTP n); check the Halo URL and Client ID/Secret.	Check the URL, then the Client ID and Client Secret. If you no longer have the secret, generate a new one in Halo.
(token address) answered, but not with a Halo token; check the Halo URL.	The address belongs to something other than Halo's API. Check the URL.
Halo answered at (token address) but issued no access token; check the Client ID/Secret.	Check the credentials and that the API application is set to Client ID and Secret (Services).
Failed to connect to Halo PSA.	Try again. If it keeps failing, contact support.

If the connection test fails, xClause saves the credentials but marks Data sync as Disabled, so no contracts sync until you connect successfully.

After connecting

What you see	What it means and what to do
Credentials incomplete badge: "Halo PSA credentials are incomplete"	The stored credentials cannot be read. Click Update connection and re-enter the Client ID and Client Secret. Halo shows the secret once, so generate a new one if you no longer have it.
Not responding badge: "Halo PSA is not responding"	xClause could not get a working answer. This can be an outage at Halo or revoked credentials. Nothing is disconnected. Click Refresh connection. If it keeps failing, use Update connection.
Status unknown badge: "We could not reach Halo PSA just now"	Usually a slow or unavailable Halo. Your connection is still saved. Click Refresh connection in a moment.
"We couldn't load your Halo PSA connection status."	This is a problem reading the status, not a verdict on the connection. Click Try again.
Halo PSA didn't answer. That can be an outage on their side or credentials that no longer work...	Shown by Refresh connection. Try again, and update the connection if it keeps failing.
Halo PSA API error: 403 Forbidden - Your API Application needs (permission) permission. After updating permissions in Halo PSA, click "Refresh Token" in XClause.	The API application lacks a permission (AgentCustomers, AgentQuote, or AgentSales, depending on the area). Fix it in Halo, then click Refresh connection (the message calls it "Refresh Token").
Halo PSA API error: 403 Forbidden - Token refreshed but still denied...	A fresh token was still refused. Check the API application's permissions, or disconnect and reconnect to get a fresh token.
Halo PSA API error: 401 Unauthorized - Invalid credentials or expired token.	Click Refresh connection. If it persists, update the connection.
Halo PSA permission denied. Please ensure your API application has "AgentSales Modify" permission.	Grant the Opportunities (AgentSales) write permission in Halo.
Halo PSA endpoint not found. Your Halo instance may use different API endpoints.	Check that the Halo URL is the Resource Server for your instance.
Please select a valid Client/Site/User	Halo needs an opportunity to belong to a client, site, or user. xClause tries to create these automatically. Check that the API account can read and create clients, sites, and users.
Halo PSA integration is not active	Data sync is Disabled. Click Update connection and reconnect.
We couldn't reach Halo PSA to load clients / opportunities / invoices	Check the connection on the Connection settings tab and try again.
We couldn't sync your contracts to Halo PSA	Check the connection and try again.
"(n) contracts failed to sync"	Run the full integration test on Testing & debug to find the failing area.

The opportunity is missing in Halo

Contract creation does not show Halo errors. If an opportunity did not appear:

Open the Testing & debug tab and click Run Full Test. It checks the connection, token, and read access to clients, opportunities, and invoices, then creates a test client and test opportunity. The Test opportunity creation section creates one opportunity for a client you pick or name.
Fix any area that fails, then click Refresh connection.
Open Data management and click Sync all contracts to create the missing opportunities.

The tests create real records in Halo (a client named "XClause Test Client" followed by a number, and test opportunities). Delete them in Halo when you are done.

Disconnecting

Open the Halo PSA integration.
Click Disconnect.
Confirm Disconnect from Halo PSA?

Disconnecting deletes the Halo connection record in xClause, including your stored Client ID, Client Secret, and access tokens. Contracts and other data already in xClause are not changed, and the Halo IDs saved on contracts stay. Nothing is deleted in Halo, and the API application remains in Halo until you remove it there. New opportunities stop being created, and signed contracts no longer close Halo records, until you reconnect.