Developer Handover Pack

Developer Handover Pack

IT Helpdesk Request Handling

Reads the raw text of each incoming IT support request and applies a structured classification and priority score. The agent evaluates category keywords (hardware, software, access, general) and severity signals (business impact phrases, user count, affected system type) to assign a category and a P1 to P4 priority tier without any human input. It then creates a fully pre-filled ticket in Freshdesk so no manual data entry is required. Estimated build time: 16 hours. Complexity: Complex.

// Input
request_text: string          // raw body from email, form, or Slack message
requester_email: string       // sender address from Gmail or Slack user profile
requester_name: string        // display name resolved from Slack or Gmail header
source_channel: enum          // 'email' | 'slack' | 'form'
received_at: ISO8601          // timestamp of original submission

// Classification logic
category: enum                // 'hardware' | 'software' | 'access' | 'general'
priority: enum                // 'P1' | 'P2' | 'P3' | 'P4'
confidence_score: float       // 0.0–1.0; tickets below 0.7 flagged for IT Manager review

// Output
freshdesk_ticket_id: string   // e.g. 'TKT-00412'
freshdesk_ticket_url: string  // direct link to the created ticket
category: enum                // confirmed category written to Freshdesk custom field
priority: enum                // P1–P4 written to Freshdesk priority field
status: 'open'               // ticket status on creation

Triggered the moment the Triage and Priority Agent creates a classified ticket in Freshdesk. The agent queries the Freshdesk API to retrieve each technician's current open ticket count and assigns the new ticket to the technician with the lowest open count who is tagged for the relevant category. It then fires two Slack messages: one to the requester confirming their ticket details, and one to the assigned technician with a summary and a direct Freshdesk link. Estimated build time: 10 hours. Complexity: Moderate.

// Input
freshdesk_ticket_id: string   // from Triage and Priority Agent output
category: enum                // 'hardware' | 'software' | 'access' | 'general'
priority: enum                // P1–P4
requester_email: string
requester_name: string

// Assignment logic
technician_pool: array        // filtered by category skill tag in Freshdesk
open_ticket_counts: map       // { technician_id: integer } from Freshdesk API
assigned_technician_id: string // technician with lowest open count in pool

// Output
freshdesk_ticket_id: string   // ticket updated with assignee
assigned_technician_name: string
assigned_technician_slack_id: string
requester_slack_dm_ts: string // Slack message timestamp for requester DM
technician_slack_dm_ts: string // Slack message timestamp for technician DM

// On tie in workload
// If two technicians share the lowest open count, assign to the one
// whose last assignment timestamp is older (round-robin fallback).

Runs on two separate triggers. First, it polls open P1 and P2 Freshdesk tickets on a scheduled interval and fires a PagerDuty alert when any P1 or P2 ticket has exceeded its SLA response window without a status change. Second, it listens for the Freshdesk ticket.resolved webhook event and writes a structured resolution entry to the Notion knowledge base, including the category, resolution summary, and fix steps. Estimated build time: 12 hours. Complexity: Moderate.

// Input (SLA breach path)
freshdesk_ticket_id: string
priority: 'P1' | 'P2'
created_at: ISO8601
last_updated_at: ISO8601
sla_response_due_at: ISO8601  // from Freshdesk SLA policy field
current_status: string        // 'open' | 'pending'

// Output (SLA breach path)
pagerduty_event_action: 'trigger'
pagerduty_severity: 'critical' | 'error'  // P1 -> critical, P2 -> error
pagerduty_summary: string     // 'P1 ticket TKT-00412 breached SLA by 47 min'
pagerduty_dedup_key: string   // freshdesk_ticket_id to prevent duplicate alerts

// Input (resolution path)
freshdesk_ticket_id: string
category: enum
resolution_notes: string      // technician notes from Freshdesk ticket body
resolved_by: string           // technician name
resolved_at: ISO8601

// Output (resolution path)
notion_page_id: string        // newly created knowledge base entry
notion_page_url: string
kb_entry: {
  category: enum,
  issue_summary: string,      // first 200 chars of original request
  resolution_steps: string,   // extracted or summarised from resolution_notes
  resolved_by: string,
  resolved_at: ISO8601
}

// ─── TRIGGER ───────────────────────────────────────────────────────────────
// An employee submits an IT support request via one of three channels.

SOURCE: Google Workspace shared inbox  ->  Gmail API watch (push notification)
  fields: message_id, from_email, subject, body_text, received_at

SOURCE: Slack slash command (/it-request)  ->  Slack Events API callback
  fields: user_id, user_email, command_text, team_id, received_at

SOURCE: Web intake form  ->  webhook POST to automation platform endpoint
  fields: requester_name, requester_email, issue_description, submitted_at

// Normalise all three sources to a shared payload before passing to Agent 1:
normalised_request: {
  request_text: string,
  requester_email: string,
  requester_name: string,
  source_channel: 'email' | 'slack' | 'form',
  received_at: ISO8601
}

// ─── AGENT 1: Triage and Priority Agent ───────────────────────────────────
// Input: normalised_request

STEP 1.1  Deduplication check
  lookup: requester_email + category match within past 10 minutes
  if duplicate -> merge as note on existing ticket, halt workflow
  else -> proceed

STEP 1.2  Category classification
  keyword matching + severity signal scoring against category ruleset
  output: category ('hardware' | 'software' | 'access' | 'general')
          confidence_score (0.0–1.0)
  if confidence_score < 0.70 -> flag ticket for IT Manager review

STEP 1.3  Priority assignment
  P1: system down, multiple users affected, business-critical service
  P2: single user blocked, core tool unavailable
  P3: degraded performance, workaround available
  P4: general query, non-urgent request
  output: priority ('P1' | 'P2' | 'P3' | 'P4')

STEP 1.4  Freshdesk ticket creation
  POST /api/v2/tickets
  payload: { subject, description, email, category (custom_field),
             priority, source, status: 'open', tags: [source_channel] }
  output: freshdesk_ticket_id, freshdesk_ticket_url

// ─── HANDOFF: Agent 1 -> Agent 2 ──────────────────────────────────────────
// Freshdesk fires ticket.created webhook to automation platform endpoint.
// Payload passed forward:
//   freshdesk_ticket_id, category, priority,
//   requester_email, requester_name, freshdesk_ticket_url

// ─── AGENT 2: Assignment and Notification Agent ───────────────────────────
// Input: freshdesk_ticket_id, category, priority, requester_email, requester_name

STEP 2.1  Query technician workload
  GET /api/v2/tickets?filter=open&assignee_id={id} for each technician in pool
  filter pool by category skill tag
  output: open_ticket_counts map { technician_id: integer }

STEP 2.2  Assignment logic
  select technician with lowest open_ticket_count in category pool
  tie-break: oldest last_assignment_timestamp (round-robin)
  if all technicians >= overload_threshold (default 10) -> assign to IT Manager
  PUT /api/v2/tickets/{freshdesk_ticket_id}  { responder_id: assigned_technician_id }
  output: assigned_technician_id, assigned_technician_name, assigned_technician_slack_id

STEP 2.3  Notify requester via Slack DM
  Slack API: chat.postMessage  { channel: requester_slack_id }
  message fields: ticket_number, category, priority, assigned_technician_name,
                  estimated_response_time (derived from SLA config)
  output: requester_slack_dm_ts

STEP 2.4  Alert technician via Slack DM
  Slack API: chat.postMessage  { channel: assigned_technician_slack_id }
  message fields: ticket_number, issue_summary (first 200 chars),
                  priority, freshdesk_ticket_url
  output: technician_slack_dm_ts

// ─── PARALLEL BRANCH: SLA MONITORING (Agent 3, path A) ───────────────────
// Scheduled poll every 15 minutes. Runs independently of Agent 2 completion.

STEP 3A.1  Query open P1/P2 tickets
  GET /api/v2/tickets?filter=open&priority=1  (P1)
  GET /api/v2/tickets?filter=open&priority=2  (P2)
  output: list of { freshdesk_ticket_id, created_at, sla_response_due_at,
                    last_updated_at, current_status }

STEP 3A.2  SLA breach check
  for each ticket: if now() > sla_response_due_at and status in ('open','pending')
  -> breach confirmed

STEP 3A.3  PagerDuty escalation
  POST https://events.pagerduty.com/v2/enqueue
  payload: { routing_key, event_action: 'trigger',
             dedup_key: freshdesk_ticket_id,
             severity: P1->'critical' / P2->'error',
             summary: 'P{n} ticket {id} breached SLA by {elapsed} min' }
  output: pagerduty_dedup_key (stored to prevent re-alert on next poll cycle)

// ─── EVENT BRANCH: RESOLUTION (Agent 3, path B) ──────────────────────────
// Triggered by Freshdesk ticket.resolved webhook.

STEP 3B.1  Receive resolution event
  fields: freshdesk_ticket_id, category, resolution_notes, resolved_by,
          resolved_at
  if resolution_notes is empty -> write placeholder + send Slack prompt
                                  to resolved_by technician

STEP 3B.2  Write Notion knowledge base entry
  POST https://api.notion.com/v1/pages
  parent: { database_id: KB_DATABASE_ID }
  properties: {
    'Category':          { select: { name: category } },
    'Issue Summary':     { title: [{ text: { content: issue_summary } }] },
    'Resolution Steps':  { rich_text: [{ text: { content: resolution_steps } }] },
    'Resolved By':       { rich_text: [{ text: { content: resolved_by } }] },
    'Resolved At':       { date: { start: resolved_at } }
  }
  output: notion_page_id, notion_page_url

// ─── END OF FLOW ──────────────────────────────────────────────────────────