HB HB Plastics Wiki

Job Cards

CRM Last reviewed Wed Jul 22 2026 00:00:00 GMT+0000 (Coordinated Universal Time) Edit this guide ↗

Job Cards

What it is

The job card system generates a PDF job card for each Pipedrive deal that enters Production. The PDF contains all the information the floor staff need to fulfil the order — customer details, line items, dispatch method, and any attached drawings. A daily email report (“Job Card Ops”) flags deals that are missing a card or have a card nobody has opened yet.

flowchart LR
  A[Deal enters Production] --> B[Generate job card PDF]
  B --> C[PDF stored in KV + note on deal]
  C --> D[Tracked in job_card_tracking table]
  D --> E[Daily report checks tracking rows]

How to generate a job card

  1. Open the deal in Pipedrive.
  2. In the job card panel, click Generate Job Card.
  3. The system creates a PDF, attaches it as a Pipedrive note, and records it in the job_card_tracking table.
  4. The PDF link appears in the deal’s activity log — click Open Job Card PDF to view it.
💡 Tip

Each time someone opens the PDF, it’s logged. The daily report uses this to tell you which cards have been generated but not yet actioned.

How to read the daily ops email

The “Job Card Ops” email arrives at 7

AM AEST for each brand. It has two sections:

  1. Card generated, not opened yet — these deals have a job card PDF but nobody has clicked the link. Action: open the PDF and start the job.
  2. In production, no job card — these deals are in a Production stage but no card has been generated at all. Action: generate a card, or check if the deal should be in Production.

Deals get a grace period — they only appear in the report if they entered Production before midnight AEST the previous day. A deal that moved to Production at 3 PM today won’t show up until tomorrow’s email.

⚠️ Gotcha

The report checks the job_card_tracking D1 table, not the Pipedrive note. If a card was generated but the tracking INSERT failed (see below), the deal will show as “no job card” even though the PDF exists. If you see a deal flagged that definitely has a card, tell Daniel — the tracking row needs to be backfilled.

How to backfill missing tracking rows

If deals appear in the report incorrectly (they have cards but are flagged as missing), an admin can:

  1. Run POST /backfill/job-card-tracking on the job-card-worker. This scans KV for PDF keys and inserts any missing tracking rows. It processes 50 at a time — keep calling with the returned cursor until has_more is false.
  2. For deals too old for the KV backfill to find, insert rows directly into D1 job_card_tracking with deal_id, deal_title, org_name, brand, and a placeholder pdf_key.

Known issue — silent tracking failures (fixed July 2026)

What happened: Before ~June 17 2026, the /generate endpoint tried to write a job_type column that didn’t exist in the job_card_tracking table. D1 rejected the INSERT, but the error was caught as a non-fatal warning — so the deal got a PDF but no tracking row. The daily report then flagged it as “no job card”.

Fix (PR #1443): The job_type column was added (migration 303), error logging was escalated from console.warn to console.error, and a KV failure counter (jc:count:track-fail:{date}) was added. 13 affected deals were backfilled directly into D1.

Lesson: “Non-fatal” tracking failures can cascade into user-facing report errors. Tracking INSERTs should always log at error level.

Auto job cards now retry a failed attempt (July 2026)

Paid online orders generate a job card automatically. Each deal has a one-time “already generated” guard so a burst of duplicate triggers can’t make two cards. Previously, if that automatic attempt failed partway (e.g. a Pipedrive note error), the guard stayed set and the deal was stuck as “already generated” for 30 days — the order silently got no job card until someone regenerated it by hand.

Now a failed automatic attempt clears its own guard, so the next trigger (or a manual regenerate) proceeds normally. Manual regeneration was never affected — it always bypasses the guard. If a paid order still shows no job card, regenerate it from the deal as usual and flag it.

Common questions

  • Why does a deal show “no job card” when I can see the PDF in Pipedrive? — The tracking row is missing. Tell Daniel to backfill it. See the gotcha above.
  • What deals need a job card? — Any deal in a Production stage with a single dispatch type that isn’t dropship.
  • Can I regenerate a card? — Yes, generating again creates a new PDF and a new tracking row. The report uses the latest card per deal.

Who to tell if it breaks

Tell Daniel, or ask in #whats-new. If the daily email stops arriving entirely, check the job-card-worker cron in Cloudflare.

Derived from: job-card-worker/index.js, HBPlastics-PIM/migrations/217_job_card_tracking.sql, HBPlastics-PIM/migrations/303_job_card_tracking_job_type.sql. If this looks wrong, the source changed — update the source and re-generate, don’t just patch this page.