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

The first time you log a waste or disposal transaction, the form will require a witness (another staff member). Make sure step 3 — Invite your clinic members is done first, or at minimum that you have one other clinic member, before you need 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)