mattrguerra.comHouston area
Matt Guerra
  1. 01AI & Automation
  2. 02Photography
  3. 03Design
  4. 04About
  5. 05Notes
  6. 06Contact
Back to the systems

mattrguerra/meridian-skillsmainPrivate on GitHub, published here in full

bitrix-tracker/

Bitrix Tracker

A read-only status digest of the Bitrix24 task queue. It answers "what needs attention right now?" without anyone scrolling the CRM.

What it does

Reads tasks from Bitrix24 via an inbound webhook and sorts them into attention buckets:

  • Overdue: deadline is in the past and the task isn't closed.
  • Unassigned: no real responsible person (responsible is empty or matches the configured "unassigned" placeholder).
  • Stale: no change in the last N days (default 7) and still open.
  • Changed since yesterday: moved in the last 24 hours (useful as a "what happened" glance).

It only reads. It never edits, assigns, or closes anything, so there's no write-gate and no risk of it touching live data.

Setup

  1. Copy config.example.json to config.json and adjust:
    • stale_days: how many days of no movement counts as stale (default 7).
    • unassigned_ids: Bitrix user IDs (or empty value) that mean "nobody really owns this." Often the account owner's ID if your team uses that as a holding pen.
    • task_filter: which tasks to pull (default: open, not closed).
  2. Copy .env.example to .env and set BITRIX_WEBHOOK_URL (the https://<domain>.bitrix24.com/rest/<user_id>/<token>/ base URL). Needs task read scope. If you later want deals tracked too, the same webhook needs CRM scope and we add a deals bucket.

The webhook URL is a credential. Treat .env like a password; don't commit it.

Running it

python scripts/bitrix_tracker.py            # digest from live Bitrix
python scripts/bitrix_tracker.py --mock     # digest from bundled sample_tasks.json
python scripts/bitrix_tracker.py --json      # machine-readable output instead of text

Output

A dated digest with a one-line count per bucket, then the tasks under each (ID, title, owner, and the relevant date: deadline for overdue, last-change for stale). Empty buckets are shown as "clear" so a quiet day reads as reassurance, not a blank screen.

Tuning the buckets

The four buckets are a sensible default for "tracking," but a reader may want something narrower (their own open tasks, one project group, deals rather than tasks). The buckets and filter live in config.json, so reshaping the digest doesn't mean touching code. Keep the buckets people act on and trim the rest.

Going automatic

This pairs naturally with a scheduled task, e.g. run every weekday at 8am and drop the digest somewhere the team will see it. Since it's read-only, scheduling it carries no risk; it's just a question of where the output should land (email, a doc, a chat message).

How to read failures

  • BITRIX_WEBHOOK_URL not set → .env missing or empty.
  • HTTP 401 / "Invalid token" → webhook URL wrong or revoked.
  • Empty digest with a live connection → check task_filter; the default only pulls open tasks.