Set up the API application in Halo
A Halo administrator does this. The menus and labels below are the ones Halo's own screens show.
Step 1: note your Halo's addresses
In Halo, go to Configuration, then Integrations, then Halo API. Note the Resource Server URL, the Authorisation Server URL and your Tenant name.
Step 2: create the application
Create an application there with the authentication method Client ID and Secret (Services), and choose an agent for it to log in as. Every ticket we open shows that agent as the one who raised it, so choose one your engineers will recognise.
Step 3: give it its permission
On its Permissions tab, tick all. That is the scope we ask for. Halo has no narrower permission for tickets, customers or invoices, and the other entries on that tab cover different ground.
Halo warns that all is a broad scope, and it is. What limits us is the agent you chose in step 2. Every call we make is made as that agent, so we can do nothing it cannot. Give it a role that reaches the tickets and customers you are happy for us to work on, and invoices if you want an invoice line kept in step. That role is yours to tighten whenever you like. When Halo refuses something, the card says so, and we do not work around it.
Step 4: copy the client ID and secret
Copy the Client ID and the Client Secret.
Connect it in the partner console
In your partner console, open Integrations and its PSA tab. Paste the five values into the HaloPSA card: the two addresses, the tenant name, the client ID and the secret.
We store the secret encrypted, use it only to talk to your Halo, and never show it again. If you lose it, give the application a new secret in Halo and connect again.
Connecting does not call Halo straight away. We check the connection in the background, which takes up to a minute: refresh the page to see the result. If Halo refuses the credential, we say so and delete it, so we never keep one that does not work.
Choose a ticket type
Nothing opens until you do. Every ticket has to be raised as one of your ticket types, so under Settings on the card, choose the one we should use. We read the list from your Halo when we check the connection, so these are your own types, in your own words.
Choose the type whose defaults you want our tickets to take. Its team, its priority, its SLA and its own rules all apply, just as they would to a ticket an agent raised by hand. We send the summary, the details, the company, the site and the type, and nothing else.
Until a type is chosen, the card says so and everything waits. Choosing one sends what has been waiting. Settings is also where you choose what opens a ticket, and where you can have each change open a ticket of its own.
Choose how a note is added
Halo records each note on a ticket as an action, and an action has to be one of your own outcomes. Add notes as on the card is where you choose which.
We offer only the outcomes that change nothing else about the ticket. An outcome can close a ticket, move it to another status, hand it to another team or email your client, and none of that should happen because we added a note. So an outcome that moves a ticket to a status is left off the list. Our notes are private, and email nobody.
If your Halo has an outcome called Internal Note, we choose it for you. If you have renamed yours, nothing is chosen. Until you choose one, each later change opens its own ticket instead of a note, and the card says so.
Match your companies
Nothing is matched for you. On Match companies, each of your customers gets a list of your Halo companies and a suggestion:
- One exact name match: suggested, and you confirm it.
- Two or more: nothing suggested, because choosing between them is your call.
- None: the closest names are listed first.
Harbourview Ltd and Harbourview Limited are treated as different companies, because two companies can have names that close. Apply every single suggestion accepts all the unambiguous ones at once, and skips every row where two companies match.
Events for a customer with no match wait, rather than going somewhere wrong. The card shows how many are waiting, and the button that saves a match tells you how many it will send.
Keep an invoice line in step
If you bill a client for managed DMARC on a recurring invoice in Halo, we can keep that line's quantity at the number of their domains we manage. Your next invoice to them is then right without anybody counting. It is your bill to your client: our own invoice to you is separate, and never goes into your Halo.
On a matched customer's row on Match companies:
- Press Load invoice lines. Within a minute we read that company's recurring invoices from your Halo. Refresh to see their lines.
- Choose the line you bill managed DMARC on and press Keep this line in step. That is the whole opt-in: a customer with no line chosen is never touched in Halo.
- We then keep its quantity at the number of that customer's domains where managed DMARC is active. A domain still waiting for its DNS change is not counted.
After that we check every six hours, and within a couple of minutes of the number of managed domains changing. A domain removed from a customer is counted at the next six-hourly check. If someone changes the quantity by hand in Halo, we set it back, and the card says when we did.
Stop keeping it in step stops us and changes nothing in Halo: the quantity stays as it is, yours to edit. The same is true when you remove a customer from your list.
If you match a customer to a different company, or remove their match, the old company's line keeps its quantity, so that client goes on being invoiced at the last figure. Match companies and the HaloPSA card say what Halo still holds, on which line and for which company. Set it to zero in Halo, or press Set to zero: we set it, read it back, and clear the warning once Halo shows 0. We never set it to zero unless you press the button.
The agent we log in as must be able to read and edit invoices for any of this. Without that, Halo refuses and the card says so.
What opens a ticket
You choose, kind by kind, what opens a ticket. By default:
| What happened | What it opens |
|---|---|
| An alert was raised for a domain | A new ticket each time |
| An impersonation campaign was detected | A new ticket each time |
| A domain reached a new stage | A note on that domain's open ticket, or a new ticket |
| A domain's published DMARC policy or reporting changed | A note on that domain's open ticket, or a new ticket |
| A security scan finished | A note or a new ticket, only if the score fell between two comparable scans |
| A domain was added, its DNS onboarding moved on, or managed DMARC was turned on or off | Nothing |
| A customer joined or left your book, or changed status | Nothing |
Two scans are comparable when both read the same checks and the same version of our scanner scored both. A check a scan could not read, because a lookup timed out or a source refused us, is scored as unknown, so a score can move just because one scan saw more than the other. That is not a fall. To see every scan, choose Open a ticket every time: when two scores do not compare, the ticket says so.
A second change to the same domain is added as a note on the ticket we opened for it, so each domain's changes stay in one thread. Once that ticket is closed, the next change opens a new one. You can turn threading off and get a ticket for each change.
Each ticket number opens its ticket
Under Recent tickets on the PSA tab, the number beside each ticket we opened or noted links to it in your Halo. Your Halo opens in a new tab, where you sign in as usual. A number from before you last connected has no link, because it may belong to a different Halo.
What a ticket never contains
Your engineers read a ticket, and often forward it, so it follows the same rule as our API and webhooks:
- No text from a DMARC report. No alert title or detail, no impersonation origin name, no reporter names, no published record text. DMARC reports are unauthenticated mail, so whoever sent one chose its contents. A ticket carries our own fixed wording and counts, and the detail is in your partner console.
- Nothing read back from your Halo. We never copy a company name from your Halo into a ticket in your Halo.
- No markup. Plain text only. Halo shows a ticket's details and notes as formatted text, so we escape the characters formatting is made of, and nothing in a name can become formatting, an image or a link.
- The names a ticket does carry (yours, your customers' and their domains) have invisible and bidirectional characters removed, and are cut to a set length.
Every ticket carries a reference such as rosebud:event:1234 in its third-party ID and in the last line of its details. That is how we know whether we have already opened a ticket for an event, so please do not remove it.
Cutting us off
Either end works:
- Disconnect on the PSA tab of Integrations. We stop at once and delete the stored credential. Your company matches are kept, so connecting the same Halo again resumes where you left off.
- Delete the application in Halo, or give it a new secret. Our access token can go on working until it expires, which is about an hour. After that the connection fails, and the card says so.
Limits
- One Halo connection per partner, and five connection attempts an hour.
- We read up to 2,000 of your companies.
- We send at most 24 requests a minute to your Halo for your tickets, notes and invoice lines. Re-reading your companies, once a day or when you ask, comes on top. We back off whenever Halo asks us to.
- If Halo stops answering, we pause, try again over about eight and a half hours and show you what happened. Six attempts with no clear answer leave the event marked not confirmed, with its reference, so you can search Halo for it yourself.