Freshdesk SLA Breach Sentinel

id: freshdesk-sla-breach-sentinel
namespace: company.team
description: |
  On a schedule, read recent tickets from the Freshdesk API (read-only:
  no ticket is replied to, updated or closed) and classify SLA health as
  HEALTHY, WARNING, CRITICAL or UNREACHABLE. Log quiet runs and alert
  Slack when open tickets are past their resolution or first-response
  due time, and page when a high or urgent ticket has breached.

inputs:
  - id: lookback_days
    type: INT
    defaults: 30
    displayName: "Lookback Window (days)"
    description: "Read tickets updated in this many days. Without a window Freshdesk
      only returns tickets created in the last 30 days."

triggers:
  - id: sla_check
    type: io.kestra.plugin.core.trigger.Schedule
    description: Check SLA health every 30 minutes during working hours (Monday to
      Saturday, 09:00 to 19:00 IST). Shipped disabled; enable it once the
      Freshdesk secrets are set and a manual run has been verified.
    cron: "*/30 9-19 * * 1-6"
    timezone: Asia/Kolkata
    disabled: true

tasks:
  - id: list_tickets
    type: io.kestra.plugin.core.http.Request
    description: Read up to 100 tickets updated in the lookback window, earliest due
      first. This is a GET; no ticket is changed.
    uri: "https://{{ secret('FRESHDESK_DOMAIN')
      }}.freshdesk.com/api/v2/tickets?per_page=100&order_by=due_by&order_type=a\
      sc&updated_since={{ now() | dateAdd(-inputs.lookback_days, 'DAYS') |
      date(\"yyyy-MM-dd'T'HH:mm:ss'Z'\", timeZone=\"UTC\") }}"
    method: GET
    options:
      auth:
        type: BASIC
        username: "{{ secret('FRESHDESK_API_KEY') }}"
        password: "X"
      allowFailed: true
      timeout:
        connectTimeout: PT10S
        readIdleTimeout: PT30S
    retry:
      type: constant
      interval: PT10S
      maxAttempts: 3
    allowFailure: true

  - id: summarize_sla
    type: io.kestra.plugin.core.debug.Return
    description: Keep tickets that are still Open (2) or Pending (3), count those
      past their resolution due time and those whose first response was
      escalated, count how many of the breached ones are High or Urgent, and
      classify in one jq query. A missing or non-200 response becomes
      UNREACHABLE instead of looking healthy.
    format: >-
      {{ (outputs.list_tickets.code is not defined or outputs.list_tickets.code
      != 200) ?
      '{"status":"UNREACHABLE","open":0,"resolution_breached":0,"first_response_breached":0,"high_urgent_breached":0,"oldest_breach":"none"}'
      : (fromJson(outputs.list_tickets.body) | jq(' "' ~ (now() |
      date("yyyy-MM-dd'T'HH:mm:ss'Z'", timeZone="UTC")) ~ '" as $now | [.[] |
      select(.status == 2 or .status == 3)] as $o | [$o[] | select(.due_by !=
      null and .due_by < $now)] as $r | [$o[] | select(.fr_escalated == true)]
      as $fr | ([$r[], $fr[]] | unique_by(.id)) as $b | ([$b[] |
      select(.priority >= 3)] | length) as $hu | {open: ($o | length),
      resolution_breached: ($r | length), first_response_breached: ($fr |
      length), high_urgent_breached: $hu, oldest_breach: (if ($r | length) == 0
      then "none" else ($r | sort_by(.due_by) | first | ("#" + (.id | tostring)
      + " due " + .due_by)) end), status: (if $hu > 0 then "CRITICAL" elif ($b |
      length) > 0 then "WARNING" else "HEALTHY" end)} ') | first | toJson) }}

  - id: route_by_sla_state
    type: io.kestra.plugin.core.flow.Switch
    description: Route to a quiet log when no open ticket is past its due time, a
      Slack message when low or medium tickets have breached, or a Slack page
      when a high or urgent ticket has breached or Freshdesk could not be read.
    value: "{{ fromJson(outputs.summarize_sla.value).status }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          message: "Freshdesk SLA healthy: {{ fromJson(outputs.summarize_sla.value).open
            }} open or pending ticket(s), none past due."
      "WARNING":
        - id: alert_warning_breach
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Post a Slack message when low or medium priority tickets are past
            their resolution due time or had their first response escalated.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Freshdesk SLA WARNING: {{ fromJson(outputs.summarize_sla.value).resolution_breached }} open ticket(s) past resolution due time and {{ fromJson(outputs.summarize_sla.value).first_response_breached }} with first response breached. Oldest: {{ fromJson(outputs.summarize_sla.value).oldest_breach }}. Execution {{ execution.id }}."
            }
      "CRITICAL":
        - id: alert_critical_breach
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when at least one High or Urgent ticket has breached its
            SLA.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Freshdesk SLA CRITICAL: {{ fromJson(outputs.summarize_sla.value).high_urgent_breached }} High or Urgent ticket(s) have breached SLA ({{ fromJson(outputs.summarize_sla.value).resolution_breached }} past resolution due, {{ fromJson(outputs.summarize_sla.value).first_response_breached }} first response breached). Oldest: {{ fromJson(outputs.summarize_sla.value).oldest_breach }}. Execution {{ execution.id }}."
            }
      "UNREACHABLE":
        - id: alert_unreachable_api
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when the Tickets API could not be read, indicating an
            outage, a wrong domain or an invalid API key.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Freshdesk SLA sentinel UNREACHABLE: the Tickets API did not return a usable response (HTTP {{ outputs.list_tickets.code ?? 'no response' }}). Check the domain and API key. Execution {{ execution.id }}."
            }
    defaults:
      - id: log_unclassified
        type: io.kestra.plugin.core.log.Log
        message: "Freshdesk SLA sentinel completed with an unexpected classification: {{
          outputs.summarize_sla.value }}."

  - id: log_audit_result
    type: io.kestra.plugin.core.log.Log
    description: Record one audit line for every run, whichever branch fired, so SLA
      history stays queryable even if Slack delivery fails.
    message: "Freshdesk SLA sentinel audit: lookback_days={{ inputs.lookback_days }}
      http={{ outputs.list_tickets.code ?? 'n/a' }} summary={{
      outputs.summarize_sla.value }} execution={{ execution.id }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alert Slack when the sentinel flow itself fails, so a broken check
      is never mistaken for a healthy queue.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {
        "text": "Freshdesk SLA sentinel flow {{ flow.id }} FAILED (execution {{ execution.id }}). SLA status is now unknown; check the task logs and the Freshdesk ticket views."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ fromJson(outputs.summarize_sla.value).status }}"