Update-TaskCustomField.ps1

<#
    .SYNOPSIS
        Updates the task custom field on Zendesk tickets based on phrase similarity.

    .DESCRIPTION
        Loads task definitions from a JSON file, discovers the custom field that stores the task reference, and processes each ticket. For each ticket, it extracts tokens from the subject and description, computes Jaccard similarity against task names/keywords, and updates the custom field with the best‑matching task ID when the similarity exceeds the threshold.

    .PARAMETER Tickets
        Array of ticket objects as returned by Get-CommonTaskTickets.

    .PARAMETER CustomObjectsPath
        Path to the custom‑objects.json file containing task definitions. Defaults to the script directory.

    .PARAMETER TaskFieldName
        Name (or part of the title) of the custom field that stores the task reference. Defaults to "Task".

    .PARAMETER SimilarityThreshold
        Minimum Jaccard similarity (0‑1) required to consider a task a match. Default is 0.35.

    .NOTES
        Requires Zendesk environment variables: ZendeskUrl, ZendeskEmail, ZendeskApiToken.
#>
function Update-TaskCustomField {
  [CmdletBinding()]
  param (
    # Array of ticket objects (as returned by Get-CommonTaskTickets)
    [Parameter(Mandatory = $true)]
    [array]$Tickets,
    # Path to the custom-objects.json file containing task definitions
    [string]$CustomObjectsPath = "${PSScriptRoot}\custom-objects.json",
    # Name (or part of title) of the custom field that stores the task reference
    [string]$TaskFieldName = "Task",
    # Similarity threshold (0-1) for matching phrases to a task
    [double]$SimilarityThreshold = 0.35
  )

  # Ensure environment variables are present
  Test-ZendeskEnvironment

  # ---------------------------------------------------------------
  # 1. Load task definitions from custom-objects.json
  # ---------------------------------------------------------------
  if (-not (Test-Path $CustomObjectsPath)) {
    Write-Error "Custom objects file not found at $CustomObjectsPath"
    return
  }
  $customObjects = Get-Content $CustomObjectsPath -Raw | ConvertFrom-Json
  # Expect an array of objects with at least id, name, and optional keywords (array of strings)
  $tasks = @{}
  foreach ($obj in $customObjects) {
    if ($obj.type -eq 'task') {
      $tasks[$obj.id] = @{
        Name     = $obj.name
        Keywords = if ($obj.PSObject.Properties.Name -contains 'keywords') { $obj.keywords } else { @() }
      }
    }
  }
  if ($tasks.Count -eq 0) {
    Write-Error "No task objects found in $CustomObjectsPath"
    return
  }

  # ---------------------------------------------------------------
  # 2. Discover the custom field ID that stores the task reference
  # ---------------------------------------------------------------
  $fieldsResponse = Invoke-ZendeskApiCall -UriPath "api/v2/ticket_fields.json" -Method 'GET'
  $fieldsJson = $fieldsResponse.Content | ConvertFrom-Json
  $taskField = $fieldsJson.ticket_fields | Where-Object {
    $_.type -eq 'custom' -and ($_.title -like "*$TaskFieldName*" -or $_.raw_title -like "*$TaskFieldName*")
  } | Select-Object -First 1
  if (-not $taskField) {
    Write-Error "Could not locate a custom field matching name '$TaskFieldName'."
    return
  }
  $taskFieldId = $taskField.id
  Write-Verbose "Discovered task custom field ID $taskFieldId"

  # ---------------------------------------------------------------
  # 3. Process each ticket
  # ---------------------------------------------------------------
  foreach ($ticket in $Tickets) {
    # Combine subject and description for phrase extraction
    $text = @($ticket.subject, $ticket.description) -join " "
    $tokens = $text.ToLower() -replace "[^a-z0-9]+", " " -split " "
    $tokens = $tokens | Where-Object { $_ }
    # Build a set of unique tokens for Jaccard comparison
    $ticketTokenSet = [System.Collections.Generic.HashSet[string]]::new()
    foreach ($t in $tokens) { $null = $ticketTokenSet.Add($t) }

    $bestMatchId = $null
    $bestScore = 0
    foreach ($taskId in $tasks.Keys) {
      $taskInfo = $tasks[$taskId]
      $taskTokens = @()
      if ($taskInfo.Keywords.Count -gt 0) {
        $taskTokens = $taskInfo.Keywords
      }
      else {
        $taskTokens = $taskInfo.Name -split " "
      }
      $taskTokenSet = [System.Collections.Generic.HashSet[string]]::new()
      foreach ($tk in $taskTokens) { $null = $taskTokenSet.Add($tk.ToLower()) }
      # Jaccard similarity
      $intersection = [System.Collections.Generic.HashSet[string]]::new($ticketTokenSet)
      $intersection.IntersectWith($taskTokenSet)
      $union = [System.Collections.Generic.HashSet[string]]::new($ticketTokenSet)
      $union.UnionWith($taskTokenSet)
      $score = if ($union.Count -gt 0) { $intersection.Count / $union.Count } else { 0 }
      if ($score -gt $bestScore) {
        $bestScore = $score
        $bestMatchId = $taskId
      }
    }

    if ($bestMatchId -and $bestScore -ge $SimilarityThreshold) {
      Write-Verbose "Ticket $($ticket.id) matched task $bestMatchId (score $([math]::Round($bestScore,2)))"
      # Build body to update the custom field
      $body = @{
        ticket = @{
          custom_fields = @(
            @{ id = $taskFieldId; value = $bestMatchId }
          )
        }
      } | ConvertTo-Json -Depth 10
      try {
        Invoke-ZendeskApiCall -UriPath "api/v2/tickets/$($ticket.id).json" -Method 'PUT' -Body $body
        Write-Host "Updated ticket $($ticket.id) with task $bestMatchId" -ForegroundColor Green
      }
      catch {
        Write-Error "Failed to update ticket $($ticket.id): $_"
      }
    }
    else {
      Write-Verbose "Ticket $($ticket.id) did not meet similarity threshold (best $([math]::Round($bestScore,2)))"
    }
  }
}