Asset Tracker — QR Code System

For Users: Read sections 1-7 for everything you need to know about using QR codes For Developers: Jump to Technical Documentation (section 8) for API specs and implementation details

🎯 What Are QR Codes?

QR codes are scannable barcodes that help you quickly identify and track physical assets. Every asset in Nimbly automatically gets its own unique QR code that you can print and attach to the physical item.

Benefits:

📱 Fast identification — Scan with any smartphone camera
🔓 No login required — Anyone can scan to see basic asset info
📊 Automatic tracking — All scans are recorded for audit trails
🖨️ Easy printing — Download and print QR labels directly

📷 How to Generate QR Codes

Step-by-Step Guide

Open the asset you want to create a QR code for
Click the QR Code button at the top of the page
A popup will show your asset’s QR code
Choose what you want to do:
- Download QR — Save the QR code image to print
- Copy URL — Copy the link to share via email or chat
- View Details — Go back to the asset page

What You’ll See

When the QR code popup opens, you’ll see:

✅ The scannable QR code (square barcode)
✅ Asset number (e.g., “A-1042”)
✅ Asset name (e.g., “Commercial Fryer”)
✅ Web address (the URL the QR code points to)

📱 How to Scan QR Codes

Using Your Smartphone

Open your phone’s camera app (works on iPhone and Android)
Point the camera at the QR code on the asset
Tap the notification that appears on your screen
Your phone will open a webpage showing:
- Asset number
- Asset name
- Organization name
- Asset type

What Happens When You Scan?

If you’re logged into Nimbly:

✅ The scan is automatically recorded with your name
✅ An activity entry is created with your name and timestamp
✅ You can click “View Full Asset Details” to see everything

If you’re NOT logged in:

✅ You can still see basic asset information
✅ The scan is recorded as “Unknown User” (for tracking purposes)
ℹ️ You’ll need to log in to see full details

What Gets Recorded:

Logged-in users: Your name, timestamp, and asset scanned
Anonymous users: “Unknown User”, timestamp, and asset scanned

✅ Complete Workflow Example

Scenario: Tracking a Kitchen Fryer

1. Create the Asset

Admin adds “Commercial Fryer” to the system
Asset number: A-1042
Nimbly automatically generates a unique QR code

2. Print the QR Code

Admin opens the fryer’s detail page
Clicks QR Code button
Downloads the QR code image
Prints it on a label printer

3. Attach the Label

Admin sticks the QR label to the fryer in the kitchen

4. Kitchen Manager Scans It

Manager uses phone camera to scan the QR code
Webpage opens showing: “Asset A-1042 - Commercial Fryer”
Manager is logged in, so the scan is recorded with their name

5. Delivery Person Scans It (Not Logged In)

Delivery person scans the same QR code while dropping off supplies
Webpage shows the asset info
Scan is recorded as “Unknown User” for tracking purposes

6. View Activity History

Admin checks the fryer’s Activity tab
Sees:
- “Scanned by John Doe at 10:30 AM on March 26”
- “Scanned by Unknown User at 2:15 PM on March 26”
Confirms the fryer is being used and identifies unexpected access

🖨️ Printing Tips

Best Practices

Label Size:

Minimum: 1 inch x 1 inch (2.5cm x 2.5cm)
Recommended: 2 inches x 2 inches (5cm x 5cm) for easy scanning

Print Quality:

Use high-quality printer settings
Avoid blurry or pixelated prints
Test scan before attaching to asset

Label Material:

Use waterproof labels for outdoor assets
Use heat-resistant labels for kitchen equipment
Use durable vinyl for high-traffic areas

Placement:

Place QR codes where they’re easy to access
Avoid curved surfaces if possible
Keep labels clean and visible

📊 Activity Tracking

What Gets Recorded?

When someone scans a QR code, the system automatically records:

Information	Description
Who	Name of the person who scanned (or “Unknown User” if not logged in)
When	Date and time of the scan
What	Which asset was scanned
Source	Marked as “QR Code” scan

Note: Both logged-in and anonymous scans are recorded to help you track asset visibility and usage patterns.

Where to Find Scan Records

Go to the asset’s detail page
Click the Activity tab
Look for “Scanned by [Name]” entries
See all historical scans with timestamps (newest first)

Why Track Scans?

✅ Verify asset presence — Confirm assets are being used/accessed
✅ Monitor usage — See which assets are actively used
✅ Compliance checks — Prove assets were inspected
✅ Identify unused assets — Find assets that are never scanned

❓ Common Questions

Can anyone scan the QR code?

Yes! QR codes work for everyone, even people without Nimbly accounts. They’ll see basic asset information (name, number, organization).

Do I need a special app to scan?

No! The built-in camera app on iPhones and Android phones can scan QR codes. Just point your camera at the code and tap the notification.

Will my scan be recorded if I’m not logged in?

Yes! Anonymous scans are recorded as “Unknown User” so you can track all asset interactions. However, only logged-in scans show the actual person’s name.

Can I print multiple QR codes at once?

Not yet, but this feature is planned. For now, you need to download QR codes one asset at a time.

Yes! Click the Copy URL button in the QR code popup, then paste it into an email or chat message. The recipient can click the link to view asset information.

How long do QR codes last?

QR codes never expire. Once generated, they work forever unless the asset is deleted from the system.

Can I use QR codes offline?

No. Scanning a QR code requires an internet connection to open the asset information webpage.

🚨 Troubleshooting

QR Code Won’t Scan

Try these solutions:

✅ Make sure the QR code is in focus
✅ Ensure good lighting (not too dark)
✅ Hold your phone steady for 2-3 seconds
✅ Try moving closer or farther away
✅ Clean the QR code label if it’s dirty

QR Code Opens Wrong Asset

This shouldn’t happen. Each QR code is unique and always points to the same asset. If this occurs:

Check if someone switched labels by mistake
Verify the asset number matches
Reprint a fresh QR code from the correct asset

Scan Not Showing in Activity Tab

Check these things:

✅ Are you looking at the correct asset?
✅ Try refreshing the Activity tab
✅ Look for “Unknown User” entries if you weren’t logged in
✅ Scroll through the activity list (scans may be mixed with other events)
✅ Verify your internet connection was active during the scan

📈 Dashboard Reports

Tracking Health Metrics

The Asset Tracker dashboard shows QR scan statistics:

Metric	Description
Scanned Last 30 Days	Assets with recent QR scans
Never Scanned	Assets without any scan records
Compliance Rate	Percentage of assets scanned regularly

Using Scan Data

Identify Assets Needing Attention:

Assets never scanned may be lost or unused
Assets not scanned recently may need inspection
High scan frequency indicates active use

Improve Operations:

Train staff to scan assets during inspections
Set expectations for regular scanning
Use scan data to track asset usage patterns

🔐 Privacy & Security

What Information Is Public?

Anyone who scans a QR code can see:

✅ Asset number (e.g., “A-1042”)
✅ Asset name (e.g., “Commercial Fryer”)
✅ Organization name
✅ Asset type (Serialized or Bulk)

What Information Is Private?

The following details require login to view:

❌ Asset custodian (who’s responsible)
❌ Purchase price and costs
❌ Maintenance history
❌ Custom fields
❌ Activity logs
❌ Site location details

QR Code Security

QR codes use random, unique identifiers (impossible to guess)
No sensitive data is embedded in the QR code itself
Deleting an asset disables its QR code permanently

🎯 Best Practices

For Administrators

Print QR codes immediately after creating assets
Attach labels securely to prevent loss
Take a photo of the QR code placement for reference
Test scan each QR code before deployment
Keep backup labels for critical assets

For Field Staff

Scan assets during inspections to create activity records
Report damaged QR codes so they can be replaced
Don’t remove or switch labels between assets
Clean QR codes if they get dirty or obscured

For Operations Managers

Monitor scan compliance via the dashboard
Follow up on never-scanned assets to locate them
Train new staff on how to scan QR codes
Review activity logs to verify inspections

Technical Documentation

This section is for developers and system administrators

For complete technical details including API endpoints, data models, request/response formats, and database schemas, see Architecture - QR Code & Public Access.

🏗️ System Overview

Components

Frontend:

QR Code Modal (qr-code-modal.tsx) — Displays and downloads QR codes
Public Scan Page (/asset-tracker/scan/[qrToken]/page.tsx) — Server-side rendered public view
Scan Handler (qr-scan-handler.tsx) — Client-side component for activity logging

Backend:

nimbly-go-api — QR code generation and scan logging
PostgreSQL — Activity storage and asset data
MongoDB — User and site lookups

Flow Diagram

graph TB
    CREATE[Asset Created] --> TOKEN[QR Token Generated<br/>UUID v4]
    TOKEN --> MODAL[QR Code Modal]
    MODAL --> PRINT[Print & Attach]

    PRINT --> SCAN[User Scans QR]
    SCAN --> PUBLIC[Public Scan Page<br/>/asset-tracker/scan/:token]

    PUBLIC --> AUTH{User<br/>Authenticated?}
    AUTH -->|Yes| LOG[Log Scan Event<br/>with User Name]
    AUTH -->|No| LOGALT[Log Scan Event<br/>as Unknown User]

    LOG --> ACTIVITY[Activity Tab]
    LOGALT --> ACTIVITY
    LOG --> DISPLAY[Display Asset Info]
    LOGALT --> DISPLAY

    style TOKEN fill:#bbf,stroke:#333,stroke-width:2px
    style PUBLIC fill:#f9f,stroke:#333,stroke-width:2px
    style LOG fill:#bfb,stroke:#333,stroke-width:2px

🔑 Key Technical Points

QR Code Generation:

Format: PNG (256x256 pixels default)
Token: UUID v4 generated on asset creation
Endpoint: GET /v1.0/go/v1/asset-tracker/assets/{assetId}/qr-code

Public Scan Flow:

QR code resolves via GET /public/scan/{qrToken} (no auth required)
Server-side renders page with basic asset info
Client-side handler logs scan event
Activity record created with user name or “Unknown User”

GPS Location Support:

Backend API accepts latitude and longitude parameters
Frontend implementation pending (currently sends null)

Frontend Files:

QR Modal: admin-lite/src/app/admin/asset-tracker/_components/qr-code-modal.tsx
Public Page: admin-lite/src/app/asset-tracker/scan/[qrToken]/page.tsx
Scan Handler: admin-lite/src/app/asset-tracker/scan/[qrToken]/_components/qr-scan-handler.tsx

Backend Service:

API: nimbly-go-api
Base Path: /v1.0/go/v1/asset-tracker
Database: PostgreSQL (main data), MongoDB (user/site lookups)

For complete API specifications, request/response formats, data models, and database schemas, see Architecture - QR Code & Public Access.

🔌 API Endpoints (Summary)

All endpoints are prefixed with /v1.0/go/v1/asset-tracker.

Endpoint	Method	Auth	Purpose
`/assets/{assetId}/qr-code`	GET	Required	Generate QR code PNG image
`/public/scan/{qrToken}`	GET	Not required	Resolve QR token to asset data
`/assets/{assetId}/scan`	POST	Required	Log authenticated scan event
`/public/assets/{assetId}/scan`	POST	Not required	Log anonymous scan event

For detailed request/response formats and examples, see Architecture - QR Code & Public Access.

🧪 Testing

Manual Testing Checklist

Authenticated Scan:

User logs in
Scans QR code
Activity tab shows scan with user name
Timestamp is accurate

Anonymous Scan:

QR Generation:

📦 Asset Tracker Overview — Full feature guide
🔧 Backend Architecture — Complete API documentation
🔐 RBAC & Permissions — Access control and roles

📝 Quick Reference

QR Code Sizes

Small labels: 1-2 inches (2.5-5cm)
Standard labels: 2-3 inches (5-7.5cm)
Large posters: 4+ inches (10+ cm)

File Format

Download format: PNG image
File name pattern: [AssetNumber]_QR.png (e.g., A-1042_QR.png)

Scan Recording

✅ Logged-in users: Recorded with user name
✅ Anonymous users: Recorded as “Unknown User”

Activity Tab

Event type: “Scanned”
Information shown: User name (or “Unknown User”), timestamp, source (QR Code)
Sorting: Newest first

Last Updated: [Date] Version: 1.0.0 Status: Active

Nimbly Docs

Explorer

Asset Tracker — QR Code System

Asset Tracker — QR Code System

🎯 What Are QR Codes?

📷 How to Generate QR Codes

Step-by-Step Guide

What You’ll See

📱 How to Scan QR Codes

Using Your Smartphone

What Happens When You Scan?

✅ Complete Workflow Example

Scenario: Tracking a Kitchen Fryer

🖨️ Printing Tips

Best Practices

📊 Activity Tracking

What Gets Recorded?

Where to Find Scan Records

Why Track Scans?

❓ Common Questions

Can anyone scan the QR code?

Do I need a special app to scan?

Will my scan be recorded if I’m not logged in?

Can I print multiple QR codes at once?

Can I share the QR code URL via email?

How long do QR codes last?

Can I use QR codes offline?

🚨 Troubleshooting

QR Code Won’t Scan

QR Code Opens Wrong Asset

Scan Not Showing in Activity Tab

📈 Dashboard Reports

Tracking Health Metrics

Using Scan Data

🔐 Privacy & Security

What Information Is Public?

What Information Is Private?

QR Code Security

🎯 Best Practices

For Administrators

For Field Staff

For Operations Managers

Technical Documentation

🏗️ System Overview

Components

Flow Diagram

🔑 Key Technical Points

🔌 API Endpoints (Summary)

🧪 Testing

Manual Testing Checklist

🔗 Related Documentation

📝 Quick Reference

QR Code Sizes

File Format

Scan Recording

Activity Tab

Graph View

Table of Contents

Backlinks