How to Setup HaloPSA Integration

Introduction

This guide outlines the steps to integrate HaloPSA with Uniportal, enabling seamless use of Uniportal's AI workflows directly from your service desk.

Prerequisites

Before proceeding, ensure you have the following:

• A login to your Halo tenant with Admin role permissions
• Admin/Owner role access to your Uniportal tenant

High-level steps

1. Create a new API-only HaloPSA agent for Uniportal
2. Create a new API application in HaloPSA
3. Configure the HaloPSA integration in Uniportal
4. Configure the Uniportal Custom Tab to appear inside tickets

Step 1: Create a new API-only agent for Uniportal

1. Log into HaloPSA. In the sidebar, click Configuration.
2. In the search bar, type Agents.
3. Click on the Agents icon.
4. Click the New button near the top right of the screen.
5. In the Username field, enter Uniportal Integration.
6. In the Roles field, click and select Administrator.

Note: Once the integration is configured in the Uniportal dashboard and the Halo tab for tickets has been created, you can reduce the role permissions to a custom role with the permissions listed below. The Administrator role is required for the initial configuration so that Uniportal can push and create the ticket tab in Halo.

Minimum permissions for the custom role:

• Read and edit all tickets
• Add internal notes to tickets (Uniportal logs workflow activity here)
• Read, edit, and create end-users in HaloPSA (for matching directory accounts to Halo contacts)
• Read and edit full details of end-users including phone and email (used when end-users save contact info via the welcome email)
• Read all customers in HaloPSA (for customer matching)
• Access to configure webhooks (used to detect contact updates in Halo)

7. Click the checkbox for Is an API-only Agent.
8. Scroll to the bottom of the page and click Save. HaloPSA will flag any other required fields based on your Halo setup. Fill those out as needed.

Step 2: Create a new API application in HaloPSA

1. In the sidebar, click Configuration.
2. In the search bar, type HaloPSA API.
3. Click on the HaloPSA API icon.
4. In API Detail, record the Resource Server value into a temporary note on your computer, without the trailing /apidirectory.
   • HaloPSA presents it like: https://{yourhaloaddress}.halopsa.com/api
   • Save it as: https://{yourhaloaddress}.halopsa.com
5. In API Detail, record the Tenant value into your temporary note. It should look like mymspname.
6. In the Applications section, click View Applications.
7. On the top right, click the New button.
8. In Application Name, enter Uniportal.
9. In Authentication Method, click Client ID and Secret (Services).
10. Record the Client ID value into your temporary note.
11. Record the Client Secret value into your temporary note.
12. Ensure Login Type is set to Agent.
13. In Agent to login as, search for and select the API agent you created earlier (e.g. Uniportal Integration).
14. Scroll to the top and click the Permissions tab.
15. Select the following permissions:
    • All
    • All:Teams
16. Save your changes.

Step 3: Configure the HaloPSA integration in Uniportal

1. Log into the Uniportal dashboard at https://[your-subdomain].uniportal.ai with a technician account that has the Admin role.
2. In the sidebar, click Integrations.
3. Click the HaloPSA tile.
4. Using the information from your temporary note, populate the following fields:
   • Account URL (Resource Server from HaloPSA, without the trailing /)
   • Tenant
   • Client ID
   • Secret (Client Secret from HaloPSA)

Note: If you're an on-premise HaloPSA customer, enter any arbitrary value into the Tenant field, since on-prem Halo setups don't have a tenant value (e.g. selfhosted).

5. Click the Connect button.
6. If the connection succeeds, you'll be taken to the Customers page.

Contact settings

Click the Settings button to configure field mapping for syncing contacts with HaloPSA.

The Integration Settings dialog lets you select a PSA email and phone number field to sync with Uniportal. These fields are used for sending welcome emails, notifications, and authentication requests, and they update automatically whenever contact details change in Halo.

Future updates from HaloPSA will overwrite the email and phone number Uniportal has on file for the end-user. They also affect the email and phone number end-users use to log into the Uniportal self-serve experiences.

Once you've selected the email and phone field mappings, click Save.

Customer matching

Click Match Customer to begin matching your customers with HaloPSA.

You'll see a list of Halo companies in alphabetical order with three options for matching, plus the option to create a new Uniportal customer from a Halo client.

Use the Matched Status dropdown to filter Uniportal customers:

• Unmatched (default)
• Matched
• All

A company already part of a one-to-many match cannot be linked to another company.

Warning: Make sure the Relationship and Main Site fields are correctly filled out in HaloPSA for each client. Without these, Halo clients won't appear in customer matching.

Option 1: Automatic matches

Items marked with a three-star icon have been automatically matched, meaning the customer name in Uniportal exactly matches a customer in Halo.

Use Suggested Matches in the Match Status filter to quickly identify Uniportal customers that have been auto-matched.

Option 2: Manual matching

Accounts that aren't automatically matched can be manually linked.

Use the filters at the top of the screen to display Halo clients without an exact spelling match to a Uniportal customer.

Match status filters:

• All: Displays all Halo clients, regardless of matching status
• Unmatched: Shows Halo clients with no exact spelling match to any Uniportal customer
• Matched: Displays all Halo clients you've already assigned a match to

To define a manual match, click the Match with Uniportal Customer box, select the appropriate Uniportal customer, then click Select.

Option 3: Create Uniportal customers from Halo

You can also create new Uniportal customers based on existing clients in HaloPSA. Check the box next to the customers you'd like to create in Uniportal, then click Save.

Once your customers are matched, you can proceed to match end-user accounts in Uniportal with HaloPSA contacts.

Step 4: Configure the Uniportal tab to appear inside tickets

1. In HaloPSA, navigate to Configuration > Tickets.
2. Click Ticket Types to view all ticket types.
3. Click on any ticket type where you want the Uniportal integration to display, and add the Uniportal tab to the ticket layout.

Once the tab is added to your ticket types, technicians can run Uniportal workflows (onboarding, offboarding, password and MFA resets, group access changes, and any other skills in your Uniportal repository) directly from the ticket they're working on. All actions are logged back to the ticket as internal notes.