04 — Your first substance (end-to-end)

Purpose

Walk through the full first-time setup: add a substance, add a supplier, create an invoice, receive a container, and log your first transaction. This guide ties together every inventory concept so you have a working example by the end.

This is the most important onboarding guide for a new clinic. After completing it, your clinic is set up to log all controlled-substance activity going forward, and you understand the substance → supplier → invoice → container → transaction chain that DEA inspectors trace.

When to use it

• Right after completing 02 — Onboarding wizard and (optionally) 03 — Invite your clinic members
• When training a new staff member on the full data flow
• As a sanity check during an internal audit ("can I trace this transaction back to its supplier?")

The chain you're building

SUBSTANCE  (Ketamine HCl 100mg/mL injectable)
   │
   ├── SUPPLIER  (Patterson Veterinary, DEA registered)
   │       │
   │       └── INVOICE  (#INV-2026-0341, dated 2026-02-15)
   │
   └── CONTAINER  (number 2026-KET-001, 10mL, lot ABC123)
          │
          └── TRANSACTION  (administered 0.3mL to Bella the dog)

Each step is one form. Each form takes 30-60 seconds to fill in. End to end, your first substance takes ~5 minutes.

Walkthrough

Step 1 — Add the substance

Navigate to /home/<your-clinic>/inventory/substances and click Add substance.

For Ketamine HCl injectable:

• Substance name: Ketamine HCl
• DEA Schedule: III (ketamine is Schedule III)
• Form: injectable
• Unit: mL
• Concentration: 100mg/mL
• Generic name: Ketamine hydrochloride (optional)
• Brand names: Ketaset, VetaKet (optional, comma-separated)
• Substance code: KET (optional, used in container number template)

Click Save. The substance appears in your formulary list.

Step 2 — Add the supplier

Navigate to /home/<your-clinic>/inventory/suppliers and click Add supplier.

For Patterson Veterinary:

• Supplier name: Patterson Veterinary Supply
• DEA registration: RP1234567 (use the supplier's actual DEA registration; most are 2 letters + 7 digits)
• Contact name: optional
• Email / Phone / Address: optional but recommended for audit-trail completeness

Click Save.

If your "supplier" is actually an internal transfer (e.g., from your other clinic location), you can add them as a supplier with a placeholder DEA registration (set the DEA registration to blank since they're not technically a wholesaler) and select transfer as the receiving type when receiving the container.

Step 3 — Create the invoice

Navigate to /home/<your-clinic>/inventory/invoices and click Add invoice.

• Supplier: select Patterson Veterinary
• Invoice number: from the supplier's paperwork (e.g., INV-2026-0341)
• Invoice date: when the supplier issued it
• Subtotal / Tax / Shipping: optional but recommended for cost tracking; total auto-calculates
• Status: pending until the shipment arrives, then received, then reconciled after you've verified the contents
• Document file: optional PDF upload of the invoice scan — strongly recommended for DEA audit chain

Click Save.

Step 4 — Receive the container

Navigate to /home/<your-clinic>/inventory/containers and click Receive container.

• Receiving type: purchase (since this came from a supplier)
• Substance: select Ketamine HCl
• Container/bottle number: leave blank for auto-generation, or override (the system shows a preview after you select the substance — for example 2026-KET-001)
• Lot number: from the bottle label (e.g., ABC123)
• NDC: from the bottle label, optional but useful
• Initial quantity: 10
• Unit: mL (auto-populated from substance)
• Received date: today
• Expiration date: from the bottle label (must be in the future for purchases)
• Supplier: Patterson Veterinary
• Invoice: select the invoice you just created

Click Save. The container appears in your container list with status unopened.

Step 5 — Log your first transaction

Navigate to /home/<your-clinic>/inventory/transactions and click Add transaction.

For an administered transaction:

• Container: select your Ketamine container (it'll auto-mark the container as opened on the first transaction)
• Transaction type: administered
• Quantity: 0.3
• Unit: mL (auto-populated)
• Date / time: now (or backdated if entering historical)
• Patient: select or quick-add Bella (if you don't have a client/patient yet, see people/patients.md — you can also quick-add inline from this form)
• Prescriber (the prescribing veterinarian): yourself, or the appropriate prescribing vet from your clinic
• Notes: optional; e.g., "Pre-anesthetic for spay surgery"

Click Save.

The container's current_balance decreases from 10mL to 9.7mL. The transaction is now permanent — you can read it from the transaction log forever, but the only way to change it is via a correction RPC, which preserves the original entry and adds a separate corrected-entry record.

Step 6 — Verify the chain

Click into your transaction. The detail page shows:

• Transaction info (type, quantity, date, performed by)
• Linked container (with its current balance)
• Linked patient (with their client / owner)
• The container's linked supplier and invoice

You have just built a complete audit trail. A DEA inspector tracing the 0.3mL of ketamine you administered to Bella can navigate from this transaction up to the container, up to the invoice, up to the supplier — all in CS Logbook, no paper required.

Edge cases

Can I receive a container without a supplier or invoice?

For new purchases — no, both are required. This is a CFR 1304.21 requirement (records of receipt must identify source).

For historical migrations (entering containers you had before adopting CS Logbook), use the receiving type paper_migration. That mode allows past expiration dates and lets you create a placeholder supplier ("Unknown - Historical") and invoice ("N/A - Migration") for legacy data. See inventory/containers.md § historical migration for the full pattern.

What if I don't know the lot number?

Lot number is required (1+ characters). If a bottle's label is illegible, use a placeholder like UNKNOWN-2026-02-15 (where 2026-02-15 is the receive date) and document why in the Notes field. DEA inspectors prefer "best-effort with documentation" over blank fields.

Witness requirements

When you log a waste or on-site disposal transaction, the form offers a witness picker (another staff member). It is expected but never required, so you can record the event before anyone else is set up. Inviting your clinic members (step 3) is still worth doing early, so a witness is available to name at the time, but it does not gate your ability to log waste.

Common mistakes

• Skipping the supplier step. "I'll just enter 'patterson' as text" — but the form requires selecting a supplier from the dropdown, not free-text. Add the supplier first.
• Reusing the same invoice across unrelated containers. One invoice = one supplier shipment. If two shipments arrived from the same supplier on the same day, create two invoices (one per shipment / packing slip).
• Logging "received" transactions manually. When you receive a container via the Receive container form, the system auto-creates the corresponding received transaction with the correct quantity. Don't add a separate received transaction afterward — that double-counts the receipt.
• Backdating without a paper trail. You can backdate transactions, but be prepared to defend the date in an audit. Always note in the Notes field why you backdated (e.g., "data entry catch-up; physical use occurred 2026-02-12 per paper log page 47").

Related

• Inventory → Substances — adding substances in detail
• Inventory → Suppliers — supplier records and DEA registration
• Inventory → Invoices — invoice details and PDF attachments
• Inventory → Containers — container lifecycle and receive flow
• Inventory → Transactions — transaction types, witnesses, corrections
• People → Patients — adding patients (the animals on transactions)