HaloPSA

1. Overview

HaloPSA is a comprehensive Professional Services Automation (PSA) platform designed for Managed Service Providers (MSPs) and IT service desks. It centralizes operations, including service desk management, project management, billing, and customer relationship management.

With the GoInsight Halopsa node, you can seamlessly integrate your service management tasks into automated workflows. This allows you to manage the entire lifecycle of key resources within HaloPSA directly from your workflows, including:

• Client Management: Create, retrieve, update, and delete client records.
• Site Management: Manage sites associated with clients, including creation, retrieval, updates, and deletion.
• Ticket Handling: Automate the creation, retrieval, updating, and deletion of service tickets.
• User Administration: Manage user accounts, including creating, finding, updating, and deleting them.

2. Prerequisites

Before using this node, you must have a valid Halopsa account. You may also need administrative privileges or specific API permissions within your HaloPSA instance to generate and manage the necessary credentials for authentication.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node provides a comprehensive set of operations for managing clients, sites, tickets, and users within your HaloPSA environment. The table below summarizes the available actions.

Operation Details

Create a Client

Create a new client in HaloPSA using OAuth2 authentication. Supports both on-premise and Halo-hosted solutions with optional VIP status, notes, and website information.

Options:

• Name: Client name to be created
• Inactive: Account status, false = Active, true = Inactive
• Notes: Additional notes or description for the client
• IsVip: Whether the client is a VIP customer
• Website: Client website URL

Output:

• Client (object): Created client information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Delete a Client

Delete a client in HaloPSA by client ID. This operation permanently removes the client record using OAuth2 authentication.

Input Parameters:

• Id: Client ID to be deleted

Output:

• Success (bool): Whether the client was successfully deleted
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get a Client

Get a client information from HaloPSA by client ID using OAuth2 authentication. Returns complete client details including VIP status, notes, and website information.

Input Parameters:

• Id: Client ID to retrieve information

Output:

• Client (object): Client information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Clients

Get multiple clients from HaloPSA with pagination, filtering and search support using OAuth2 authentication. Returns a list of clients with total record count.

Options:

• Count: Limit the number of clients returned
• PageNo: Current page number for pagination
• PageSize: Number of records per page
• Pageinate: Whether to enable pagination
• Search: Search keyword to filter clients
• IncludeActive: Include active clients in results
• IncludeInactive: Include inactive clients in results

Output:

• Clients (object-array): List of client information objects
• RecordCount (number): Total number of records
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Update a Client

Update an existing client in HaloPSA using OAuth2 authentication. Supports updating name, status, VIP flag, notes, and website information.

Input Parameters:

• Id: Client ID to update

Options:

• Name: Client name to update
• Inactive: Account status, false = Active, true = Inactive
• Notes: Additional notes or description for the client
• IsVip: Whether the client is a VIP customer
• Website: Client website URL

Output:

• Client (object): Updated client information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Create a Site

Create a new site in HaloPSA using OAuth2 authentication. A site must be associated with an existing client and can include contact information and notes.

Input Parameters:

• Name: Site name to be created
• SiteClientId: Client ID that this site belongs to

Options:

• MaincontactName: Main contact person name
• Notes: Additional notes or description for the site
• Phonenumber: Contact phone number

Output:

• Site (object): Created site information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Delete a Site

Delete a site in HaloPSA by site ID. This operation permanently removes the site record using OAuth2 authentication.

Input Parameters:

• Id: Site ID to be deleted

Output:

• Success (bool): Whether the site was successfully deleted
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get a Site

Get a site information from HaloPSA by site ID using OAuth2 authentication. Returns complete site details including client information, contact details, and phone number.

Input Parameters:

• Id: Site ID to retrieve information

Output:

• Site (object): Site information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Sites

Retrieve a list of sites from HaloPSA with pagination and filtering support. All parameters are optional with default values.

Options:

• Count: Limit the number of sites returned
• PageNo: Current page number for pagination
• PageSize: Number of records per page
• Pageinate: Whether to enable pagination
• Search: Search keyword to filter sites
• IncludeActive: Include active sites in results
• IncludeInactive: Include inactive sites in results

Output:

• Sites (object-array): List of site information objects
• RecordCount (number): Total number of records
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Update a Site

Update an existing site in HaloPSA using OAuth2 authentication. Supports updating name, client association, contact information, notes, and phone number.

Input Parameters:

• Id: Site ID to update

Options:

• Name: Site name to update
• SiteClientId: Client ID to associate with the site
• MaincontactName: Main contact name
• Notes: Additional notes or description for the site
• Phonenumber: Contact phone number

Output:

• Site (object): Updated site information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Create a Ticket

Create a new ticket in HaloPSA using OAuth2 authentication. Requires ticket type ID, summary, and detailed description.

Input Parameters:

• TickettypeId: Ticket type ID
• Summary: Ticket summary
• Details: Ticket detailed description

Options:

• AgentId: Assigned agent/technician ID
• Startdate: Start date in ISO format (e.g., 2025-10-30T10:00:00)
• Targetdate: Target date in ISO format (e.g., 2025-11-05T18:00:00)

Output:

• Ticket (object): Created ticket information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Delete a Ticket

Delete a ticket from HaloPSA by ticket ID using OAuth2 authentication. Supports both on-premise and Halo-hosted solutions.

Input Parameters:

• Id: Ticket ID to delete

Output:

• Success (bool): Whether the ticket deletion was successful
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get a Ticket

Get a ticket information from HaloPSA by ticket ID using OAuth2 authentication. Returns complete ticket details including status, priority, and assignment information.

Input Parameters:

• Id: Ticket ID to retrieve information

Output:

• Ticket (object): Ticket information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Tickets

Retrieve a list of tickets from HaloPSA with pagination and filtering support. All parameters are optional with default values.

Options:

• Count: Limit the number of tickets returned
• PageNo: Current page number for pagination
• PageSize: Number of records per page
• Pageinate: Whether to enable pagination
• Search: Search keyword to filter tickets
• IncludeActive: Include active tickets in results
• IncludeInactive: Include inactive tickets in results

Output:

• Tickets (object-array): List of ticket information objects
• RecordCount (number): Total number of records
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Update a Ticket

Update an existing ticket in HaloPSA by ticket ID using OAuth2 authentication. Supports both on-premise and Halo-hosted solutions. Only provided fields will be updated.

Input Parameters:

• Id: Ticket ID to update

Options:

• TickettypeId: Ticket type ID
• Summary: Ticket summary to update
• Details: Ticket detailed description to update
• AgentId: Assigned agent/technician ID
• Startdate: Start date in ISO format (e.g., 2025-10-30T10:00:00)
• Targetdate: Target date in ISO format (e.g., 2025-11-05T18:00:00)

Output:

• Ticket (object): Updated ticket information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Create a User

Create a new user in HaloPSA using OAuth2 authentication. Supports both on-premise and Halo-hosted solutions with optional email, surname, password, and notes information.

Input Parameters:

• Name: User name
• SiteId: Associated site ID

Options:

• Emailaddress: User email address
• Surname: User surname
• Notes: Additional notes or description for the user
• Password: User password (at least 8 characters, including uppercase, lowercase, and numbers/symbols)
• Inactive: Whether the user is inactive, false = Active, true = Inactive

Output:

• User (object): Created user information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Delete a User

Delete a user in HaloPSA by user ID. This operation permanently removes the user record using OAuth2 authentication.

Input Parameters:

• Id: User ID to be deleted

Output:

• Success (bool): Whether the user was successfully deleted
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get a User

Get a user information from HaloPSA by user ID using OAuth2 authentication. Returns complete user details including name, surname, site, email, and notes information.

Input Parameters:

• Id: User ID to retrieve information

Output:

• User (object): User information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Users

Get multiple users from HaloPSA with pagination, filtering and search support using OAuth2 authentication. Returns a list of users with total record count.

Options:

• Count: Limit the number of users returned
• PageNo: Current page number for pagination
• PageSize: Number of records per page
• Pageinate: Whether to enable pagination
• Search: Search keyword to filter users
• IncludeActive: Include active users in results
• IncludeInactive: Include inactive users in results

Output:

• Users (object-array): List of user information objects
• RecordCount (number): Total number of records
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Update a User

Update an existing user in HaloPSA using OAuth2 authentication. Allows updating user name, surname, site, email, notes, password and inactive status. Only provided fields will be updated.

Input Parameters:

• Id: User ID to update

Options:

• Name: User name
• Surname: User surname
• SiteId: Site ID
• Emailaddress: User email address
• Notes: Notes or remarks
• Password: User password
• Inactive: Inactive status (true for inactive, false for active)

Output:

• User (object): Updated user information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

5. Example Usage

This section will guide you through creating a simple workflow to automatically create a new incident ticket in HaloPSA whenever the workflow is triggered.

The workflow will consist of three nodes: Start -> Create a Ticket -> Answer.

Step-by-Step Guide

1. Add the Tool Node:
   • In the workflow canvas, click the + button to add a new node.
   • In the pop-up panel, select the "Tools" tab.
   • Find and select "Halopsa" from the list of tools.
   • In the list of supported operations for Halopsa, click on "Create a Ticket". This will add the node to your canvas.
2. Configure the Node:
   • Click on the newly added "Create a Ticket" node to open its configuration panel on the right.
   • Credentials Configuration: At the top of the panel, find the credentials field. Click the dropdown menu and select the Halopsa credential you have already configured.
   • Parameter Configuration: Fill in the required input parameters for creating a ticket.
   • TickettypeId: Select "Incident" from the dropdown list, or enter the numerical ID 1.
   • Summary: Enter a concise title for the ticket, for example, "Network printer is offline".
   • Details: Provide a more detailed description of the issue, such as "The main office printer on the 2nd floor is not responding to pings and cannot be accessed from any workstation."
3. Run and Validate:
   • Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
   • Click the "Test Run" button in the top-right corner of the canvas to execute the workflow.
   • After a successful execution, you can click the log icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the ticket was created successfully.

After completing these steps, your workflow is fully configured. When executed, it will create a new incident ticket in your HaloPSA instance with the specified details.

6. FAQs

Q: I'm receiving a 401 Unauthorized error. What could be the cause?

A: A 401 error typically indicates an issue with your credentials. Please check the following:

• Correct Credentials: Ensure that the Client ID, Client Secret, and other details entered for your Halopsa credential in GoInsight are correct.
• Permissions: Verify that the API key or user associated with the credentials has the necessary permissions within HaloPSA to perform the requested action (e.g., create tickets, read clients).

Q: Why did my 'Create a User' action fail without a clear error message?

A: When creating a user, there are a few common silent failure points. Please verify the following:

• Valid SiteId: The SiteId you provided must correspond to an existing site in HaloPSA. An invalid ID will cause the request to fail.
• Password Complexity: If you are setting a password, ensure it meets HaloPSA's complexity requirements (e.g., minimum length, character types).
• Unique Email: The email address for the new user might already be in use within your HaloPSA instance.

7. Official Documentation

For more in-depth information about the HaloPSA API and its capabilities, please refer to the Halopsa Official API Documentation.