Find inactive agents in Freshservice

#!/usr/bin/env python3
"""List Freshservice full-time agents with no activity or login for N days. Read-only.

Needs Python 3.9 or newer and no packages. Run it and paste an admin API key at the hidden prompt:

    python3 freshservice_idle_agents.py acme.freshservice.com --days 30 --price 49 --csv idle.csv

To skip the prompt, set FRESHSERVICE_API_KEY in the environment instead.
"""
import argparse
import base64
import csv
import getpass
import http.client
import json
import os
import re
import sys
import urllib.error
import urllib.request
from datetime import datetime, timezone

PAGE_SIZE = 100
MAX_PAGES = 50
HOST_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,62}\.freshservice\.com$")


class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, *args, **kwargs):
        return None


def parse_time(value):
    if not value:
        return None
    try:
        t = datetime.fromisoformat(re.sub(r"(\d:\d\d)\.\d+", r"\1", str(value)).replace("Z", "+00:00"))
    except ValueError:
        return None
    return t if t.tzinfo else t.replace(tzinfo=timezone.utc)


def whole_days(later, earlier):
    return int((later - earlier).total_seconds() // 86400)


def find_idle(agents, now, days):
    counts = {"agents": len(agents), "deactivated": 0, "occasional": 0, "full_time": 0, "unassessed": 0}
    idle = []
    for a in agents:
        if a.get("active") is False:
            counts["deactivated"] += 1
            continue
        if a.get("occasional") is True:
            counts["occasional"] += 1
            continue
        counts["full_time"] += 1
        name = " ".join(p for p in (a.get("first_name"), a.get("last_name")) if p).strip() or a.get("email") or "Agent %s" % a.get("id")
        row = {"id": a.get("id"), "name": name, "email": a.get("email") or ""}
        times = [t for t in (parse_time(a.get("last_active_at")), parse_time(a.get("last_login_at"))) if t]
        if times:
            last = max(times)
            idle_days = max(0, whole_days(now, last))
            if idle_days >= days:
                idle.append({**row, "last_seen": last.astimezone(timezone.utc).date().isoformat(), "days_idle": idle_days, "never_seen": False})
            continue
        created = parse_time(a.get("created_at"))
        if created is None:
            counts["unassessed"] += 1
        elif whole_days(now, created) >= days:
            idle.append({**row, "last_seen": "", "days_idle": None, "never_seen": True})
    idle.sort(key=lambda r: (not r["never_seen"], -(r["days_idle"] or 0)))
    return idle, counts


def fetch_page(host, key, page):
    token = base64.b64encode((key + ":X").encode()).decode()
    request = urllib.request.Request(
        "https://%s/api/v2/agents?per_page=%d&page=%d" % (host, PAGE_SIZE, page),
        headers={"Authorization": "Basic " + token, "Content-Type": "application/json"},
    )
    with urllib.request.build_opener(NoRedirect).open(request, timeout=30) as response:
        data = json.load(response)
    if not isinstance(data, dict) or not isinstance(data.get("agents"), list):
        raise ValueError("unexpected reply")
    return data["agents"]


def list_agents(host, key, fetch=fetch_page):
    agents = []
    for page in range(1, MAX_PAGES + 1):
        batch = fetch(host, key, page)
        agents.extend(batch)
        if len(batch) < PAGE_SIZE:
            return agents, False
    return agents, True


def csv_cell(value):
    text = "" if value is None else str(value)
    return "'" + text if text[:1] in ("=", "+", "-", "@", "\t", "\r") else text


def http_message(status):
    if status in (401, 403):
        return "Freshservice rejected the API key. Use the key of an admin."
    if status == 404:
        return "Freshservice did not recognise that address."
    if status == 429:
        return "Freshservice is rate limiting this account. Try again in a few minutes."
    return "Freshservice answered with status %d." % status


def main(argv=None):
    parser = argparse.ArgumentParser(description="List Freshservice agents with no activity or login for N days.")
    parser.add_argument("domain", help="your Freshservice address, for example acme.freshservice.com")
    parser.add_argument("--days", type=int, default=30, help="idle threshold in days, 1 to 365 (default 30)")
    parser.add_argument("--price", type=float, default=0, help="what you pay per full-time agent per month, to total the cost")
    parser.add_argument("--csv", metavar="FILE", help="also write the list to FILE as a CSV that opens in Excel")
    args = parser.parse_args(argv)

    host = args.domain.strip().lower().replace("https://", "").split("/")[0]
    if re.match(r"^[a-z0-9][a-z0-9-]{0,62}$", host):
        host += ".freshservice.com"
    if not HOST_RE.match(host):
        parser.error("the address must end in .freshservice.com; the key is only ever sent there")
    if not 1 <= args.days <= 365:
        parser.error("--days must be between 1 and 365")
    key = os.environ.get("FRESHSERVICE_API_KEY", "").strip()
    if not key:
        try:
            if sys.stdin.isatty():
                key = getpass.getpass("Freshservice API key (typing is hidden): ").strip()
            else:
                sys.stderr.write("Freshservice API key (this window may show what you paste; use cmd or PowerShell on Windows): ")
                sys.stderr.flush()
                key = sys.stdin.readline().strip()
        except (EOFError, KeyboardInterrupt):
            key = ""
    if not key:
        parser.error("no API key given. Run again and paste it at the prompt, or set FRESHSERVICE_API_KEY")

    try:
        agents, truncated = list_agents(host, key)
    except urllib.error.HTTPError as e:
        sys.exit(http_message(e.code))
    except (urllib.error.URLError, http.client.HTTPException, OSError, ValueError):
        sys.exit("Could not read the agent list from Freshservice. Check the address and your connection.")

    idle, counts = find_idle(agents, datetime.now(timezone.utc), args.days)

    if hasattr(sys.stdout, "reconfigure"):
        sys.stdout.reconfigure(errors="replace")
    print("%d of %d full-time agents have shown no activity for %d days or more." % (len(idle), counts["full_time"], args.days))
    for r in idle:
        print("  %-28s %-34s %s" % (r["name"][:28], r["email"][:34], "never seen" if r["never_seen"] else "%s (%d days ago)" % (r["last_seen"], r["days_idle"])))
    if args.price > 0 and idle:
        monthly = len(idle) * args.price
        print("At %.2f per agent per month these seats cost %.2f a month (%.2f a year)." % (args.price, monthly, monthly * 12))
    print("Not counted: %d occasional, %d deactivated." % (counts["occasional"], counts["deactivated"]))
    if counts["unassessed"]:
        print("%d full-time agent(s) have no activity or creation date in the data and could not be assessed." % counts["unassessed"])
    if truncated:
        print("Stopped after %d agents; the rest were not read." % (MAX_PAGES * PAGE_SIZE))
    if args.csv:
        try:
            with open(args.csv, "w", encoding="utf-8-sig", newline="") as f:
                out = csv.writer(f)
                out.writerow(["name", "email", "last_seen", "days_idle"])
                for r in idle:
                    out.writerow([csv_cell(r["name"]), csv_cell(r["email"]), r["last_seen"] or "never seen", "" if r["days_idle"] is None else r["days_idle"]])
        except OSError as e:
            sys.exit("Could not write %s: %s" % (args.csv, e.strerror or "unknown error"))
        print("Saved the list to %s." % args.csv)


if __name__ == "__main__":
    main()

The script reports what last_active_at and last_login_at show for that agent. Open the agent’s profile in Freshservice and compare. A late timestamp is not proof that a seat is unused, and an old one is not proof that it is idle for good, so treat the list as a place to start checking.

No. It calls the Freshservice API only.

The script accepts only addresses ending in .freshservice.com, so use the .freshservice.com address of your account.

It answers a question many admins have, and it shows how Seat Sweep decides who is idle. The app checks daily inside Freshservice and opens a digest ticket monthly, so there is nothing to run and no key to handle in a terminal.