Go SDK for Nexthink API

A community Go client library for the Nexthink API.

Quick Start

Get started quickly with the SDK using the Quick Start Guide, which includes:

• Installation instructions
• Your first API call
• Common operations (NQL queries, workflows, remote actions)
• Error handling patterns
• Response metadata access
• Links to configuration guides for production use

Examples

The examples directory contains complete working examples for all SDK features:

Client Configuration

• Basic Client Creation
• Client with Structured Logging

NQL (Nexthink Query Language)

Basic Operations

• Execute NQL Query V1
• Execute NQL Query V2
• Start NQL Export
• Get NQL Export Status
• Wait for NQL Export (Full Workflow)

Advanced Features

• Query Builder - Fluent API for building NQL queries
• Templates - Pre-built queries for common scenarios
• Result Set Processing - Type-safe data access and transformations
• Export Workflow - Simplified large data exports
• Comprehensive Example - Full-featured example combining all enhancements

Workflows

• Trigger Workflow V1
• Trigger Workflow V2
• List Workflows
• Get Workflow Details

Remote Actions

• Trigger Remote Action
• List Remote Actions
• Get Remote Action Details

Enrichment

• Enrich Fields

Campaigns

• Trigger Campaign

Each example includes a complete main.go with comments explaining the code.

SDK Services

Core Query and Data Services

• NQL (Nexthink Query Language): Execute NQL queries, start and monitor data exports
  • V1 and V2 query execution
  • Asynchronous export operations with status tracking
  • Automatic waiting and polling for export completion
  • Query Builder: Fluent API for programmatic query construction
  • Query Templates: Pre-built queries for common scenarios
  • Result Sets: Type-safe data access and transformation helpers
  • Export Workflow: Simplified large data exports with progress tracking
  • Data Model Constants: Type-safe constants for tables, fields, and values
  • Query Validation: Client-side validation before API execution
  • Metadata Extraction: Detailed execution and performance metrics

Automation and Orchestration

• Workflows: Trigger and manage Nexthink workflows

  • V1 and V2 workflow execution
  • List available workflows
  • Get detailed workflow information

• Remote Actions: Execute remote actions on endpoints

  • Trigger remote actions with parameters
  • List available remote actions
  • Get remote action details and schemas

Data Enrichment and User Engagement

• Enrichment: Enrich Nexthink data with custom fields

  • Add custom device and user metadata
  • Update existing enrichment data

• Campaigns: Send targeted campaigns to users

  • Trigger campaigns with custom parameters
  • Multi-user campaign execution
  • Track campaign request status per user

NQL Enhancements

The SDK includes comprehensive enhancements for working with NQL (Nexthink Query Language):

Query Builder

Build NQL queries programmatically with a type-safe fluent API:

import "github.com/deploymenttheory/go-api-sdk-nexthink/nexthink/services/nql"

// Build a query using method chaining
query := nql.NewQueryBuilder().
    FromDevices().
    DuringPast(7, nql.Days).
    With("execution.crashes during past 7d").
    WhereEquals("binary.name", "outlook.exe").
    ComputeSum("total_crashes", "number_of_crashes").
    List("device.name", "total_crashes").
    SortDesc("total_crashes").
    Limit(20).
    Build()

// Validate before use
if err := qb.Validate(); err != nil {
    log.Fatal(err)
}

Query Templates

Use pre-built query templates for common scenarios:

templates := nql.NewTemplates()

// Get devices with crashes
query := templates.DevicesWithCrashes("during past 7d", "outlook.exe")

// Analyze DEX scores by platform
query := templates.DEXScoreByPlatform("during past 24h")

// Find users with low DEX scores
query := templates.UsersWithLowDEXScore(50, "during past 24h")

Result Set Processing

Process query results with type-safe helpers:

// Execute query
result, apiResp, err := nqlService.ExecuteNQLV2(ctx, req)

// Create result set
resultSet := nql.NewV2ResultSet(result)

// Type-safe data access
deviceName, err := resultSet.GetString(0, "device.name")
crashCount, err := resultSet.GetInt(0, "total_crashes")

// Iterate through results
resultSet.IterateRows(func(row int, data map[string]any) error {
    fmt.Printf("Device: %v\n", data)
    return nil
})

// Filter and transform
windowsDevices := resultSet.Filter(func(row map[string]any) bool {
    platform, _ := row["operating_system.platform"].(string)
    return platform == "Windows"
})

// Convert to JSON
jsonData, _ := resultSet.ToJSON()

Export Workflow

Simplified workflow for large data exports:

// Simple CSV export
result, err := nqlService.ExportToCSV(ctx, "#large_query")
os.WriteFile("export.csv", result.Data, 0644)

// Export with progress tracking
opts := nql.DefaultExportOptions().
    WithPollInterval(5 * time.Second).
    WithTimeout(15 * time.Minute).
    WithOnProgress(func(status string, elapsed time.Duration) {
        fmt.Printf("[%v] %s\n", elapsed, status)
    })

result, err := nqlService.ExportWorkflow(ctx, req, opts)
fmt.Printf("Exported %s in %v\n", result.SizeFormatted(), result.TotalDuration)

Data Model Constants

Use constants for type-safe query construction:

// Table constants
nql.TableDevices              // "devices"
nql.TableExecutionCrashes     // "execution.crashes"
nql.TableWebErrors            // "web.errors"

// Field constants
nql.FieldDeviceName           // "device.name"
nql.FieldOSPlatform           // "operating_system.platform"
nql.FieldHardwareType         // "hardware.type"

// Value constants
nql.PlatformWindows           // "Windows"
nql.HardwareTypeLaptop        // "laptop"
nql.ExperienceLevelGood       // "good"

// Time selection helpers
nql.Past7Days                 // "during past 7d"
nql.Past24Hours               // "during past 24h"

Comprehensive Documentation

• NQL Query Building Guide - Complete guide to the query builder
• NQL Result Processing Guide - Working with query results
• NQL Export Workflow Guide - Large data exports
• NQL Templates Guide - Pre-built query templates
• NQL Best Practices Guide - Optimization and patterns
• NQL API Reference - Complete API reference

HTTP Client Configuration

The SDK includes a powerful HTTP client with production-ready configuration options:

• Authentication - OAuth2 token management with automatic refresh
• Timeouts & Retries - Configurable timeouts and automatic retry logic
• TLS/SSL Configuration - Custom certificates, mutual TLS, and security settings
• Proxy Support - HTTP/HTTPS/SOCKS5 proxy configuration
• Custom Headers - Global and per-request header management
• Structured Logging - Integration with zap for production logging
• OpenTelemetry Tracing - Distributed tracing and observability
• Debug Mode - Detailed request/response inspection

Configuration Options

The SDK client supports extensive configuration through functional options. Below is the complete list of available configuration options grouped by category.

Basic Configuration

client.WithAPIVersion("v1")              // Set API version
client.WithBaseURL("https://...")        // Custom base URL
client.WithTimeout(30*time.Second)       // Request timeout
client.WithRetryCount(3)                 // Number of retry attempts

TLS/Security

client.WithMinTLSVersion(tls.VersionTLS12)                    // Minimum TLS version
client.WithTLSClientConfig(tlsConfig)                         // Custom TLS configuration
client.WithRootCertificates("/path/to/ca.pem")                // Custom CA certificates
client.WithRootCertificateFromString(caPEM)                   // CA certificate from string
client.WithClientCertificate("/path/cert.pem", "/path/key.pem") // Client certificate (mTLS)
client.WithClientCertificateFromString(certPEM, keyPEM)       // Client cert from string
client.WithInsecureSkipVerify()                               // Skip cert verification (dev only!)

Network

client.WithProxy("http://proxy:8080")    // HTTP/HTTPS/SOCKS5 proxy
client.WithTransport(customTransport)    // Custom HTTP transport

Headers

client.WithUserAgent("MyApp/1.0")                      // Set User-Agent header
client.WithCustomAgent("MyApp", "1.0")                 // Custom agent with version
client.WithGlobalHeader("X-Custom-Header", "value")    // Add single global header
client.WithGlobalHeaders(map[string]string{...})       // Add multiple global headers

Observability

client.WithLogger(zapLogger)            // Structured logging with zap
client.WithTracing(otelConfig)          // OpenTelemetry distributed tracing
client.WithDebug()                      // Enable debug mode (dev only!)

Example: Production Configuration

import (
    "crypto/tls"
    "time"
    "go.uber.org/zap"
    "github.com/deploymenttheory/go-api-sdk-nexthink/nexthink/client"
)

logger, _ := zap.NewProduction()

// Initialize client with OAuth2 credentials
apiClient, err := client.NewClient(
    "your-client-id",
    "your-client-secret",
    "your-instance",      // e.g., "company"
    "us",                 // Region: "us" or "eu"
    client.WithTimeout(30*time.Second),
    client.WithRetryCount(3),
    client.WithLogger(logger),
    client.WithMinTLSVersion(tls.VersionTLS12),
    client.WithGlobalHeader("X-Application-Name", "MyITApp"),
)
if err != nil {
    logger.Fatal("Failed to create Nexthink client", zap.Error(err))
}

// Access services
nqlService := apiClient.NQL()
workflowsService := apiClient.Workflows()
remoteActionsService := apiClient.RemoteActions()

See the configuration guides for detailed documentation on each option.

Documentation

• Nexthink API Documentation
• GoDoc

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting pull requests.

License

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

Support

• Issues: GitHub Issues
• Documentation: API Docs

Disclaimer

This is an unofficial SDK and is not affiliated with or endorsed by Nexthink.