Trackventory Help & System Guide

Understand Trackventory's features, workflows, and inventory management concepts.

Welcome to Trackventory! This system simplifies tracking your inventory using QR codes. It helps manage items that are used up (consumables) and items that are borrowed and returned (returnables). This guide explains the core concepts and how to use the system effectively.

Typical User Scenarios

These examples illustrate how you might use Trackventory for common tasks, connecting the concepts above to real-world actions.

1. First-Time User Introduction

A new user, Alex, logs into Trackventory for the first time. They see the Dashboard but aren't sure where to start. They navigate to the Help & System Guide page (this page!). Alex reads the Introduction section to get a basic understanding: Trackventory uses QR codes to manage both consumable supplies and returnable equipment.

2. Setting up a "Serialized" Returnable Item

Warehouse Manager Sarah needs to add 5 new, identical but individually tracked power drills (Returnable Items) using the Hybrid Model:

  1. Define the Type: Sarah navigates to Items and clicks "New Item". She enters:
    • Name: "Power Drill Model Z"
    • Unit: "Drill"
    • Measurement Unit: "Drill"
    • Unit Size: 1 (Crucial for serialized tracking)
    • Checks the Returnable box.
    • Saves the Item.
  2. Add Each Physical Instance: On the "Power Drill Model Z" Item page, Sarah clicks the "Add Batch" button. She enters Quantity: 1 and saves. She repeats this four more times.

    System Response: There are now 5 Batches listed for this Item, each with Quantity 1 and a unique Batch ID (e.g., #101, #102, #103, #104, #105).

  3. Label the Physical Items: Sarah goes to the Batches table on the Item page. She clicks the QR code icon next to Batch #101, prints the label, and firmly attaches it to the first physical drill. She repeats this for Batches #102 through #105, ensuring each drill gets its unique Batch QR code label.

Outcome: The 5 drills are now set up. Scanning a drill's specific QR code will identify exactly that unit in Trackventory for checkouts and returns. The Item's stock level shows 5.

3. Common Workflows

a. Receiving Standard Consumables:

Stock Clerk Ben receives a box containing 50 units of "Cleaning Wipes" (a pre-existing Consumable Item):

  1. Ben navigates to the "Cleaning Wipes" Item page.
  2. He clicks "Add Batch".
  3. He enters Quantity: 50 and the Expiration Date from the box.
  4. He clicks Save. System Response: Stock level increases by 50. New Batch record appears.
  5. Ben prints the Batch QR code for this delivery and sticks it onto the box.

Outcome: New stock recorded and ready for use via its Batch QR code.

b. Picking Consumables (FIFO Example):

Technician Chloe needs 5 "Resistors Type A":

  1. Chloe goes to the Scanner page (/scanner).
  2. She finds two batches on the shelf: Batch #88 (older) and Batch #95 (newer).
  3. She scans the Batch QR code for #95 (newer).
  4. System Response: Scanner shows #95 details but warns: "Older Batch #88 Available". Offers actions: "Complete Pick from #95 (Override FIFO)", "View Alternatives (#88)".
  5. Chloe puts #95 back and scans the Batch QR code for #88 (older).
  6. System Response: Shows #88 details. Offers "Create Pick", "View Details".
  7. Chloe selects "Create Pick", enters quantity 5, confirms. System: Pending Pick created.
  8. Scanner Updates: Shows #88 details and primary action "Complete Pick for 5 Units".
  9. Chloe selects "Complete Pick for 5 Units".

Outcome: Pick complete, Batch #88 quantity reduced, Item stock level updated.

c. Checking Out a "Serialized" Returnable Item:

Project Lead David needs to borrow "Power Drill Model Z" #103 (with Batch QR code attached):

  1. Clerk uses Scanner page, scans the Batch QR code on drill #103.
  2. System Response: Identifies Batch #103. Offers "Create Checkout", "View Details".
  3. Clerk selects "Create Checkout".
  4. Form appears (pre-filled). Clerk notes David's name/team in the notes field, sets due date, clicks Save.

Outcome: Checkout record created for Batch #103. Item stock level unchanged, but Batch #103 marked as checked out.

d. Returning a "Serialized" Returnable Item:

David returns drill #103:

  1. Clerk uses Scanner page, scans Batch QR code on drill #103.
  2. System Response: Identifies Batch #103, sees active checkout. Offers "Return Item", "View Checkout Details".
  3. Clerk selects "Return Item".
  4. Clerk confirms the return (notes any damage if applicable).

Outcome: Checkout record updated (status 'Returned'). Batch #103 marked available.

e. Checking Out Non-Serialized Returnable Items (Pool):

User Emily needs 2 standard hammers from a pool of 20 (Item: "Std Hammer", Returnable: true, one Batch with quantity 20):

  1. Emily goes to the "Std Hammer" Item page (or scans the Item QR code).
  2. She clicks the "Checkout" button/action.
  3. Form appears. She enters Quantity: 2.
  4. She selects her name/team, optionally sets a due date, and clicks Save.
  5. System Response: Checkout record created for 2 units of "Std Hammer". No specific Batch ID is linked to this checkout. The Item's available_quantity decreases by 2 (from 20 to 18).

Outcome: Emily takes 2 hammers. System tracks that 2 are checked out from the general pool.

f. Returning Non-Serialized Returnable Items (Pool):

Emily returns 1 of the 2 hammers she checked out:

  1. Clerk finds Emily's active Checkout record for "Std Hammer" (e.g., via Checkouts list or searching by user).
  2. Clerk clicks the "Return" button on that Checkout record.
  3. Form appears. Clerk enters Quantity Returned: 1.
  4. Clerk clicks Save.
  5. System Response: Return record created. The original Checkout status might update to 'Partial'. The Item's available_quantity increases by 1 (from 18 to 19).

Outcome: One hammer is returned to the pool. The system tracks that Emily still has 1 hammer checked out.

4. General Scanner Interaction

User Maria uses the mobile interface on the Scanner page (/scanner):

  1. Maria points camera at a QR code on a box.
  2. System (JS): Detects/decodes QR URL (e.g., .../batches/150).
  3. System (JS -> Backend): Sends ID (150) to ScannerController.
  4. System (Backend): Fetches Batch #150 details & context (Item type, status, pending actions, etc.).
  5. System (Backend): Determines relevant actions (e.g., "Complete Pick").
  6. System (Backend -> JS): Sends details & actions back to frontend.
  7. User Interface: Maria sees Batch details and action buttons (e.g., primary: "Complete Pick", secondary: "View Details").
  8. Maria taps the desired action button.

Outcome: Action triggered, feedback shown, scanner ready for next scan.

5. Checking Low Stock

Manager Mike wants a quick overview:

  1. Mike logs in, views the Dashboard.
  2. He checks the "Items Below Minimum Stock" widget.
  3. Sees "Resistors Type A" (Current: 8, Min: 10).
  4. Clicks "Resistors Type A" link to navigate to its Item page.

Outcome: Mike quickly identifies items needing attention.

6. Inviting a New User

Admin Alice needs to add technician Fred:

  1. Alice navigates to Account Settings -> Users & Teams.
  2. Clicks "Invite User".
  3. Enters Fred's email (fred@company.com).
  4. Selects the "Technicians" Team.
  5. Clicks "Send Invitation".

Outcome: Fred receives invite email. Listed as "Pending" until acceptance.

7. Troubleshooting: QR Code Not Recognized

User Sam tries scanning a QR code, but the scanner doesn't react:

  1. Sam checks lighting (seems okay).
  2. Adjusts phone distance/angle (still no reaction).
  3. Examines QR label - notices a smudge.
  4. Wipes label clean. Scans again. Scanner reacts.
  5. Alternative: If still not working, Sam suspects invalid code. Manually checks Item -> Batches list to verify Batch ID against delivery docs. Finds discrepancy -> data issue.

Outcome: Sam identifies the issue (smudged label or data error) and takes action.

Core Concepts

Items

The fundamental products or materials you track. Each item has a unique name, unit of measure, and type:

  • Consumable: Items used up and removed from stock permanently (e.g., supplies, ingredients). Managed via Picks. Marked as `returnable: false` in the system.
  • Returnable: Items borrowed and expected back (e.g., tools, equipment, assets). Managed via Checkouts and Returns. Marked as `returnable: true`.

Key attributes: `name`, `unit`, `measurement_unit`, `unit_size`, `stock_level`, `min_stock`, `returnable`.

The Stock Level shown for an Item is automatically calculated by summing the available quantities of all its unexpired Batches.

Batches

Specific deliveries or stock receipts of an Item. Batches allow tracking:

  • Quantity Received: How much arrived in this specific batch.
  • Expiration Dates: Crucial for perishable goods (`expiration_date`).
  • FIFO (First-In, First-Out): Ensures older stock is used first (tracked via `created_at` and batch availability logic).
  • Specific Stock Identification: Each batch gets its own QR code for precise tracking during picks, checkouts, or returns.

Key attributes: `item_id`, `quantity`, `unit_size`, `expiration_date`.

When a Batch's quantity is reduced (e.g., through a Pick), a Batch Usage record is created, and the parent Item's stock level is recalculated.

Setting Up an Item Correctly

Proper item setup is key for accurate tracking. When creating or editing an Item:

  • Name: Must be unique within your account.
  • Units vs. Measurement Units (Crucial Distinction):
    • Primary Handling Unit (`unit`): The unit items are typically handled or grouped in (e.g., 'Kiste', 'Palette', 'Pack'). Used for batch quantities in some models (like the serialized/hybrid model).
    • Base Measurement Unit (`measurement_unit`): The fundamental unit for stock counts and pricing (e.g., 'Stück', 'kg', 'ml'). Stock Level is always stored and displayed in this base unit.
    • Units Per Handling Unit (`unit_size`): How many Base Measurement Units are in one Primary Handling Unit (e.g., If Base Unit is 'Stück' and Handling Unit is 'Kiste', Unit Size might be '64'). Must be > 0.

    Example: Item: Chemical X, Handling Unit: Bottle, Base Unit: ml, Unit Size: 1000. A Pick request for "2 Bottles" will translate to consuming "2000" ml from batches.

  • Returnable (`returnable`): Check this box if the item is loaned out and returned (like equipment). Leave unchecked for items that are used up (consumables). This determines whether Picks or Checkouts/Returns are used.
  • Min Stock / Reorder Quantity: Set thresholds (in Base Measurement Units) for low stock notifications.
  • Price Per Unit: Price for one Base Measurement Unit, used for stock valuation (optional).

Handling Individually Tracked / Serialized Items (The "Hybrid Model")

If you need to track unique, individually identifiable items where each physical instance matters (e.g., specific tools, equipment, rental boxes like "Crockery Box #1", laptops), use this setup. This model avoids creating separate Item records for each physical unit (like "Box #1", "Box #2"). Instead, it uses the Item record to represent the general type and the Batch record to represent each unique physical instance.

Key Concept: Define the general product type as an Item (e.g., "Laptop Model X"). Create a separate Batch (with quantity 1) for each physical unit. The unique Batch ID and its corresponding QR Code act as the unique system identifier (like a serial number) for that specific physical unit, enabling precise tracking via scanning.

What Does "Serialized" Mean Here? (Item vs. Batch)

It means that each individual physical instance is treated as unique and distinct, even if they are the same type of item.

  • The `Item` Record: Represents the general category (e.g., "Crockery Box RAK Black", "Laptop Model X"). You only need one Item record per type.
  • The `Batch` Record: Represents one specific physical instance of that Item type (e.g., the specific physical box labeled #103, the specific laptop with serial ABC). Each Batch gets `quantity: 1`. This requires setting the Item's `unit_size` to 1 and marking it `returnable: true`.
  • The `Batch ID` & QR Code: This is the unique system identifier. Scanning the Batch QR code tells Trackventory *exactly which* physical unit is being handled (tracking), differentiating it from all others of the same Item type.

Think of it like this: You have one Item "T-Shirt Style 123", but many Batches, each representing a specific physical T-shirt with its own unique Batch ID/QR code.

  • 1. Configure the Item Record (Represents the *Type*):
    • Name: Describe the general type (e.g., "Laptop Model X", "Crockery Box RAK Black"). Avoid instance-specific names like "Box #1".
    • Primary Handling Unit (`unit`): The name of the individual item (e.g., "Laptop", "Box", "Unit").
    • Base Measurement Unit (`measurement_unit`): Often the same as the Handling Unit (e.g., "Laptop", "Box") since you are counting instances.
    • Units Per Handling Unit (`unit_size`): Must be set to `1`. This signifies that each "batch" represents exactly one measurable unit.
    • Returnable (`returnable`): Mark as `true`, as these items are typically checked out and returned individually.
  • 2. Create Batch Records (Represent *Each Physical Instance*):
    • Go to the Item's page.
    • Use the standard "Add Batch" button once for each physical item you are adding. (Or use "Bulk Add" if adding many identical items at once).
    • Enter a Quantity of `1` for each batch.
    • The system creates a separate `Batch` record for each physical item added, each with `quantity: 1`.
    • The `Batch ID` automatically generated becomes the unique internal identifier for that specific physical item.
    • You can assign unique expiration/inspection dates to each batch if needed.
  • 3. Physically Label Each Item with its Batch QR Code:
    • Print the QR code for each individual Batch (using the QR icon in the Batches table on the Item page).
    • Affix the specific Batch QR code to the corresponding physical item (e.g., put Batch #103's QR code on physical Box #103).
    • This step is vital! It links the physical item to its unique digital record (`Batch`) in Trackventory.
  • 4. Stock Level Interpretation:
    • The `Item#stock_level` will correctly show the total number of these individual physical items you have in stock (it sums the quantities of all available batches, which are all 1).

By scanning the unique Batch QR code on the physical item, the system precisely identifies that specific unit for Checkouts and Returns, distinguishing it from others of the same Item type.

Understanding Units & Measurements

Unit System Overview

Scanventory uses a dual-unit system that makes inventory management more intuitive. This guide explains how the system works and best practices for using it.

Key Unit Concepts
  • Handling Units: The physical containers or discrete units you handle (e.g., bags, bottles, boxes)
  • Base Units: The fundamental measurement units (e.g., liters, kilograms, pieces)
  • Unit Size: The conversion factor between handling and base units (e.g., 1 bag = 25 kg)

Understanding this relationship is crucial for accurate inventory management, especially when adding batches or recording usage.

Unit Conversion Explained

The system automatically converts between handling units and base units using the unit size defined for each item.

Example Conversion

For an item with:

  • Handling Unit: Bag
  • Base Unit: Kilogram
  • Unit Size: 25 (meaning 1 bag = 25 kg)

Converting Handling → Base:

3 bags × 25 kg/bag = 75 kg

Converting Base → Handling:

80 kg ÷ 25 kg/bag = 3.2 bags (rounded to 4 bags)

The system always rounds up when converting from base units to handling units to ensure you have enough physical containers to hold the specified amount.

Using the Dual Input System

When creating batches, you can now choose to enter quantities in either handling units or base units, depending on what's most convenient for your workflow.

Handling Unit Input

Use when you know how many physical containers (bags, bottles, etc.) you're adding.

  • Enter the number of containers
  • System calculates the total base units
  • Example: "5 bags" → "125 kg total"
Base Unit Input

Use when you know the total weight, volume, or quantity in base units.

  • Enter the total amount in base units
  • System calculates how many containers needed
  • Example: "130 kg" → "Requires 6 bags"
How to Toggle Between Input Modes
  1. When adding a new batch, look for the input mode toggle buttons above the quantity field
  2. Click "Bags" (or your handling unit) to enter quantities in handling units
  3. Click "Kilograms" (or your base unit) to enter quantities in base units
  4. The system will automatically convert and show you both values
  5. The form submits the correct handling unit quantity regardless of which input mode you used

Best Practices & Tips

Follow these guidelines to ensure accurate inventory management:

  • Set Up Items Correctly:
    • Define clear, consistent handling units (e.g., "Bag", "Bottle", "Box")
    • Use standard base units (e.g., "Kilogram", "Liter", "Piece")
    • Verify the unit size is accurate (measure if necessary)
  • Choose the Right Input Mode:
    • Use handling units when counting physical containers
    • Use base units when measuring with scales or volumetric tools
    • Verify the conversion looks reasonable before submitting
  • Maintain Consistency:
    • Don't change an item's unit size after creating batches
    • Use the same measurement tools consistently
    • Train all staff on the unit system to ensure consistent data entry
  • Regular Verification:
    • Periodically verify physical inventory against system records
    • The system runs nightly reconciliation to ensure stock levels match batch quantities
    • Check notifications for any discrepancies that need attention
Pro Tip: Precision Matters

The system now uses 3 decimal places for all measurements, providing greater accuracy for your inventory. This is especially important for high-value items or precise formulations.

Key Inventory Workflows

1. Receiving Inventory (Creating Batches)

When new stock arrives, you record it by creating a Batch for the corresponding Item.

  • Navigate to the Item's page.
  • For standard items, click "Add Batch" and enter the quantity received in that delivery and the expiration date.
  • For individually tracked/serialized items (like equipment or boxes), use the "Bulk Add" form (if available) to create multiple batches at once, each representing one physical item with quantity 1.
  • The system increases the Item's `stock_level` (in Base Measurement Units).
  • A unique QR code is generated for each specific Batch. Print and affix this to the corresponding batch/item.

2a. Using Consumable Items (Picks)

When a consumable item (`returnable: false`) is used, you record a Pick.

  • Picks can be created from the Item page or initiated by scanning an Item's QR code.
  • Enter the quantity needed. A "Pending Pick" is created (`PicksController#create`, `status: 'pending'`).
  • To fulfill the pick, scan the QR code of the specific Batch being used.
  • The system checks FIFO rules (`Batch#fifo_valid?`) and batch quantity.
  • If valid, the pick is completed (`PicksController#complete`), stock levels are reduced (`BatchUsage` record created), and the pick status becomes 'completed'.
  • The Scanner interface guides this batch scanning and completion process (`ScannerController`, `scanner_controller.js`).

2b. Borrowing Returnable Items (Checkouts)

When a returnable item (`returnable: true`) is borrowed, you create a Checkout.

  • Checkouts are typically initiated by scanning the Item's QR code, which directly takes you to the checkout form (`ItemsController#checkout` route).
  • Specify the quantity, user/team borrowing, and optionally a due date (`CheckoutsController#create`).
  • The Checkout status is initially 'pending' or similar.
  • To link the specific physical item being borrowed, scan the Batch QR code associated with that item. This updates the Checkout record (`CheckoutsController#link_batch`).
  • The Item's overall `stock_level` is typically *not* reduced, but the availability of specific batches might be affected depending on configuration. The checkout record tracks who has the item.

3. Returning Returnable Items

When a borrowed item is returned, you record a Return against the original Checkout.

  • Find the active Checkout (via the Checkouts list or potentially by scanning the item/batch QR).
  • Initiate a Return (`ReturnsController#new`).
  • Specify the quantity returned and any damaged quantity.
  • The system updates the Checkout status (e.g., 'partial', 'returned') based on quantities (`ReturnsController#create`).
  • Scanning the Batch QR code might also present a "Return Item" action in the scanner interface.

QR Code Scanning Workflow

The scanner is a powerful tool for quickly interacting with inventory. Here's how it works (`ScannerController`, `scanner_controller.js`):

Step 1: Scan a QR Code

Use the Scanner page (`/scanner`). The system reads the URL encoded in the QR code.

There are two main types of QR codes:

  • Item QR Codes: Link to the Item's general info. Used to initiate actions like creating a Pick or Checkout for the *type* of item.
  • Batch QR Codes: Link to a specific Batch. Used to identify specific stock for completing Picks, Checkouts, or processing Returns. For serialized items, this identifies the *unique physical unit*.

Step 2: Data Fetch & Context Analysis

The scanner fetches details about the scanned Item or Batch (using background JSON requests).

It determines the context: Is it an Item or a Batch? Is the Item returnable or consumable? Is the Batch expired? Is there a pending Pick/Checkout for this Item? (`scanner_controller.js#handleScan`, `#presentContextualActions`)

Step 3: Action Menu Presentation

Based on the context, the scanner presents relevant actions (`scanner_controller.js#getAvailableActions`, `#displayActionMenu`). Examples:

  • Scanned Consumable Item QR: Create Pick, View Item Details.
  • Scanned Returnable Item QR: Create Checkout (often redirects directly), View Item Details.
  • Scanned Consumable Batch QR (No Pending Pick): Create Pick, View Batch Details.
  • Scanned Consumable Batch QR (Matching Pending Pick): Complete Pick (Primary Action), View Batch Details.
  • Scanned Returnable Batch QR (No Active Checkout): Create Checkout, Return Item (if applicable), View Batch Details.
  • Scanned Returnable Batch QR (Matching Active Checkout): Link Batch to Checkout (Primary Action), Return Item, View Batch Details.
  • Scanned Expired Batch QR: Dispose Batch, View Batch Details.

FIFO warnings and alternatives may also be shown (`ScannerController#batch_error_message`, `#alternatives_data`).

Step 4: Action Execution

Selecting an action triggers the corresponding backend process (`scanner_controller.js#handleActionSelection` calling controller actions like `PicksController#complete`, `CheckoutsController#link_batch`, etc.).

Success or error messages are displayed, and the scanner typically becomes ready for the next scan.

Other Features

Dashboard

Provides an overview of inventory levels, recent activity, and pending actions (`DashboardController`).

Notifications

Alerts for low stock (below `min_stock`), expired or soon-to-expire batches (`NotificationsController`, background jobs potentially).

Reporting

View lists of Items, Batches, Picks, Checkouts, Returns for analysis.

Data Import

Bulk import items via CSV (`ItemsController#import`).

User & Team Management

Trackventory supports multiple users within an account.

  • Users: Individuals who log in (`User` model, managed via Devise and `RegistrationsController`).
  • Teams: Organize users into groups (`Team` model). Checkouts and Picks can optionally be associated with a Team (`TeamsController`).
  • Invitations: Invite new users to your account and assign them to teams (`Invitation` model, `InvitationsController`).
  • Roles: Define user permissions (e.g., `admin`, `account_admin`, potentially team roles via `TeamMembership`).

Scanner Troubleshooting

Camera Not Starting / Permission Denied

Ensure your browser has permission to access the camera. Check browser settings (often requires HTTPS, though workarounds exist for `localhost`). Click the "Start Camera" button if shown.

QR Code Not Recognized

Ensure the QR code is clear, well-lit, and fills a good portion of the camera view. Check if the code is for an Item or Batch within this Trackventory account. Invalid URLs will be rejected.

"Authentication Error" or Unexpected Redirect

Your login session might have expired. Try reloading the scanner page.

"Older Batches Available" / FIFO Warning

The system detected an older batch of the same consumable item that should be used first. Use the suggested alternative batch if possible, or proceed with caution if you must use the scanned batch.