Skip to content

Latest commit

 

History

History
1064 lines (849 loc) · 38.6 KB

user-manual.md

File metadata and controls

1064 lines (849 loc) · 38.6 KB

Workshop Inventory Tracking - User Manual

Table of Contents

  1. Getting Started
  2. Overview
  3. Adding New Inventory
  4. Label Printing
  5. Managing Existing Inventory
  6. Advanced Search
  7. Batch Operations
  8. Data Export
  9. Help and Utilities
  10. Tips and Best Practices
  11. Troubleshooting

Getting Started

System Requirements

  • Modern web browser (Chrome, Firefox, Safari, Edge)
  • Internet connection for database access
  • Barcode scanner (optional, keyboard wedge type recommended)

First Time Setup

  1. Open your web browser and navigate to the application URL
  2. The application will automatically connect to the database
  3. For data export functionality, ensure Google Sheets credentials are configured (optional)

Main Navigation

  • Home - Dashboard with application overview and quick actions
  • Add Item - Add new inventory items
  • Search - Advanced search and filtering
  • Inventory List - View and manage all inventory
  • Move Items - Batch move operations
  • Shorten Items - Cut materials to length

Overview

The Workshop Inventory Tracking system helps you manage metal stock, hardware, and other workshop materials. The system tracks:

  • Physical Properties: Length, width, thickness, weight
  • Material Information: Type, shape, material composition
  • Threading Details: Series, handedness, size, form
  • Location Tracking: Current location and sub-location
  • Purchase Information: Date, price, vendor details
  • Status: Active/inactive status for each item

Adding New Inventory

Using the Add Item Form

Add Item Form Add item interface showing all available fields for tracking materials

  1. Navigate: Click "Add Item"

  2. Required Fields (marked with *):

    • JA ID: Unique identifier (e.g., "JA12345")
    • Type: Rod, Tube, Sheet, Hardware, etc.
    • Shape: Round, Square, Rectangular, etc.
    • Material: Steel, Aluminum, Brass, etc.

  3. Dimensions: Enter measurements in inches

    • Length, width, thickness (as applicable)
    • Use fractions (e.g., "1 1/8") or decimals (e.g., "1.125")
    • Wall thickness for tubes

  4. Threading (if applicable):

    • Series: UNC, UNF, M (metric), NPT, etc.
    • Handedness: Right or Left
    • Size: e.g., "1/4-20", "M10x1.5", "3/4-16"
    • Form: UN, ISO Metric, Acme, Trapezoidal, etc.

  5. Location Information:

    • Location: Main storage area
    • Sub-Location: Specific bin, shelf, or section

  6. Purchase Details (optional):

    • Purchase date, price, location
    • Vendor and part number

  7. Notes: Additional information or special handling requirements

Barcode Scanning

  • JA ID Field: Scan barcode to automatically fill
  • Location Field: Scan location barcode for consistency
  • Submit Code: Scan ">>DONE<<" barcode to submit form

Form Features

  • Auto-complete: Previous entries suggest values as you type
  • Auto-save: Form data is preserved if page refreshes
  • Validation: Real-time feedback on field formats

Streamlined Data Entry

Bulk Creation ("Quantity to Create")

Bulk Creation Preview Bulk creation preview showing sequential JA IDs that will be created

The Quantity to Create field allows you to create multiple identical items with sequential JA IDs in a single form submission. This is ideal when you have multiple pieces of the same material that need individual tracking.

How to use:

  1. Fill out the add item form completely with all item details
  2. Set Quantity to Create to the number of items you want (1-100)
    • Default is 1 (single item)
    • For multiple items, a preview shows the JA ID range that will be created
  3. Submit the form
  4. For bulk creation (quantity > 1):
    • A modal appears showing all created JA IDs
    • You can print labels for all items from the modal
    • All items are identical except for their unique JA IDs

What gets copied:

  • ALL fields: type, shape, material, dimensions, location, notes, vendor info, etc.
  • Sequential JA IDs are automatically assigned starting from the next available number

What doesn't get copied:

  • History (each item is a fresh record)

Note: Photos are not automatically copied during bulk creation. However, you can manually copy photos after creation using the photo copying feature (see Photo Management).

Example use case: You receive 10 identical steel bars from a supplier. Instead of creating 10 separate entries, fill out the form once with all details and set "Quantity to Create" to 10. The system creates JA000001 through JA000010 (or whatever the next available numbers are) with identical specifications.

Carry Forward Button

The Carry Forward button (located in the top-right header) allows you to copy common field values from the previously added item into the current form. This is useful when adding multiple similar items.

Fields copied forward:

  • Type, Shape, Material
  • Location and Sub-Location
  • Dimensions (length, width, thickness, wall thickness, weight)
  • Thread Size, Series, and Handedness
  • Vendor, Vendor Part Number, Purchase Location, and Purchase Date
  • Notes

Fields NOT copied (remain blank):

  • JA ID (you'll need to enter unique ID)
  • Purchase Price
  • Photos

How to use:

  1. Add your first item normally
  2. On the next add form, click Carry Forward to populate common fields
  3. Enter the unique JA ID (and modify any fields as needed for the new item)
  4. Submit as normal

Add & Continue Button

The Add & Continue button (green button next to "Add Item") submits the current item and immediately returns to a fresh add form, streamlining bulk entry workflows.

How to use:

  1. Fill out the add item form completely
  2. Click Add & Continue instead of Add Item
  3. The item is saved and you're returned to a blank add form
  4. Repeat for additional items
  5. Use Add Item (blue button) for your final item to return to the inventory list

When to use each:

  • Carry Forward: Adding multiple similar items (same material, location, etc.)
  • Add & Continue: Adding multiple different items in sequence
  • Combined approach: Use Add & Continue, then Carry Forward for maximum efficiency

Label Printing

The system can print barcode labels for any JA ID using connected label printers. Labels can be printed from the Add Item form, Edit Item form, or in bulk from the Inventory List.

Accessing Label Printing

From Add Item Form

  1. Enter a valid JA ID (format: JA######)
  2. The printer button (📄) will become enabled next to the JA ID field
  3. Click the printer button to open the label printing dialog

From Edit Item Form

  1. The printer button is always enabled since the JA ID already exists
  2. Click the printer button next to the JA ID field
  3. The label printing dialog will open

From Inventory List (Bulk Printing)

  1. Navigate to the Inventory List page
  2. Select one or more items using the checkboxes in the leftmost column
    • You can select items individually by clicking their checkboxes
    • Or use the "Select All" option from the Options dropdown to select all visible items
  3. Click the "Options" dropdown button in the top-right corner
  4. Select "Print Labels" from the dropdown menu
  5. The bulk label printing dialog will open showing all selected items

Using the Label Printing Dialog

  1. Select Label Type: Choose from available label types:

    • Sato 1x2: Standard 1" × 2" labels
    • Sato 1x2 Flag: 1" × 2" labels with flag mode (rotated barcodes)
    • Sato 2x4: Larger 2" × 4" labels
    • Sato 2x4 Flag: 2" × 4" labels with flag mode
    • Sato 4x6: Large 4" × 6" labels
    • Sato 4x6 Flag: 4" × 6" labels with flag mode

  2. Print Label: Click "Print Label" to send the job to the printer

  3. Success Confirmation: A green success message will appear when printing completes

  4. Auto-close: The dialog automatically closes after successful printing

Label Type Selection

Add Item Form

  • Label type selection is remembered between uses
  • Your last selected label type will be pre-selected the next time you print
  • This helps speed up workflows when printing many similar labels

Edit Item Form

  • Label type selection is not remembered
  • You must select the label type each time
  • This prevents confusion when editing different items

Inventory List (Bulk Printing)

  • Label type selection is not remembered between sessions
  • You must select the label type each time you open the bulk printing dialog
  • All selected items will be printed with the same label type

Using the Bulk Label Printing Dialog

When printing labels for multiple items from the Inventory List:

  1. Review Selected Items: The dialog displays all selected items with their JA IDs
  2. Select Label Type: Choose the label type to use for all selected items
    • The same label type will be used for all items in the batch
  3. Print All Labels: Click "Print All Labels" to start the batch printing process
  4. Monitor Progress: A progress bar shows the printing status
    • Current item being printed
    • Number of items completed
    • Percentage complete
  5. Review Results: After completion, the dialog shows:
    • Number of labels printed successfully
    • Number of failures (if any)
    • Detailed error messages for any failed prints
  6. Close or Retry: Click "Done" to close the dialog
    • Your item selection remains unchanged for convenience
    • You can retry printing if needed

Tips for Bulk Printing:

  • Print labels in batches of similar sizes to ensure label consistency
  • Review the selected items list before printing to avoid mistakes
  • If some labels fail to print, the dialog will show which ones need to be retried
  • The progress bar helps monitor large batch jobs

Supported Printers

The system supports Sato label printers with the following configurations:

  • sato2: 1" × 2" label printer
  • sato3: 2" × 4" label printer
  • SatoM48Pro2: 4" × 6" label printer

Flag Mode Labels

Flag mode creates labels with rotated barcodes at both ends, making them easier to read when wrapped around cylindrical objects like rods or tubes.

Troubleshooting Label Printing

Printer Not Responding

  • Verify the printer is powered on and connected
  • Check that the correct printer driver is installed
  • Ensure the printer name matches the system configuration

Label Format Issues

  • Verify you selected the correct label type for your printer
  • Check that labels are loaded correctly in the printer
  • Ensure label size matches the selected type

Barcode Scanning Issues

  • Use high contrast settings if barcodes appear faint
  • Verify label material is compatible with your scanner
  • Clean scanner lens if having reading difficulties

Managing Existing Inventory

Edit Item Form Edit interface with complete item details, photo management, and history access

Viewing Inventory

  1. Inventory List: View all items with sorting and filtering
  2. Search Results: View items matching search criteria
  3. Item Details: Click any item to view complete information

Inventory List Filters

The inventory list page provides several filters to help you find items:

  • Status: Filter by item status
    • Active Only (default): Shows only active/available items
    • Inactive Only: Shows only inactive/used items
    • All Items: Shows both active and inactive items
  • Type: Filter by item type (Bar, Sheet, Tube, Channel, etc.)
  • Material: Search/filter by material name
  • Search: Search across JA ID, location, and notes fields

All filtering happens instantly as you type or change selections. You can also click column headers to sort the results.

Updating Items

  • Edit items directly through the web interface
  • Navigate to any item's edit page from inventory list or search results
  • All fields can be updated except JA ID (which identifies the item)

Duplicating Items

The Duplicate button on the edit page allows you to create copies of existing items with new sequential JA IDs. This is useful when you acquire more of the same item.

How to use:

  1. Navigate to the edit page for the item you want to duplicate
  2. Click the Duplicate Item button in the page header
  3. In the modal that appears:
    • View a summary of the item being duplicated
    • Set the quantity (1-100) of duplicates to create
    • Preview shows the JA ID range that will be created
  4. If you have unsaved changes on the edit form:
    • Choose whether to Save changes (apply edits to source and duplicates) or Discard changes (use original values)
  5. Click Create Duplicates
  6. Success message confirms creation

What gets duplicated:

  • ALL fields: type, shape, material, dimensions, threading, location, vendor info, notes, etc.
  • Photos: ALL photos are automatically copied from the source item to each duplicate
  • Sequential JA IDs are automatically assigned

What doesn't get duplicated:

  • History (duplicates have no modification history)
  • Timestamps (duplicates get current date/time)

Photo Copying: When duplicating items, all photos from the source item are automatically copied to each new duplicate. The system uses efficient storage - photo data is shared between items rather than duplicated, saving storage space.

Example use case: You have an item JA000050 (a 36" steel bar) and acquire 5 more identical bars. Open JA000050's edit page, click Duplicate, set quantity to 5, and create. The system creates JA000051 through JA000055 with identical specifications.

Photo Management

The system allows you to attach photos to inventory items and copy photos between items. Photos can be automatically copied during item duplication or manually copied between any items.

Uploading Photos

Photo Upload Interface Photo upload interface for attaching images to inventory items

Photos can be uploaded when adding or editing items:

  1. Navigate to the Add Item or Edit Item page
  2. Scroll to the Photos section
  3. Click Choose Files or drag and drop images
  4. Supported formats: JPEG, PNG, WebP, PDF
  5. Multiple photos can be uploaded at once
  6. Photos are automatically resized to three sizes: thumbnail, medium, and original

Viewing Photos

Photo Gallery Gallery view showing multiple photos attached to an item

  • Inventory List: Photo count displayed in the table (e.g., "📷 3" indicates 3 photos)
  • Item Details Modal: Click any item to view full-size photos in a gallery
  • Edit Page: View and manage all photos for an item

Copying Photos Between Items

There are two ways to copy photos between items:

1. Automatic Photo Copying (During Duplication)

When duplicating items, photos are automatically copied to all new duplicates:

  • Navigate to the edit page for an item with photos
  • Click Duplicate Item
  • Set the quantity of duplicates to create
  • Click Create Duplicates
  • All photos from the source item are copied to each new duplicate
  • Success message shows: "Item duplicated as [JA ID]. N photos copied."

Storage Efficiency: The system uses smart storage - photo data is shared between items rather than duplicated, saving disk space.

2. Manual Photo Copying (From Inventory List)

For copying photos between existing items, use the photo clipboard workflow from the Inventory List page:

Step 1: Copy Photos

  1. Navigate to Inventory List (/inventory)
  2. Select one item that has photos (the source item)
    • The "Copy Photos From This Item" option is only enabled when:
      • Exactly one item is selected, AND
      • That item has at least one photo
  3. Click Options dropdown → Copy Photos From This Item
  4. A banner appears showing: "📋 N photo(s) from [JA ID] ready to paste. Select target items and click 'Paste Photos'."
  5. The selection is automatically cleared, ready for you to select target items

Step 2: Paste Photos

  1. Select one or more target items (items that will receive the photos)
  2. Click Options dropdown → Paste Photos To Selected
  3. Confirm the paste operation
  4. Photos are appended to any existing photos on the target items (not replaced)
  5. Success message shows: "Copied N photo(s) to M item(s)"
  6. Photo clipboard is automatically cleared

Additional Options:

  • Clear Photo Clipboard: Cancel the copy operation without pasting
  • The photo clipboard persists across page navigation within the same browser session

Example Workflow: You just created 5 new metal rod items (JA000550-JA000554) and want to copy photos from an existing similar item (JA000123):

  1. Go to Inventory List
  2. Find and select item JA000123
  3. Click Options → "Copy Photos From This Item"
  4. Search/filter for items JA000550-JA000554
  5. Select all 5 new items
  6. Click Options → "Paste Photos To Selected"
  7. Confirm the operation
  8. All 3 photos from JA000123 are now on each of the 5 new items

Photo Copying Rules:

  • Photos are appended to existing photos (not replaced)
  • If a target item already has 2 photos and you paste 3 photos, it will have 5 photos total
  • The display order is preserved from the source item
  • Source item's photos remain unchanged
  • Storage is efficient - photo data is shared, not duplicated

Deleting Photos

To delete a photo from an item:

  1. Navigate to the Edit Item page
  2. Find the photo in the Photos section
  3. Click the Delete button next to the photo
  4. Confirm the deletion
  5. If other items share the same photo, only the association is removed (photo data remains for other items)
  6. If no other items use the photo, it is completely removed from the system

Item Status

  • Active: Available for use
  • Inactive: Used up, cut down, or removed

Parent-Child Relationships & Item History

  • When items are shortened, complete history is tracked
  • Original item becomes inactive while maintaining full record
  • New item references parent item for traceability

Viewing Item History

Item History View History modal showing complete modification timeline for an item

Multiple Access Points:

  • 📋 Inventory List: Clock icon (🕒) in the Actions column of any item
  • 🔍 Search Results: Clock icon (🕒) in the Actions column of search results
  • 👁️ Item Details Modal: "View History" button in modal footer (both list and search views)
  • ✏️ Edit Form: "View History" button in the page header

History Modal Features:

  • Timeline Display:
    • Most recent changes at the top
    • Visual indicators for active (green) vs inactive (gray) entries
    • Complete dimension changes and modification notes
    • Timestamps for when each version was created/modified
  • Summary Information: Total versions, active items, and inactive items count
  • Easy Navigation: Seamlessly transitions between details and history views

Technical Details

  • Item History API: Access complete modification history via /api/items/{JA_ID}/history
    • Returns chronological list of all versions of an item
    • Shows active/inactive status for each version
    • Includes dimensions, dates, and modification details
  • Multi-Row Support: System properly handles multiple database entries per JA ID
    • UI always displays current active item data
    • Historical versions remain accessible via API and History UI
    • Search and filtering only return active items by default

Advanced Search

Search Interface

Advanced Search Form Advanced search interface with range queries, filters, and multiple criteria

Access via "Search" menu

Search Results Search results displaying matching items with all relevant details

Filter Categories

1. Basic Filters

  • Status: Active/inactive items
  • Type: Rod, tube, sheet, hardware, etc.
  • Shape: Round, square, rectangular, etc.
  • Material: Hierarchical material search with autocomplete (see below)

2. Dimension Ranges

  • Length: Min and max values
  • Width: Min and max values
  • Thickness: Min and max values
  • Wall Thickness: Min and max values
  • Weight: Min and max values

3. Threading

  • Thread Series: UNC, UNF, M, NPT, etc.
  • Thread Handedness: Right/left
  • Thread Size: Specific size patterns
  • Thread Form: UN, ISO Metric, Acme, etc.

4. Location

  • Location: Main storage areas
  • Sub-Location: Specific locations

5. Purchase Information

  • Purchase Date Range: Date range filters
  • Vendor: Specific suppliers
  • Price Range: Cost filters

6. Text Search

  • Notes: Search within notes field
  • Vendor Part: Search part numbers

Hierarchical Material Search

The material search field features intelligent autocomplete and hierarchical matching:

Autocomplete Features:

  • Progressive Disclosure: Shows top-level material categories when empty
  • Smart Filtering: Type to filter across all taxonomy levels
  • Navigation Mode: Browse through categories → families → specific materials
  • Keyboard Support: Navigate suggestions with arrow keys, select with Enter

Hierarchical Matching: When you search for a material, the system automatically includes all sub-materials in the hierarchy:

  • Searching for "Aluminum" (category) returns items made of:
    • "Aluminum" (exact match)
    • "6000 Series Aluminum" (family)
    • "6061-T6", "6063-T5" (specific alloys)
    • All other aluminum sub-materials
  • Searching for "6000 Series Aluminum" (family) returns items made of:
    • "6000 Series Aluminum" (exact match)
    • "6061-T6", "6063-T5", etc. (specific alloys in this family)
  • Searching for "6061-T6" (specific material) returns:
    • Only items made of "6061-T6" (leaf materials have no children)

This hierarchical search makes it easy to find all items of a general material type without needing to remember every specific alloy or variant.

Search Tips

  • Multiple Filters: Combine filters for precise results
  • Range Queries: Use min/max for dimensions
  • Hierarchical Materials: Search broad categories to find all variants
  • Export Results: Download search results as CSV
  • Bookmark Searches: Save frequently used search URLs

Batch Operations

Batch Operations Menu Dropdown menu showing available bulk operations for selected items

Moving Items

Move Items Interface Batch move interface for relocating multiple items efficiently

The Move Items feature allows you to efficiently relocate multiple inventory items in a single batch operation. The system supports moving items to both primary locations and optional sub-locations.

Move Workflow

  1. Navigate: Click "Move Items" in the main menu

  2. Scan Pattern: Follow this sequence for each item:

    • Scan JA ID: Scan or enter the item's barcode (e.g., JA000123)
    • Scan Location: Scan or enter the new primary location (e.g., M1-A, T-5, Other)
    • Scan Sub-Location (optional): Scan or enter the sub-location (e.g., Bin-3, Shelf-B)
      • Sub-locations can be any text format
      • If no sub-location is needed, skip this step
    • Next Item or Finalize:
      • Scan the next item's JA ID to finalize the current move and start a new one
      • OR scan ">>DONE<<" to finalize the current move

  3. Review Queue:

    • All queued moves appear in the table with item details
    • Each row shows: JA ID, current location, new location, and new sub-location (if specified)
    • Items remain in the queue until you execute the batch

  4. Validate Moves:

    • Click "Validate & Preview" to check all queued moves
    • System verifies that all JA IDs exist in the database
    • Any issues are highlighted for correction

  5. Execute Moves:

    • Click "Execute Moves" to apply all changes
    • Confirm the operation when prompted
    • All items are updated simultaneously
    • Success message confirms completion

Location Patterns

The system recognizes these location patterns:

  • M-locations: M1, M2-B, M15-ZZ (materials storage)
  • T-locations: T1, T-5, T10 (tool/temporary storage)
  • Other: For non-standard locations
  • Sub-locations: Any text format for specific bin, shelf, or section

Moving Without Sub-Location

When moving an item to a new location without specifying a sub-location, the system clears any existing sub-location for that item. This ensures location data stays clean and accurate.

Example:

  • Item JA000100 is currently at "M1-A / Bin-3"
  • You move it to "M2-B" (without specifying sub-location)
  • Result: Item is now at "M2-B" with no sub-location (Bin-3 is cleared)

Workflow Examples

Example 1: Simple Move (No Sub-Location)

Scan: JA000100
Scan: M2-B
Scan: >>DONE<<

Result: JA000100 moved to M2-B (sub-location cleared if it had one)

Example 2: Move with Sub-Location

Scan: JA000200
Scan: M3-C
Scan: Shelf-A
Scan: >>DONE<<

Result: JA000200 moved to M3-C / Shelf-A

Example 3: Batch Move Multiple Items

Scan: JA000300
Scan: M4-D
Scan: Bin-1
Scan: JA000301      (this finalizes JA000300's move)
Scan: M4-D
Scan: Bin-2
Scan: JA000302      (this finalizes JA000301's move)
Scan: M5-E
Scan: >>DONE<<      (this finalizes JA000302's move)

Result: Three items moved - JA000300 to M4-D/Bin-1, JA000301 to M4-D/Bin-2, JA000302 to M5-E

Tips for Efficient Moving

  • Barcode Scanner: Use a keyboard wedge barcode scanner for fastest data entry
  • Batch Related Items: Group items going to the same location to minimize scanning
  • Review Before Execute: Always validate the queue before executing to catch errors
  • Clear Sub-Locations: When reorganizing, move items without sub-locations first to clear old data
  • Manual Entry Mode: Check the "Manual Entry Mode" checkbox if you need to type values instead of scanning

Shortening Items

Shorten Items Interface Interface for cutting materials to length and creating child items

  1. Navigate: "Shorten Items" menu
  2. Item Selection: Enter or scan item JA ID
  3. New Length: Specify remaining length after cut
  4. New ID: Assign new JA ID for shortened piece
  5. Automatic: Original item becomes inactive, new item created

Data Export

The system provides comprehensive data export functionality to backup your inventory data and materials taxonomy to Google Sheets or download as JSON data. This feature is essential for data backup, reporting, and integration with other systems.

Export Types

1. Inventory Export

Exports all inventory items with complete details including:

  • Item identification (JA ID, type, shape, material)
  • Physical dimensions (length, width, thickness, wall thickness, weight)
  • Threading information (series, handedness, size, form)
  • Location tracking (location, sub-location)
  • Purchase details (date, price, vendor, part numbers)
  • Status and history (active/inactive, dates, notes)

2. Materials Taxonomy Export

Exports the hierarchical materials classification system:

  • Material names and categories
  • Hierarchy levels (1=Category, 2=Family, 3=Material)
  • Parent-child relationships
  • Example: Metal → Steel → 4140 Pre-Hard

3. Combined Export

Exports both inventory and materials data in a single operation for complete backup.

Export Destinations

JSON Format

  • Use Case: API integration, data processing, development
  • Format: Structured JSON with metadata, headers, and row data
  • Response: Direct API response with immediate download
  • Benefits: Machine-readable, preserves data types, includes export metadata

Google Sheets Upload

  • Use Case: Backup, manual review, sharing with stakeholders
  • Format: Direct upload to Google Sheets with proper formatting
  • Target Sheets: Metal_Export (inventory), Materials_Export (materials)
  • Benefits: Human-readable, accessible via web browser, collaborative editing

Using the Web Interface

Admin Export Page

  1. Navigate to /admin/export (admin access required)
  2. Select export type: Inventory, Materials, or Combined
  3. Choose destination: JSON Download or Google Sheets Upload
  4. Configure options:
    • Include inactive items (inventory only)
    • Batch size for processing
    • Enable progress logging
  5. Click "Export" to start the process
  6. Monitor progress and download results

API Access

Export to JSON

# Export inventory data only
curl -X POST http://localhost:5000/api/admin/export \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inventory",
    "destination": "json",
    "options": {
      "include_inactive": true,
      "batch_size": 1000
    }
  }' | jq '.'

# Export materials taxonomy only
curl -X POST http://localhost:5000/api/admin/export \
  -H "Content-Type: application/json" \
  -d '{
    "type": "materials",
    "destination": "json",
    "options": {
      "materials_active_only": true,
      "batch_size": 1000
    }
  }' | jq '.'

# Export combined data
curl -X POST http://localhost:5000/api/admin/export \
  -H "Content-Type: application/json" \
  -d '{
    "type": "combined",
    "destination": "json",
    "options": {
      "include_inactive": false,
      "materials_active_only": true,
      "batch_size": 1000
    }
  }' | jq '.'

Export to Google Sheets

# Upload inventory data to Google Sheets
curl -X POST http://localhost:5000/api/admin/export \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inventory",
    "destination": "sheets",
    "options": {
      "include_inactive": true,
      "batch_size": 1000,
      "enable_progress_logging": true
    }
  }' | jq '.'

# Upload materials taxonomy to Google Sheets
curl -X POST http://localhost:5000/api/admin/export \
  -H "Content-Type: application/json" \
  -d '{
    "type": "materials", 
    "destination": "sheets",
    "options": {
      "materials_active_only": true,
      "batch_size": 1000
    }
  }' | jq '.'

# Upload both datasets to Google Sheets
curl -X POST http://localhost:5000/api/admin/export \
  -H "Content-Type: application/json" \
  -d '{
    "type": "combined",
    "destination": "sheets",
    "options": {
      "include_inactive": false,
      "materials_active_only": true,
      "batch_size": 1000,
      "enable_progress_logging": true
    }
  }' | jq '.'

Data Validation

# Validate export data before uploading
curl -X POST http://localhost:5000/api/admin/export/validate \
  -H "Content-Type: application/json" \
  -d '{
    "export_data": {
      "inventory": {
        "headers": ["Active", "JA ID", "Length", "..."],
        "rows": [["Yes", "JA000001", "5.5400", "..."]]
      },
      "materials": {
        "headers": ["Name", "Level", "Parent"],
        "rows": [["Steel", "2", "Metal"]]
      }
    }
  }' | jq '.'

Export Options

Inventory Options

  • include_inactive: Include inactive/historical items (default: true)
  • inventory_sort_order: Sort order for results (default: "ja_id, active DESC, date_added")
  • batch_size: Records per processing batch (default: 1000)

Materials Options

  • materials_active_only: Export only active materials (default: true)
  • materials_sort_order: Sort order (default: "level, sort_order, name")
  • batch_size: Records per processing batch (default: 1000)

General Options

  • enable_progress_logging: Show detailed progress logs (default: true)
  • export_generated_by: Attribution text for export metadata

Response Format

Success Response (JSON)

{
  "success": true,
  "export_data": {
    "type": "inventory",
    "headers": ["Active", "JA ID", "Length", "..."],
    "rows": [
      ["Yes", "JA000001", "5.5400", "..."],
      ["No", "JA000002", "3.2500", "..."]
    ],
    "metadata": {
      "export_type": "inventory",
      "timestamp": "2025-09-11T17:30:00.000Z",
      "records_exported": 476,
      "success": true,
      "errors": [],
      "warnings": []
    }
  },
  "export_type": "inventory",
  "timestamp": "2025-09-11T17:30:00.000Z"
}

Success Response (Google Sheets)

{
  "success": true,
  "message": "Export to Google Sheets completed successfully",
  "export_type": "inventory",
  "upload_details": {
    "success": true,
    "rows_uploaded": 476,
    "sheets_updated": ["Metal_Export"],
    "upload_type": "inventory"
  }
}

Error Response

{
  "success": false,
  "error": "Export operation failed: Invalid export type"
}

Automated Backups

Scheduled Exports via Cron

# Daily backup at 2 AM - inventory and materials to Google Sheets
0 2 * * * curl -X POST http://localhost:5000/api/admin/export \
  -H "Content-Type: application/json" \
  -d '{"type": "combined", "destination": "sheets", "options": {"include_inactive": true}}'

# Weekly backup to JSON files  
0 3 * * 0 curl -X POST http://localhost:5000/api/admin/export \
  -H "Content-Type: application/json" \
  -d '{"type": "combined", "destination": "json"}' \
  > "/backups/inventory_$(date +%Y%m%d).json"

Best Practices

Performance

  • Use appropriate batch sizes (1000 is optimal for most cases)
  • Schedule large exports during low-usage periods
  • Enable progress logging for monitoring long-running exports

Data Quality

  • Validate exports regularly using the validation endpoint
  • Compare record counts between source and destination
  • Review export metadata for errors and warnings

Security

  • Restrict admin export access to authorized users only
  • Use HTTPS for all API communications
  • Rotate Google Sheets credentials regularly
  • Monitor export logs for unusual activity

Backup Strategy

  • Regular automated backups to Google Sheets for accessibility
  • Periodic JSON exports for long-term archival
  • Test restore procedures using exported data
  • Keep multiple backup versions for point-in-time recovery

Troubleshooting Export Issues

Common Problems

  • "Google Sheets connection failed": Check credentials and sheet permissions
  • "Sheet not found": Ensure target sheets exist in the Google Sheets document
  • "Rate limit exceeded": Reduce batch size or add delays between operations
  • "Export timeout": Break large exports into smaller chunks or increase timeout

Performance Tuning

  • Adjust batch_size based on dataset size and performance
  • Use include_inactive=false for faster inventory exports
  • Monitor system resources during large exports
  • Consider off-peak hours for major backup operations

Help and Utilities

Quick Search

  • / - Focus search field from anywhere in the application
  • Use this to quickly jump to the search input without clicking

Built-in Help

  • F1 or Shift+/ - Show available help and shortcuts
  • Hover over field labels for tooltips and guidance
  • Check validation messages for field-specific help

Barcode Scanner Support

  • Most input fields support barcode scanning
  • Ensure your scanner is configured as a "keyboard wedge"
  • Test scanner functionality in any text editor first

Context-Sensitive Features

  • Form fields provide real-time validation feedback
  • Auto-complete suggestions appear as you type
  • Error messages guide you to correct formatting

Tips and Best Practices

ID Management

  • Use consistent ID format (e.g., JA + 5 digits)
  • Sequential numbering helps tracking
  • Consider material codes in IDs

Measurements

  • Always use same units (inches recommended)
  • Fractions preferred for common sizes
  • Document measurement method in notes

Threading

  • Use standard nomenclature
  • Include thread form for specialty threads
  • Note if threads are damaged or modified

Location Tracking

  • Establish consistent location naming
  • Use sublocation for precise placement
  • Update locations promptly after moves

Data Quality

  • Complete all applicable fields
  • Use notes for special conditions
  • Regular data cleanup maintains accuracy

Performance

  • Search filters improve response time
  • Batch operations when possible
  • Regular browser cache clearing if slow

Troubleshooting

Common Issues

"Cannot connect to Google Sheets"

  • Check: Internet connection
  • Verify: Google Sheets permissions
  • Solution: Refresh page, check credentials

"Item not found"

  • Check: JA ID spelling/format
  • Verify: Item still active
  • Solution: Use search to locate similar items

"Duplicate item ID"

  • Check: Existing item with same ID
  • Solution: Use different ID or update existing

"Form validation errors"

  • Check: Required fields completed
  • Verify: Correct data formats
  • Solution: Follow field help text

"Barcode scanner not working"

  • Check: Scanner configured as keyboard wedge
  • Test: Scanner in text editor
  • Solution: Reconfigure scanner settings

"Search returns too many results"

  • Solution: Add more specific filters
  • Tip: Use range filters for dimensions
  • Export: Download results for offline review

"Performance is slow"

  • Clear: Browser cache and cookies
  • Check: Internet connection speed
  • Reduce: Number of active browser tabs

Getting Help

Built-in Help

  • Press F1 for help and available shortcuts
  • Hover over field labels for tooltips
  • Check validation messages for guidance

Data Issues

  • Verify entries in Google Sheets directly
  • Check for formatting consistency
  • Contact administrator for access issues

Technical Problems

  • Clear browser cache
  • Try different browser
  • Check browser JavaScript enabled
  • Ensure pop-ups allowed for application domain

Performance Optimization

  • Use search filters to limit results
  • Close unused browser tabs
  • Regular browser maintenance
  • Consider wired connection for barcode scanners

Quick Reference Card

Most Common Operations

  1. Add Item: Navigate to "Add Item" → Fill required fields → Submit
  2. Find Item: Navigate to "Search" → Enter search criteria → View results
  3. Move Items: Navigate to "Move Items" → Scan item/location pairs → Submit
  4. List All: Navigate to "Inventory List" → Use filters as needed

Required Fields for New Items

  • JA ID, Type, Shape, Material

Measurement Format

  • Inches preferred: "1 1/4" or "1.25"
  • Consistency is key

Thread Format Examples

  • Inch: "1/4-20", "3/8-16 UNC"
  • Metric: "M10x1.5", "M6x1.0"
  • Special: "3/4-6 Acme", "1/2-14 NPT"

This user manual provides comprehensive guidance for using the Workshop Inventory Tracking system efficiently and effectively.