HaloPSA Integration Setup – MSPbots.ai

Connecting HaloPSA to MSPbots lets you leverage automation and Business Intelligence (BI) solutions to manage every aspect of your MSP business. The integration is done by assigning the appropriate user permissions in HaloPSA, entering the integration settings in the MSPbots app, and configuring webhooks.

This article provides the prerequisites and step-by-step guide to establishing a HaloPSA connection with MSPbots.

1. Prerequisites for connecting HaloPSA to MSPbots

You need the following to establish a successful Halo PSA integration with MSPbots:

Correct permissions set in Halo PSA:
- Ensure the user is part of a department or team that has the corresponding permissions to access the relevant data. If the user is not, click Edit to add the user to a corresponding team or department.

2. How to transition to the new backend webhook

Due to the Halo team upgrading the backend webhook version and not maintaining support for the old system. If you continue to use the old version of the webhook, it may cause issues.

So, refer to the following steps to upgrade the backend webhook. If you have already upgraded, skip and proceed with the configuration of section 3.

Log in to HaloPSA.
Click Configuration > Advanced Settings in sequence.
Navigate to Backend Services and select the checkboxes for the following options：
- Use Event Service
- Use Outgoing Service (BETA)
- Use Incoming Service (BETA)

3. How to obtain field values connecting HaloPSA integration

Log in to HaloPSA.
Click Configuration > Integrations > HaloPSA API in sequence.
Copy the values of the Resource Server and Authorization Server to your desktop.
When connecting to Halo integration, these two values will be used as the Resource URL and Auth URL, respectively.
Click View Applications.
Click New, and fill in the following fields in the Details section.

If you already have an account, click on the account name and follow the steps below to check if the Details and Permissions settings of the account are correct.
1. Enter a unique Application Name, the value of the Application Name will be used as the value of the Tenant field when connecting to the Halo integration to MSPbots.
2. Keep Active checked.
3. For the Authentication Method, check Client ID and Secret (Services).
4. Be sure to copy the values of Client ID and Client Secret to your desktop. These values are required when connecting Halo integration to MSPbots.
  
  Be sure to save the value of Client Secret as it is only shown during the creation of the application. Once saved, the value of the Client Secret will no longer be displayed.
5. For Login Type, select Agent.
6. For Agent to log in as, select the admin who will access to the MSPbots app.
Click Permissions, select all:standard and admin:webhooks to assign permissions to the admin user.
Click Save.

4. How to configure Agents permissions

Go to Configuration > Teams & Agents > Agents in sequence.
Click the admin name you selected in Step 3.5.f.
Click Permissions.
Click Edit.
On the Permissions tab, set the following fields:
1. Navigate to Feature Access, and set the following fields to Read Only:
  - Tickets Access Level
  - Clients Access Level
  - Users Access Level
  - CRM Access Level
  - Assets Access Level
  - Calendars and Appointments Access Level
  - Suppliers Access Level
  - Items Access Level
  - Sales Access Level
  - Quotations Access Level
  - Billing Details Access Level
  - Invoices Access Level
  - Reporting Access Level
  - Client Contracts Access Level
  - Supplier Contracts Access Level
  - Timesheets Access Level
  - Software Licencing Access Level
2. Navigate to Tickets Permissions, and set the following two fields to Yes:
  - Can view Unassigned Tickets
  - Can view Tickets that are assigned to other Agents
3. Navigate to Asset Type Restrictions, and set Allow use of all Asset Types to Yes.
4. Navigate to Ticket Type Restrictions, and set Allow use of all Ticket Types to Yes.
5. Navigate to Asset Field Restrictions, and set Allow use of all Asset Fields to Yes.
6. Navigate to Calendars and Appointments Permissions,
  - Set Editing of Appointments to Can Edit Own Appointments Only.
  - Set Adding New Appointments to Can Add All Appointments.
  - Set Visibility of Appointments to Can view Team and Department Appointments Only.
  - Set Deleting of Appointments to Can Delete Own Appointments Only.
7. Navigate to Billing Permissions,
  - Set Can View Item Costs to Read Only.
  - Set Can View Item Prices to Read Only.
  - Set Can View Agent Costs to Yes.
Click Save.

5. How to set up the HaloPSA and MSPbots Integration

5.1. Complete the prerequisites for the integration.

5.2. Submit the required information in the MSPbots app.

Log in to the MSPbots app and navigate to Integrations on the menu.
Search for Halo PSA and click it to open the connection settings.
When the Halo PSA configuration settings appear, fill in all of the following required fields:
- Auth URL - Enter the Authorization Server from Step 3.3.
- Resource URL - Enter the Resource Server from Step 3.3. For example, https://xxx.xxx.xxx/api.
- Tenant - Enter the Application Name from Step 3.5.a.
  
  When you are using Halo On Premise, go to Configuration > HaloPSA API in the Halo app, then copy and enter the value of Tenant here.
- Client ID - Enter the Callback URL from Step 3.5.d.
- Client Secret - Enter the Callback URL from Step 3.5.d.
Click Save And Sync when done. When Success appears, the connection of HaloPSA integration is successful.
Click the Config coin to open the connection settings.
Click to copy the value for the Callback URL to your desktop.

5.3. Configure the HaloPSA webhook

A webhook is required for HaloPSA dashboards to function properly. Configure the HaloPSA webhook according to the steps below.

It is important to configure the webhook correctly. If not properly set, an incorrect webhook may affect the normal data synchronization adversely and trigger HaloPSA's request limit rate of 450 requests within 5 minutes.

A correct webhook configuration request ensures that the system will not initiate duplicate synchronizations, thereby reducing the possibility of triggering the rate limit.

Once the field for Callback URL is visible, log in to the HaloPSA app.
Navigate to Configuration > Integrations > Webhooks.
Click New to open the New Webhook screen.
Fill in the following fields. You can leave the other fields with their default values.
- Webhook Name - Enter a unique webhook name.
- Payload URL - Enter the Callback URL from Step 5.2.6.
- Day(s) to Retain Logs - Enter 7.
- Payload - Select Full object with linked objects from the dropdown list.
Add a Ticket Changed event that includes criteria.
1. Click Add to add a new event.
2. On the New Event screen, select Ticket Changed from the Event dropdown menu.
3. Click Add .
4. In the Add Criteria pop-up window, select Summary and then click Save.
5. Fill in the following fields.
  - Set Change Context to Value changed.
  - Set Rule Type to Is not equal to.
  - Set Summary to "".
6. Click Save.
7. Click Save on the New Event screen.
  
  Note that when you successfully add the Ticket Changed event, its name will display as Ticket Updated.
  
  Clicking on the event to enter its detail page will then display the event name as Ticket Changed - All. This is a normal occurrence and is the name defined by the official Halo API in the HaloPSA app, so there is no need to worry. Proceed with the next steps.
Add multiple events that do not contain criteria. Repeat Step 6.a, Step 6.b, and Step 6.c until the events are added.
1. Click Add .
2. Select an event from the Event dropdown menu, such as New Ticket Logged.
3. Click Save.
  
  You need to repeat Step 6.a, Step 6.b and Step 6.c to add the following events.
  - New Ticket Logged
  - Ticket Deleted
  - Ticket Status Changed
  - Site created
  - Site updated
  - Site deleted
  - User created
  - User updated
  - User deleted
  - Invoice created
  - Invoice updated
  - Invoice deleted
  - Asset created
  - Asset updated
  - Asset deleted
  - Purchase Order created
  - Purchase Order updated
  - Purchase Order deleted
  - Sales Order created
  - Sales Order updated
  - Sales Order deleted
  - Quotation created
  - Quotation updated
  - Quotation deleted
  - Item created
  - Item deleted
Then click Save on the New Webhook screen.
Navigate to Configuration > Advanced Settings.
Check the following option in the Backend Services section:
- Use Outgoing Service (BETA)
- Use Incoming Service (BETA)
Back to Integrations in MSPbots, you can check the data synchronization status of the webhook.

What are the Webhook statuses and messages for the HaloPSA integration?

The Webhook statuses for your Halo PSA interaction can show any of the following:

Status	Message	Description
Webhook Successful		This means that all the data was received successfully.
Webhook Received No Data For Some Events		This means that Webhook did not receive some data because of one of the following reasons: The webhook is not properly configured. Ensure correct configuration and refer to the section Configure the HaloPSA webhook. There is no new data from the webhook yet. Verify this by creating a new invoice, site, ticket, or user.
Webhook Received No Data		This means the webhook did not receive data because of the same reasons explained in the previous status message. Resolve this using the same recommendations for the previous message.
Webhook Received No Data Within 4 Days		This means that MSPbots has not received data from the webhook for the past 4 days. Ensure that all webhook events are properly configured according to the section Configure the HaloPSA webhook.

Known issues

The Halo API connection failed with the error message "/Appointment: 403: Forbidden"

403(1).jpg

Refer to Step 3.6 in How to obtain field values connecting HaloPSA integration section to check if your account's permissions are set to all and all:teams.

The response times in Halo's widgets are high

The response times in Halo's widgets may appear high because it counts all the ticket's response times instead of counting only the first response. This issue happens because the first response time field is not yet available in Halo's API.

We are actively working with Halo's team to add this field as soon as it is released.

The SLAtimeleft field value in Halo tickets is not up-to-date

You may encounter an issue where the SLAtimeleft field data in your widgets, dashboards, or other assets does not display the most current values.

Potential causes

The Ticket SLAtimeleft field value is dynamically calculated because Halo computes and returns the SLAtimeleft value only when requested via API. Halo does not maintain real-time SLA countdowns for all tickets in the database or API, and real-time updates for the SLAtimeleft field are not provided through API or WebHook.

As a result, this field value is dynamically calculated rather than statically updated, meaning the ticket's SLAtimeleft field does not change in real time.

This behavior indicates that when the SLAtimeleft field updates:

Changes to the SLAtimeleft attribute in Halo Ticket API do not trigger updates to the ticket's last_update field.
These changes are not pushed in real-time through WebHook.
The value must be dynamically calculated before being returned to MSPbots.

Consequently, you may observe that the SLAtimeleft field data is not the most current.

Solution

Due to third-party API limitations, we cannot fully resolve this issue until the third party implements updates. We sincerely apologize for this inconvenience. We have reported this issue to the Halo support team, and MSPbots will investigate potential solutions at the application layer.

To obtain near real-time SLAtimeleft field values, you need to periodically request information through the ticket endpoint for now.

FAQs

1. How to disable notifications for MSPbots API user in Halo, such as the "mspbots.ai is currently viewing this Ticket" notification?

Halo notification.png

After confirming with the Halo support team, these notifications are only received in Halo app versions earlier than Beta v2.190.1. The feature to disable notifications for API users has been available in Beta v2.190.1 and later.

If the Halo app version is Beta v2.190.1 or later, API users no longer receive these notifications. ( MSPbots API user is the user who connects the Halo integration to MSPbots.)

Solutions

If the Halo app version is earlier than v2.190.1,

Upgrade the Halo app to v2.190.1 or later.
If you do not want to upgrade, you can disable notifications for all users by clearing Enable collision detection for when multiple Agents are viewing the same Ticket checkbox.