Importing Assets to Shelf: CSV Guide

Introduction

Shelf allows you to import assets using CSV (Comma-Separated Values) files. This guide will help you create and import your asset data correctly.

New: Get help modelling your CSV for import with our new CSV Header generator tool

Quick Start

Ready to get started? Follow these essential steps:

1. Download the template - Use our CSV template (or barcode-enabled template if you have barcodes enabled)
2. Fill in your data - Add your asset information following the format shown
3. Save as UTF-8 - Ensure your CSV is saved with UTF-8 encoding
4. Navigate to Import - Go to Assets → Import in your Shelf workspace
5. Upload and confirm - Select your file and type "I AGREE" to confirm the import

Important: Never use data exported from asset backup to import assets. Always use the provided template to prevent data corruption.

File Requirements

Basic Format Rules

Your CSV file must follow these requirements:

• Delimiter: Use either , (comma) or ; (semicolon) as your delimiter
• Encoding: Save your file with UTF-8 encoding to prevent character issues
• Headers: The first row must contain column headers (this row is ignored during import)
• File format: Only .csv files are accepted

Standard Columns

These are the standard columns you can include in your CSV:

Advanced Features

Custom Fields

Create powerful custom fields by prefixing column headers with cf: followed by the field name and type.

Format

Use this format: cf:FieldName,type:TypeName

Supported Field Types

• text - Basic text input (default if no type specified)
• boolean - Yes/No values (use: yes, no, true, false, 1, 0)
• option - Dropdown selection (options created automatically)
• multiline text - Multi-line text areas
• date - Dates in YYYY-MM-DD format only
• amount - Currency values (numbers only, no symbols)
• number - Numeric values including negatives

Custom Field Example

QR Code Integration

Link your imported assets to existing Shelf QR codes for seamless physical asset tracking.

Requirements

• QR code must already exist in your Shelf workspace
• QR code must be unique (no duplicates in your import)
• QR code must not be linked to any existing asset or kit
• QR code must belong to your organization or be unclaimed

Note: If no qrId is provided, Shelf will automatically generate a new QR code for each asset.

Barcode Support (Premium Feature)

Import assets with various barcode types if your workspace has barcodes enabled.

Supported Barcode Types

• barcode_Code128 - 4-40 characters, supports letters, numbers, and symbols
• barcode_Code39 - 4-43 characters, letters and numbers only
• barcode_DataMatrix - 4-100 characters, letters and numbers only
• barcode_ExternalQR - 1-2048 characters, for external QR codes and URLs
• barcode_EAN13 - 13-digit retail product codes

Barcode Rules

• Multiple values: Separate with commas (e.g., "ABC123,DEF456")
• Unique values: Each barcode must be unique within your organization
• Character restrictions: Code39 and DataMatrix allow only letters and numbers
• Case handling: Values automatically converted to uppercase

Barcode Example

Kit and Custody Management

Automatic Kit Custody

When importing assets with both custodians and kits, Shelf intelligently manages custody relationships:

• New kits: Automatically inherit custody from their assets
• Existing empty kits: Updated to match asset custodian
• Existing kits with assets: Validated for consistency to prevent conflicts

Kit-Custody Validation

Shelf prevents data inconsistencies by validating:

• Assets and their kits have matching custodians
• Multiple assets in the same kit don't have different custodians
• Existing kits with assets maintain custody consistency

Import Process

Pre-Import Validation

Before creating any assets, Shelf validates:

1. File format and encoding
2. Header correctness - All headers must match supported columns or custom field format
3. QR code availability - Ensures QR codes exist and are available
4. Barcode permissions - Verifies workspace has barcode features enabled
5. Kit-custody conflicts - Prevents inconsistent custody assignments
6. Custom field formats - Validates date formats, boolean values, etc.

Import Execution

Assets are processed in this order:

1. Related entities created - Categories, locations, kits, team members
2. Image processing - Downloads and validates image URLs
3. Asset creation - Creates assets with all properties
4. QR code linking - Links existing QR codes or generates new ones
5. Barcode generation - Creates barcodes if enabled
6. Kit custody updates - Sets kit custody based on asset assignments
7. Custom field values - Processes and validates custom field data

Troubleshooting

Common Import Errors

"Invalid headers in csv file"

• Check that all column headers match supported columns exactly
• Ensure custom field headers follow the cf:FieldName,type:TypeName format
• Remove any extra spaces or special characters from headers

"CSV file is empty"

• Your file needs at least 2 rows (headers + 1 data row)
• Check that your file was saved properly as a .csv file

QR Code Issues

• Duplicate codes: Each qrId must be unique in your import
• Non-existent codes: QR codes must exist in Shelf before importing
• Already linked: QR codes can't be linked to other assets or kits
• Wrong organization: QR codes must belong to your workspace

Kit Custody Conflicts

• Multiple custodians for same kit: All assets in a kit must have the same custodian
• Existing kit conflicts: Can't assign different custodian to kit that already has assets

Data Format Issues

Date Fields Not Importing

• Use YYYY-MM-DD format only (e.g., 2024-01-15)
• Avoid date formats like MM/DD/YYYY or DD-MM-YYYY

Boolean Fields Showing Incorrectly

• Use: true, false, yes, no, 1, or 0
• Avoid: True, FALSE, Y, N, or other variations

Tags Not Separating Properly

• Use commas to separate multiple tags: "electronics,laptop,portable"
• Avoid spaces after commas unless part of the tag name

Custodian Not Found

• Use exact team member name or email address
• Ensure the team member exists in your workspace
• Check for typos in email addresses

Best Practices

Before Importing

• Clean your data: Remove empty rows and ensure consistent formatting
• Test with small batch: Try importing 5-10 assets first to verify format
• Backup existing data: Export current assets before large imports
• Plan your structure: Decide on categories, locations, and kits beforehand

After Importing

• Review imported assets: Check that all data imported correctly
• Verify relationships: Ensure kits, categories, and locations are properly linked
• Test QR codes: Scan QR codes to verify they link to correct assets
• Update permissions: Ensure team members have appropriate access to new assets

Performance Considerations

Large Imports (1000+ assets)

• Consider breaking large imports into smaller batches
• Ensure stable internet connection for image downloads
• Allow extra time for barcode and QR code processing

Related Resources

Explore these related topics to maximize your Shelf experience:

• Categories - Organize your assets effectively
• QR Codes - Learn about QR code generation and usage
• Bookings - Configure bookable assets and reservations
• Custom Fields - Create powerful custom field configurations

Need additional help? Our CSV Helper can assist with formatting your data correctly, or contact our support team for personalized assistance.

‍