Time-Based Triggers: its own page, a dev recipe, and Pitfalls #9
The #801 write-up was buried mid-page in Workflows, so it never appeared in the
sidebar tree — you could only find it if you already knew it was there.
New page: Time-Based-Triggers.md — the four triggers and their crons, the
fire-once ledger, the fingerprint, the four starter recipes, cron setup, and how
to test it by hand without waiting for a scheduler.
Plus what was missing everywhere: HOW TO ADD A NEW ONE. Register the trigger,
write the detector, choose the entity_key and fingerprint (that choice IS the
job — everything else is boilerplate), register with the cron, ship a recipe.
With the traps nobody would guess: changing the fingerprint formula re-arms every
in-window record AT ONCE, and renaming a trigger silently orphans live workflows
(workflows.trigger_event is a plain string nothing validates — the workflow stays
active, looks healthy, and never fires again).
Pitfalls #9: the fire-once ledger that burned its emission on an audience of
nobody. The cron runs from install; by the time you BUILD a renewal workflow the
ledger already says "already fired" for every contract in-window, so switching it
on leaves it permanently silent for exactly the contracts you built it for — and
nothing is observable. Found by asking what happens on a FRESH INSTALL, which the
happy path never exercises.
Workflows.md keeps a summary + link. Sidebar and See-also updated.
Workflows/Pitfalls: readable _name merge codes + the lying Send-test preview (pitfall #8)
Workflows.md: new 'Use the name, not the id' section — {{ticket.priority_name}}
renders Critical, not 4; twins derived from the same registry as the condition
dropdowns; never clobbers a host module's value.
Pitfalls: #8 — the Send-test sample invented fields the real payload never
carries, so a preview rendered 'High' and production rendered ''. Bug #1 reached
from the opposite direction. Takeaway: generate previews from the same
definition the real thing uses, never a hand-written mock that can drift.
Workflows/Webhooks: templates, dry run, merge codes, encryption, retention + 2 new pages
Workflows.md: starter templates (with the name->id resolver design), dry run,
and a rewritten merge-codes section explaining why the picker is scoped to the
trigger (renderTemplate resolves unknown paths to an EMPTY STRING, so an
unavailable code fails silently). Refreshed "what's still ahead".
Webhooks.md: new "Data protection" section — URL + signing secret encrypted at
rest, URL redacted in the delivery log, the VARCHAR(2000) width requirement,
why the secret is NOT masked in the editor, and payload retention (default 7d)
vs row retention (30d) with the Replay trade-off stated. Plus a TLS
troubleshooting pointer.
New: HTTPS-Certificates-and-CA-Bundles.md — what certificate verification is,
what a CA bundle is in plain English, why Windows hits this, the fix (both
php.ini files), how to verify, and why "just disable SSL verification" is the
wrong answer.
New: Workflow-and-Webhook-Pitfalls.md — seven real bugs, their causes and
fixes. Five were INVISIBLE in production (nothing crashed, no test would have
failed). Meta-lesson: build the thing that makes the class of bug impossible
and it hands you the instances for free.
Sidebar: both new pages nested under Workflows.