build.allanninal.dev

Part 4 of 7 · Vendor onboarder series ~5 min read

How a vendor gets chased for missing items

Most vendors don’t upload everything in one go. They send the easy items first and forget the rest, and the rest is what slips. Once a day, the onboarder looks at every vendor still collecting, works out which documents are still missing, and decides whether to do nothing, send a gentle nudge, send a firmer follow-up, or escalate to your own team. The decision is plain Python. Four small guardrails sit between “this vendor owes something” and the reminder actually landing — so the chase is polite, well-timed, lists only what’s left, and never doubles up.

Key takeaways

  • The chase runs once a day via EventBridge Scheduler at 9am local time.
  • Four moves per vendor, every tick: done, nudge, follow-up, escalate — based on days since the invite.
  • The cadence lives in the checklist doc — nudge at day 3, follow-up at day 7, escalate at day 14.
  • A reminder lists only the outstanding items, so a vendor isn’t asked for things already in.
  • Quiet hours and a no-duplicate check keep the chase from being noise. No model on the tick.

Four guardrails on every chase

Four guardrails between the chosen chase move and the sent reminder A horizontal flow diagram. On the far left, a "Move chosen" box: the daily tick read this vendor's checklist and the days since invite, and picked one of three sending moves — nudge, follow-up, or escalate (a vendor with everything in is done and gets nothing). Four guardrail gates sit in a row to the right, each drawn as a vertical bar. Gate 1: List what's left — reads the checklist row and builds the list of items still not done, so the reminder names only the outstanding documents, not the whole list. Gate 2: Pick recipient — for a nudge or follow-up, the recipient is the vendor's contact; for an escalate, it's the internal contact who owns this vendor, with the vendor's contact copied. Gate 3: Quiet hours — checks the local time against the quiet-hours window (default 6pm to 8am); if outside business hours, defers the send to the next business minute via an EventBridge Scheduler one-off. Gate 4: No duplicate — checks the vo-chase table to confirm a reminder for this move hasn't already gone out today, so a re-run of the tick never doubles a message. After all four gates pass, the reminder ships via SES outbound with the upload link and the list of missing items. A note at the bottom: every reminder is logged to DynamoDB so the next tick knows what already went out. Move chosen nudge, follow-up, or escalate Gate 1 List what's left read checklist row in DDB keep not-done name only the missing items Gate 2 Pick recipient nudge → vendor contact escalate → internal owner, vendor copied Gate 3 Quiet hours local time in business window? if not, defer via Scheduler Gate 4 No duplicate check vo-chase for today already sent? skip. else send + upload link Send — SES outbound email with the upload link and the list of missing items vendor contact for nudge/follow-up · internal owner for escalate every send logged to DDB vo-chase — the next tick won’t duplicate Every gate is a deterministic check — no model calls, and a vendor is never asked for what’s already in.
Fig 4. Four guardrails between the move and the sent reminder. List only what’s left. Pick the right recipient. Honor quiet hours. Don’t duplicate. Then send via email and log it so the next tick doesn’t repeat the message.

Four moves, always

Once a day, an EventBridge Scheduler rule fires the chase Lambda. It reads every vendor still in the collecting state, and for each one computes the days since the invite went out and which items are still not done. Then it lands in exactly one of four buckets.

  • Done. Every required item is present, in date, and confirmed. The vendor moves to ready-to-approve and the chase stops. Part 5 picks up here. No reminder is sent.
  • Nudge. The first cadence step has arrived (day 3 by default) and items are still missing. Send a friendly reminder that lists only the outstanding documents and re-sends the upload link.
  • Follow-up. A later step arrived (day 7) with items still missing. Send a firmer reminder that mentions the first one went out, so the vendor doesn’t feel it’s the first time you’ve asked.
  • Escalate. The final step arrived (day 14) and the vendor still hasn’t finished. Tell your own internal contact — the person who wanted this vendor — so a human can pick up the phone. The vendor’s contact is copied; the escalation isn’t a substitute for asking them, it’s a flag for your side.

The cadence numbers (3, 7, 14) live in the checklist doc, not the code, so a rep can make a slow category gentler or a rush vendor faster without a deploy.

Gate 1: list only what’s left

The single thing that makes a chase feel respectful instead of robotic is that it asks for the right things. Gate 1 reads the vendor’s checklist row and keeps only the items that aren’t done — missing entirely, or present-but-expired. The reminder names those and nothing else. A vendor who has already sent their bank details and tax form gets a reminder about the insurance certificate alone, with a line like “Thanks for the two you’ve sent — we just need your certificate of insurance to finish.” An expired item gets its own honest note: present, but out of date, please send a current copy.

Gate 2: pick the right recipient

A nudge and a follow-up go to the vendor’s contact — the person who’s actually holding the documents. An escalate is different: it goes to your internal owner, the person who started the vendor, because at day 14 the useful move is a human-to-human conversation, not another automated email. The vendor is copied so nothing happens behind their back. The escalate message carries the full history — what’s in, what’s still missing, and the dates of the earlier reminders — so your colleague has everything they need before they reach out.

Gate 3: quiet hours

The tick runs at 9am local, so most reminders land in business hours already. But deferred sends and re-runs can fall outside the window. Gate 3 reads the quiet-hours setting (default 6pm to 8am) and, if the current local time is in the quiet window, creates a one-off EventBridge Scheduler rule that fires at the next business-hour minute and exits without sending. A reminder is a finite kind of goodwill; landing one at 11pm spends it for nothing.

Gate 4: no duplicate

The last gate reads the vo-chase DynamoDB table to confirm a reminder for this vendor and this move hasn’t already gone out today. If it has, the send is skipped. This is what makes the tick safe to re-run: if the Lambda retries, or someone triggers it manually, no vendor gets the same message twice. After a successful send, a row is written to vo-chase with the vendor, the move, the date, and the list of items that were outstanding — which is also what the weekly digest and the audit trail read later.

Why the chase uses no model

The chase could call a model to write a warmer message each time. It doesn’t. The cadence and the recipient choice are simple rules, and a model in that loop would add cost and variance for no real gain — the reminder templates in the voice doc already sound like you. The only place a model reads anything is the document checker in Part 3, on upload. The daily chase is plain Python comparing a checklist against a calendar.

Next post: what happens once a vendor finishes — how the complete file reaches the owner, and the three things the owner can do before the vendor is ever added.

All posts