HaloPsa.Api 2.196.29

Halo PSA API .NET Library

A comprehensive, modern .NET library for interacting with the Halo PSA API. This library provides full coverage of the Halo PSA API with a clean, intuitive interface using modern C# patterns and best practices.

📚 Official Documentation

• API Documentation: https://halo.haloservicedesk.com/apidoc/info
• Authentication Guide: https://halo.haloservicedesk.com/apidoc/authentication/clientcredentials
• Halo PSA Official Site: https://haloservicedesk.com/halopsa

Features

• 🎯 Complete API Coverage - Full support for all Halo PSA endpoints
• 🚀 Modern .NET - Built for .NET 9 with modern C# features
• 🔒 Type Safety - Strongly typed models and responses
• 📝 Comprehensive Logging - Built-in logging and request/response interception
• 🔄 Retry Logic - Automatic retry with exponential backoff
• 📖 Rich Documentation - IntelliSense-friendly XML documentation
• ✅ Thoroughly Tested - Comprehensive unit and integration tests
• ⚡ High Performance - Optimized for efficiency and low memory usage

Installation

Install the package via NuGet Package Manager:

dotnet add package HaloPsa.Api

Or via Package Manager Console:

Install-Package HaloPsa.Api

Quick Start

1. Authentication Setup

Halo API uses OAuth2 Client Credentials flow for authentication. You'll need:

1. Halo Account Name - Your instance identifier (e.g., "yourcompany" for "yourcompany.halopsa.com")
2. Client ID - Your application's registered client ID (GUID format)
3. Client Secret - Your application's client secret (two concatenated GUIDs)

Refer to the official authentication documentation for detailed guidance on obtaining these credentials.

Creating API Credentials in Halo

1. Log into your Halo instance as an administrator
2. Navigate to Configuration → Integrations → Halo API
3. Click New to create a new API application
4. Configure the application settings:
   • Application Name: Your application name
   • Authentication Method: Client Credentials
   • Permissions: Select appropriate scopes for your use case
5. Save the application to generate your Client ID and Client Secret

using HaloPsa.Api;

var options = new HaloClientOptions
{
    HaloAccount = "your-account-name",        // e.g., "yourcompany" 
    HaloClientId = "your-client-id-guid",     // Generated Client ID (GUID)
    HaloClientSecret = "your-client-secret"   // Generated Client Secret (two concatenated GUIDs)
};

var client = new HaloClient(options);

2. Basic Usage Examples

Working with Tickets

// Use a CancellationToken for all async operations
using var cts = new CancellationTokenSource();
var cancellationToken = cts.Token;

// Get all open tickets
var filter = new TicketFilter
{
    Status = TicketStatus.Open,
    Count = 50
};

var tickets = await client.Psa.Tickets.GetAllAsync(filter, cancellationToken);

foreach (var ticket in tickets.Tickets)
{
    Console.WriteLine($"Ticket #{ticket.Id}: {ticket.Summary}");
}

// Get a specific ticket with details
var ticket = await client.Psa.Tickets.GetByIdAsync(12345, includeDetails: true, cancellationToken);
Console.WriteLine($"Ticket: {ticket.Summary}");
Console.WriteLine($"Status: {ticket.Status}");
Console.WriteLine($"Assigned to: {ticket.AssignedAgent?.Name}");

// Create a new ticket
var newTicket = new CreateTicketRequest
{
    Summary = "New ticket from API",
    Details = "This ticket was created using the HaloPsa.Api library",
    ClientId = 123,
    UserId = 456,
    TicketTypeId = 1
};

var createdTicket = await client.Psa.Tickets.CreateAsync(newTicket, cancellationToken);
Console.WriteLine($"Created ticket #{createdTicket.Id}");

Working with Users

// Search for users
var userFilter = new UserFilter
{
    Search = "john.doe",
    IncludeActive = true
};

var users = await client.Psa.Users.GetAllAsync(userFilter, cancellationToken);

// Get user details
var user = await client.Psa.Users.GetByIdAsync(123, includeDetails: true, cancellationToken);
Console.WriteLine($"User: {user.Name} ({user.EmailAddress})");

// Create a new user
var newUser = new CreateUserRequest
{
    Name = "Jane Smith",
    EmailAddress = "jane.smith@example.com",
    SiteId = 1,
    IsActive = true
};

var createdUser = await client.Psa.Users.CreateAsync(newUser, cancellationToken);

Working with Clients

// Get all active clients
var clientFilter = new ClientFilter
{
    IncludeActive = true,
    Count = 100
};

var clients = await client.Psa.Clients.GetAllAsync(clientFilter, cancellationToken);

// Get client with additional details
var clientDetails = await client.Psa.Clients.GetByIdAsync(123, includeDetails: true, cancellationToken);
Console.WriteLine($"Client: {clientDetails.Name}");
Console.WriteLine($"Contact: {clientDetails.MainContact?.Name}");

3. Advanced Configuration

Custom HTTP Configuration

var options = new HaloClientOptions
{
    HaloAccount = "your-account",
    HaloClientId = "your-client-id",
    HaloClientSecret = "your-client-secret",
    
    // Custom timeout
    RequestTimeout = TimeSpan.FromSeconds(30),
    
    // Custom retry policy
    MaxRetryAttempts = 3,
    RetryDelay = TimeSpan.FromSeconds(1),
    
    // Custom base URL (if using on-premises)
    BaseUrl = "https://your-instance.halopsa.com"
};

var client = new HaloClient(options);

Logging Configuration

using Microsoft.Extensions.Logging;
using Microsoft.Extensions.DependencyInjection;

// Create a service collection with logging
var services = new ServiceCollection();
services.AddLogging(builder => builder.AddConsole().SetMinimumLevel(LogLevel.Debug));

var serviceProvider = services.BuildServiceProvider();
var logger = serviceProvider.GetRequiredService<ILogger<HaloClient>>();

var options = new HaloClientOptions
{
    // ... authentication details
    Logger = logger,
    EnableRequestLogging = true,
    EnableResponseLogging = true
};

var client = new HaloClient(options);

4. Authentication Troubleshooting

If you're experiencing authentication issues:

1. Verify Client Credentials: Ensure your Client ID and Client Secret are correct and haven't been regenerated
2. Check API Application Status: Verify the API application is enabled in Halo Configuration
3. Validate Client ID Format: Ensure the Client ID is a valid GUID format
4. Validate Client Secret Format: Ensure the Client Secret is in the correct format (two concatenated GUIDs)
5. Check Permissions: Verify your API application has the necessary permissions/scopes
6. Network Connectivity: Ensure your application can reach the Halo API endpoints
7. On-Premise vs Cloud: On-premise installations may require custom BaseUrl configuration

5. Pagination and Large Result Sets

// Handle pagination automatically
var allTickets = new List<Ticket>();
var pageSize = 100;
var pageNumber = 1;

do
{
    var filter = new TicketFilter
    {
        PageSize = pageSize,
        PageNumber = pageNumber,
        IncludeActive = true
    };
    
    var response = await client.Psa.Tickets.GetAllAsync(filter, cancellationToken);
    allTickets.AddRange(response.Tickets);
    
    pageNumber++;
    
    // Continue while we got a full page
} while (response.Tickets.Count == pageSize);

Console.WriteLine($"Retrieved {allTickets.Count} total tickets");

6. Error Handling

try
{
    var ticket = await client.Psa.Tickets.GetByIdAsync(99999, cancellationToken);
}
catch (HaloNotFoundException ex)
{
    Console.WriteLine($"Ticket not found: {ex.Message}");
}
catch (HaloAuthenticationException ex)
{
    Console.WriteLine($"Authentication failed: {ex.Message}");
    Console.WriteLine("Check your username, password, and API permissions");
}
catch (HaloApiException ex)
{
    Console.WriteLine($"API error: {ex.Message}");
    Console.WriteLine($"Status code: {ex.StatusCode}");
    Console.WriteLine($"Error details: {ex.ErrorDetails}");
}

API Coverage

This library provides comprehensive coverage of the Halo PSA API, organized into logical groups. For complete API endpoint documentation, refer to the official API documentation.

PSA Module (client.Psa)

• Tickets - Full CRUD operations, filtering, actions, and workflow
• Users - User management, authentication, and permissions
• Clients - Client and site management
• Assets - Asset tracking and configuration management
• Projects - Project management and time tracking
• Reports - Reporting and analytics

ServiceDesk Module (client.ServiceDesk)

• Knowledge Base - Article management and search
• Service Catalog - Service requests and approvals
• Assets - IT asset management
• Workflows - Custom workflows and automation

System Module (client.System)

• Configuration - System settings and customization
• Integration - Third-party system integrations
• Audit - Audit logs and activity tracking

Configuration Options

The HaloClientOptions class provides extensive configuration:

public class HaloClientOptions
{
    // Required authentication
    public required string HaloAccount { get; init; }
    public required string HaloClientId { get; init; }
    public required string HaloClientSecret { get; init; }
    
    // Optional configuration
    public string? BaseUrl { get; init; } = null;  // Uses default Halo cloud URL
    public TimeSpan RequestTimeout { get; init; } = TimeSpan.FromSeconds(30);
    public int MaxRetryAttempts { get; init; } = 3;
    public TimeSpan RetryDelay { get; init; } = TimeSpan.FromSeconds(1);
    public ILogger? Logger { get; init; } = null;
    
    // Advanced options
    public bool EnableRequestLogging { get; init; } = false;
    public bool EnableResponseLogging { get; init; } = false;
    public Dictionary<string, string> DefaultHeaders { get; init; } = [];
    public bool UseExponentialBackoff { get; init; } = true;
    public TimeSpan MaxRetryDelay { get; init; } = TimeSpan.FromSeconds(30);
}

API Reference

For detailed API endpoint documentation, parameters, and response formats, please refer to the official resources:

• 📖 Halo API Documentation - Complete API reference
• 🔐 Authentication Guide - How to obtain and use API credentials
• 🌐 Halo Service Desk - Official product documentation

Contributing

We welcome contributions from the community! Here's how you can help:

Development Setup

1. Clone the repository:

   git clone https://github.com/panoramicdata/HaloPSA.Api.git
   cd HaloPSA.Api
   

2. Install .NET 9 SDK: Download from dotnet.microsoft.com

3. Set up User Secrets for testing:

   cd Halo.Api.Test
   dotnet user-secrets init
   dotnet user-secrets set "HaloApi:HaloAccount" "your-test-account"
   dotnet user-secrets set "HaloApi:HaloClientId" "your-test-client-id"
   dotnet user-secrets set "HaloApi:HaloClientSecret" "your-test-client-secret"
   

4. Build and test:

   dotnet build
   dotnet test
   

Coding Standards

• Follow the project's coding standards as defined in copilot-instructions.md
• Use modern C# patterns (primary constructors, collection expressions, etc.)
• Maintain zero warnings policy - all code must compile without warnings
• Write comprehensive tests - both unit and integration tests
• Document public APIs - use XML documentation comments

Pull Request Process

1. Fork the repository and create a feature branch
2. Follow the implementation plan in Specification/ImplementationPlan.md
3. Write tests for all new functionality
4. Ensure all tests pass including integration tests
5. Update documentation as needed
6. Submit a pull request with a clear description of changes

Issue Reporting

When reporting issues:

• Use the issue templates provided in the repository
• Include minimal reproduction code when possible
• Specify the library version and .NET version
• Include relevant error messages and stack traces

Development Guidelines

• API-First Approach: All new endpoints should be defined in interfaces first
• Test-Driven Development: Write tests before implementing functionality
• Documentation: Update both XML docs and README examples
• Performance: Consider performance implications of new features
• Backward Compatibility: Maintain compatibility when possible

Support

• Official Documentation: Halo API Docs
• GitHub Issues: Report Issues
• GitHub Discussions: Community Support
• Halo Support: Contact Halo Service Desk for API access and account issues

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright

Copyright © 2025 Panoramic Data Limited. All rights reserved.

Changelog

See CHANGELOG.md for a detailed history of changes and releases