Items Field Inspection & Bulk Updates

PowerShell utilities for inspecting Items API fields and performing bulk updates via HaloPSA API.

Overview

These scripts provide field-level inspection and bulk update capabilities for the Items (Inventory) module. Useful for troubleshooting, data cleanup, and mass modifications.

⚠️ CRITICAL: Pagination Requirement

The HaloPSA Items API requires pageinate=true parameter for pagination to function.

Without this parameter, the API will:

• Ignore page_no and page_size parameters
• Return only the first ~1,000 items regardless of page number
• Return identical results on all page requests
• Provide no error or warning

Required Query Format

# CORRECT - Pagination enabled
$itemsUrl = "$apiUrl/Item?pageinate=true&page_no=$page&page_size=$pageSize"

# WRONG - Pagination disabled (parameters ignored)
$itemsUrl = "$apiUrl/Item?page_no=$page&page_size=$pageSize"

Impact

If you omit pageinate=true:

• Scripts will only process the first ~1,000 items
• Remaining items will never be retrieved or updated
• API provides no indication of missing data
• Updates will appear successful but be incomplete

Always verify total item counts match expected values after bulk operations.

Verification Test

# Test pagination is working
$testUrl = "$apiUrl/Item?pageinate=true&page_no=2&page_size=100"
$response = Invoke-RestMethod -Uri $testUrl -Headers $headers -Method Get

# Page 2 should have different items than page 1
Write-Host "Page 2 items: $($response.items.Count)"
Write-Host "First item ID: $($response.items[0].id)"

If first item ID on page 2 is 101 (not 1), pagination is working correctly.

Field Inspection Script

Query all fields available on an Item record to identify field names, types, and current values.

Use Cases

• Discover field names before writing update scripts
• Troubleshoot missing or unexpected data
• Verify field types for API payload construction
• Document available fields for integration work

Script

<#
.SYNOPSIS
    HaloPSA Items - Field Inspector
.DESCRIPTION
    Queries Items API and displays all available fields with types and values
#>

# Configuration
$tenant = 'your_tenant'
$clientId = 'your_client_id'
$clientSecret = 'your_client_secret'

$authUrl = "https://$tenant.halopsa.com/auth/token"
$apiUrl = "https://$tenant.halopsa.com/api"

# Authenticate
$tokenBody = @{
    grant_type = 'client_credentials'
    client_id = $clientId
    client_secret = $clientSecret
    scope = 'read:items'
}

$token = Invoke-RestMethod -Uri $authUrl -Method Post -Body $tokenBody
$headers = @{
    Authorization = "Bearer $($token.access_token)"
    'Content-Type' = 'application/json'
}

# Query Items with detailed fields
$itemsUrl = "$apiUrl/Item?page_size=5&includedetails=true"
$response = Invoke-RestMethod -Uri $itemsUrl -Headers $headers -Method Get

# Display field information
foreach ($item in $response.items) {
    Write-Host "`n=== Item ID: $($item.id) - $($item.name) ===" -ForegroundColor Cyan
    
    $item.PSObject.Properties | ForEach-Object {
        $fieldName = $_.Name
        $fieldValue = $_.Value
        $fieldType = $_.TypeNameOfValue
        
        Write-Host "$fieldName" -NoNewline -ForegroundColor Yellow
        Write-Host " [$fieldType]" -NoNewline -ForegroundColor Gray
        Write-Host " = $fieldValue" -ForegroundColor White
    }
}

# Save raw JSON for detailed inspection
$response | ConvertTo-Json -Depth 10 | Out-File "items_fields_raw.json"
Write-Host "`nRaw JSON saved to: items_fields_raw.json" -ForegroundColor Green

Key Parameters

Parameter	Description
includedetails=true	Returns all fields including custom fields
page_size	Number of items to return (use small number for inspection)

Example Output

=== Item ID: 363 - MNT-135 ===
id [Int32] = 363
name [String] = MNT-135
description [String] = Tilting Wall Mount
template_id [Int32] = 88
item_type_id [Int32] = 2
supplier_id [Int32] = 15
...

Bulk Update Script

Perform mass updates on Items records with dry-run mode, batch processing, and comprehensive logging.

Use Cases

• Clear template_id from all items
• Update pricing across inventory
• Reassign supplier relationships
• Bulk field modifications

Features

• Dry-run mode by default - Preview changes before execution
• Batch processing - Configurable batch sizes with rate limiting
• Progress tracking - Real-time percentage complete
• Error handling - Continues on failures, reports all errors
• Comprehensive logging - Full audit trail with timestamps

Script

<#
.SYNOPSIS
    HaloPSA Items - Bulk Update Template
.DESCRIPTION
    Bulk update Items with dry-run mode and comprehensive logging
    Modify the $updatePayload section for your specific use case
#>

$ErrorActionPreference = 'Continue'

# ============================================
# CONFIGURATION
# ============================================
$tenant = 'your_tenant'
$clientId = 'your_client_id'
$clientSecret = 'your_client_secret'

$batchSize = 10
$delayBetweenBatches = 500  # milliseconds
$dryRun = $true  # Set to $false to actually update

$authUrl = "https://$tenant.halopsa.com/auth/token"
$apiUrl = "https://$tenant.halopsa.com/api"

# ============================================
# LOGGING
# ============================================
$timestamp = Get-Date -Format 'yyyyMMdd_HHmmss'
$logFile = "BulkItemUpdate_$timestamp.log"

function Write-Log {
    param(
        [Parameter(Mandatory=$false)]
        [AllowEmptyString()]
        [string]$Message = '',
        
        [Parameter(Mandatory=$false)]
        [ValidateSet('Black','DarkBlue','DarkGreen','DarkCyan','DarkRed','DarkMagenta','DarkYellow','Gray','DarkGray','Blue','Green','Cyan','Red','Magenta','Yellow','White')]
        [string]$Color = 'White'
    )
    
    if ($Message -eq '') {
        Write-Host ''
        Add-Content -Path $logFile -Value ''
    } else {
        $logMessage = "$(Get-Date -Format 'HH:mm:ss') $Message"
        Write-Host $logMessage -ForegroundColor $Color
        Add-Content -Path $logFile -Value $logMessage
    }
}

Write-Log -Message "=== HaloPSA Bulk Item Update - Started ===" -Color Cyan
Write-Log -Message "Log file: $logFile" -Color Cyan
Write-Log

# ============================================
# AUTHENTICATE
# ============================================
Write-Log -Message 'Authenticating...' -Color Cyan
try {
    $tokenBody = @{
        grant_type = 'client_credentials'
        client_id = $clientId
        client_secret = $clientSecret
        scope = 'edit:items read:items'
    }
    
    $token = Invoke-RestMethod -Uri $authUrl -Method Post -Body $tokenBody -ErrorAction Stop
    $headers = @{
        Authorization = "Bearer $($token.access_token)"
        'Content-Type' = 'application/json'
    }
    Write-Log -Message '✓ Authentication successful' -Color Green
    Write-Log
} catch {
    Write-Log -Message '✗ Authentication failed' -Color Red
    Write-Log -Message "Error: $($_.Exception.Message)" -Color Red
    exit 1
}

# ============================================
# RETRIEVE ALL ITEMS
# ============================================
Write-Log -Message 'Retrieving items...' -Color Cyan
$allItems = @()
$page = 1
$pageSize = 100

try {
    do {
        $itemsUrl = "$apiUrl/Item?page_size=$pageSize&page_no=$page"
        $response = Invoke-RestMethod -Uri $itemsUrl -Headers $headers -Method Get -ErrorAction Stop
        
        if ($response.items) {
            $allItems += $response.items
        }
        
        $page++
        Start-Sleep -Milliseconds 200
        
    } while ($response.items -and $response.items.Count -eq $pageSize)
    
    Write-Log -Message "✓ Retrieved $($allItems.Count) total items" -Color Green
    Write-Log
} catch {
    Write-Log -Message '✗ Failed to retrieve items' -Color Red
    Write-Log -Message "Error: $($_.Exception.Message)" -Color Red
    exit 1
}

# ============================================
# FILTER ITEMS TO UPDATE
# ============================================
Write-Log -Message 'Filtering items...' -Color Cyan

# MODIFY THIS FILTER FOR YOUR USE CASE
$itemsToUpdate = $allItems | Where-Object { 
    $_.template_id -ne $null -and $_.template_id -ne 0 
}

if ($itemsToUpdate.Count -eq 0) {
    Write-Log -Message '✓ No items match filter criteria' -Color Green
    exit 0
}

Write-Log -Message "✓ Found $($itemsToUpdate.Count) items to update" -Color Yellow
Write-Log

# ============================================
# PREVIEW
# ============================================
Write-Log -Message "Preview - First 10 items:" -Color Cyan
for ($i = 0; $i -lt [Math]::Min(10, $itemsToUpdate.Count); $i++) {
    $item = $itemsToUpdate[$i]
    Write-Log -Message "  ID: $($item.id) | Name: $($item.name) | template_id: $($item.template_id)"
}
Write-Log

# ============================================
# CONFIRMATION
# ============================================
if ($dryRun) {
    Write-Log -Message '*** DRY RUN MODE ***' -Color Magenta
    $confirm = Read-Host 'Continue with dry run? (yes/no)'
} else {
    Write-Log -Message '*** LIVE MODE - WILL UPDATE ITEMS ***' -Color Red
    $confirm = Read-Host 'Type YES in capitals to confirm'
}

if ($confirm -ne 'yes' -and $confirm -ne 'YES') {
    Write-Log -Message 'Operation cancelled' -Color Yellow
    exit 0
}

# ============================================
# PROCESS UPDATES
# ============================================
Write-Log
Write-Log -Message "Processing updates..." -Color Cyan

$successCount = 0
$failCount = 0
$processedCount = 0
$totalCount = $itemsToUpdate.Count

for ($i = 0; $i -lt $totalCount; $i += $batchSize) {
    $batch = $itemsToUpdate[$i..[Math]::Min($i + $batchSize - 1, $totalCount - 1)]
    
    foreach ($item in $batch) {
        $processedCount++
        $percentComplete = [Math]::Round(($processedCount / $totalCount) * 100, 1)
        
        if ($dryRun) {
            Write-Log -Message "  [$processedCount/$totalCount ($percentComplete%)] DRY RUN: Would update ID $($item.id)" -Color Gray
            $successCount++
        } else {
            try {
                # MODIFY THIS PAYLOAD FOR YOUR USE CASE
                $updatePayload = @{
                    id = $item.id
                    template_id = 0
                }
                
                # Manual array wrapper - HaloPSA API requires array
                $updateBody = "[$($updatePayload | ConvertTo-Json -Depth 5 -Compress)]"
                
                $updateResult = Invoke-RestMethod -Uri "$apiUrl/Item" -Headers $headers -Method Post -Body $updateBody -ContentType 'application/json' -ErrorAction Stop
                
                Write-Log -Message "  [$processedCount/$totalCount ($percentComplete%)] ✓ Updated ID $($item.id)" -Color Green
                $successCount++
                
            } catch {
                Write-Log -Message "  [$processedCount/$totalCount ($percentComplete%)] ✗ FAILED ID $($item.id)" -Color Red
                $failCount++
            }
            
            Start-Sleep -Milliseconds 100
        }
    }
    
    if ($i + $batchSize -lt $totalCount) {
        Start-Sleep -Milliseconds $delayBetweenBatches
    }
}

# ============================================
# SUMMARY
# ============================================
Write-Log
Write-Log -Message "=== SUMMARY ===" -Color Cyan
if ($dryRun) {
    Write-Log -Message "DRY RUN: Items that would be updated: $successCount" -Color Yellow
} else {
    Write-Log -Message "Successfully updated: $successCount" -Color Green
    Write-Log -Message "Failed: $failCount" -Color $(if ($failCount -gt 0) { 'Red' } else { 'White' })
}
Write-Log -Message "Log saved to: $logFile" -Color Cyan

Critical API Requirements

Array Format: The Items API requires an array payload even for single updates:

# CORRECT - Array format
$updateBody = "[{\"id\":363,\"template_id\":0}]"

# WRONG - Single object
$updateBody = "{\"id\":363,\"template_id\":0}"

PowerShell's ConvertTo-Json strips array wrappers for single elements, so manual wrapping is required:

$updatePayload = @{ id = 363; template_id = 0 }
$updateBody = "[$($updatePayload | ConvertTo-Json -Compress)]"

Workflow

1. Test in dev environment first
2. Run dry-run - Review log file
3. Verify preview - Confirm correct items selected
4. Set $dryRun = $false
5. Run live update - Type YES to confirm
6. Verify in UI - Spot-check random items
7. Deploy to production - After dev verification

Authentication

All scripts require HaloPSA API credentials:

1. Configuration → Integrations → HaloPSA API → View Applications
2. Create application - Select "Services" authentication
3. Set permissions - read:items, edit:items
4. Copy Client ID and Client Secret - Secret shown only once
5. Update script configuration:
   • $tenant = Your HaloPSA subdomain (e.g., 'dtcdev')
   • $clientId = Application Client ID
   • $clientSecret = Application Client Secret

API Endpoints

Endpoint	Method	Purpose
/Item	GET	Retrieve items (supports pagination)
/Item/{id}	GET	Retrieve single item by ID
/Item	POST	Create or update items (array payload)

Query Parameters

Parameter	Description	Example
page_size	Items per page (max 100)	?page_size=50
page_no	Page number	?page_no=2
includedetails	Include all fields	?includedetails=true

Common Use Cases

Clear Project Template from All Items

$itemsToUpdate = $allItems | Where-Object { 
    $_.template_id -ne $null -and $_.template_id -ne 0 
}

$updatePayload = @{
    id = $item.id
    template_id = 0
}

Update Supplier for Specific Item Type

$itemsToUpdate = $allItems | Where-Object { 
    $_.item_type_id -eq 5  # Hardware
}

$updatePayload = @{
    id = $item.id
    supplier_id = 42
}

Bulk Price Update

$itemsToUpdate = $allItems | Where-Object {
    $_.name -like "MNT-*"  # All monitor mounts
}

$updatePayload = @{
    id = $item.id
    sell_price = $item.sell_price * 1.10  # 10% increase
}

Troubleshooting

Error: "Cannot deserialize...into type 'Item[]'"

Cause: JSON payload is not an array
Fix: Manually wrap payload in brackets: "[$json]"

Error: "Cannot bind parameter 'ForegroundColor'"

Cause: Write-Log function parameter parsing issue
Fix: Use named parameters: Write-Log -Message "text" -Color Green

Error: "Authentication failed"

Check:

• Client ID and Secret are correct
• API application has required permissions (read:items, edit:items)
• Tenant name is correct (no .halopsa.com suffix)
• API application is active in HaloPSA

Items not updating despite success message

Check:

• Verify in HaloPSA UI
• Check API response for errors
• Ensure field name is correct (use field inspector)
• Verify field type matches payload type

Best Practices

1. Always run dry-run first - Preview changes before execution
2. Test in dev environment - Before production deployment
3. Use small batch sizes - Avoid API rate limiting
4. Add delays between batches - 500ms recommended
5. Log everything - Timestamped logs for audit trail
6. Verify in UI - Spot-check after bulk updates
7. Keep backups - Export data before mass modifications

Related Documentation

• Items & Inventory Endpoints
• Items & Inventory Endpoints (cont.)
• HaloPSA API Authentication