Skip to content

Bulk Upload

Module: Bulk Upload  |  Audience: Admin, Owner

Table of Contents

Overview

Bulk upload enables importing large volumes of data via file upload (CSV / Excel). This is useful for initial data migration, periodic data loads, and batch operations. In addition to creating new records, Bulk Upload also supports bulk updates to existing records — see Bulk Create vs. Bulk Update.

Path: Sidebar → Bulk Upload  |  URL: /bulk-upload

Supported Entity Types

Entity Type Description Key Required Fields
Sites Import site (physical facility) records Name, Address Line 1, City, ZIP/Postal Code
Locations Import location data Name, Site, Location Type
Asset Categories Import asset categories Name
Departments Import department data Name, Department Code
Asset Status Import asset status master data Name
Asset Condition Import asset condition master data Name
Manufacturer Import manufacturer data Name
Model Import model data Name, Manufacturer
Supplier Import supplier data Name
Users Import user records First Name, Last Name, Email, Role
Assets Import new asset records Asset Name, Category, Status, Location
Asset Images Attach image files to existing assets Asset (lookup), Image Name

Note: The sidebar lists these entity types in the order shown above. Asset Images works differently from the rest — see Asset Images — Mapping Template.

Bulk Create vs. Bulk Update

Every entity type except Asset Images supports two modes, switched using the Action dropdown on the entity's upload page:

Action Effect
Add (Create) Imports the rows as brand-new records.
Edit (Update) Patches existing records with the values provided.

How Bulk Update works

  • Download the update template using the Download Update Template button (shown when Edit (Update) is selected). This is a different file from the create template.
  • The first column of the update template is an id lookup column — a dropdown listing the existing records for that entity. Use it to identify which record each row updates.
  • The remaining columns only include fields that are actually editable in bulk. Identity or system fields (e.g. the lookup column itself) are excluded from the update template.
  • Blank cells are treated as "don't care." If you leave a column blank on a row, that field is left unchanged on the existing record — it is not cleared.
  • Like bulk create, bulk update is all-or-nothing: if any row in the file fails validation, no records are updated.

Important: Uploading a create template through Bulk Update (or an update template through Bulk Create) is rejected with an error asking you to download the correct template — the two file formats are not interchangeable.

Step-by-Step Process

Step 1 — Select Entity Type and Action

From the bulk upload sidebar, select the type of data you want to import (Assets, Locations, etc.). Then choose the Action: Add (Create) to import new records, or Edit (Update) to patch existing ones.

Step 2 — Download Template

Click Download Create Template (or Download Update Template if Edit is selected) to get the pre-formatted file for the selected entity type and mode. The template contains: - Column headers matching the required and optional fields - Sample data rows showing expected formats - Data validation notes

Important: Always use the downloaded template for the mode you intend to upload (create vs. update). Custom file formats or the wrong template variant will cause import failures.

Step 3 — Fill Data

Populate the template with your data: - Follow the column headers exactly - Use the expected data formats (dates, numbers, etc.) - For dropdown fields (Category, Status, Location, etc.), use exact master data names as they appear in the system - Leave optional fields blank if not applicable (on an update template, a blank field means "leave unchanged")

Step 4 — Upload File

Return to the bulk upload page and: 1. Click Upload — this opens the upload page, carrying over the Create/Update action you selected. 2. Click Browse Files or drag-and-drop the completed file, then click Submit (create) or Update (edit). 3. The system reads and parses the file.

Step 5 — Review

The system validates every row before importing anything. If any row fails validation, the entire file is rejected — no records are created or updated. Error messages indicate exactly which field failed and why (e.g., "Category 'XYZ' not found", "Email already exists").

Step 6 — Track Status

Monitor the upload in the upload history table:

Column Description
File Name Uploaded file name
Entity Type Type of data
Status Current processing status
Uploaded By Who uploaded
Created At / Uploaded Date Upload timestamps
Error Count / Success Count / Total Records Row-level outcome counts

Click the error icon on a row to view detailed row-by-row error messages for that upload.

Asset Images — Mapping Template

Asset Images is a create-only flow with its own two-file upload — it does not use the Add/Edit action toggle or the standard single-file template.

Step 1 — Prepare Images

Place all image files in the root of a single ZIP file. Sub-folders are not scanned.

Step 2 — Download the Mapping Template

Click Download Create Template to get the Asset Image Mapping template — a dedicated Excel file (separate from the standard entity templates) with: - An Instructions sheet explaining the process - An Asset Image Mapping data sheet with two columns: id (asset lookup dropdown) and image_name (free text)

Step 3 — Fill the Mapping Sheet

For each image you want to attach: - id — select the target asset from the dropdown. - image_name — enter the exact filename of the image as it appears in your ZIP (e.g. photo1.jpg).

Tip: You can repeat the same image_name on multiple rows to attach the same image file to multiple assets. Each row creates an independent copy in storage — deleting one does not affect the others.

Step 4 — Upload

On the bulk upload page for Asset Images, upload both files together: 1. Step 1 — Images ZIP: the ZIP file of images. 2. Step 2 — Image Mapping File (Excel): the filled-in mapping template. 3. Click Upload Images.

Every row is validated first (asset exists, image found in the ZIP, file type/size allowed); if any row fails, no images are uploaded.

Upload Statuses

Status Description
Pending File uploaded; awaiting processing
Processing System is importing records
Success All rows imported successfully
Partial Success Some rows imported; others had errors
Failed Import failed entirely (file format issue, system error)

Error Handling

Common error categories:

Error Type Example Resolution
Missing Required Field "Asset Name is required" Fill in the required field
Invalid Reference "Category 'XYZ' not found" Ensure the referenced master data exists (spelled exactly)
Duplicate Record "Asset Tag 'A001' already exists" Use a unique value or update the existing record
Invalid Format "Date must be YYYY-MM-DD" Correct the format
Validation Failure "Department Code must be 3 characters" Follow field validation rules (see Appendix B)
Wrong Template "Wrong template: you uploaded a bulk update template. Please download and use the bulk create template." Download the template matching your selected Action (Create/Update)
Asset Image Mapping Error "Asset not found for value" / "Image 'photo1.jpg' not found in the uploaded ZIP root directory" Confirm the asset name matches exactly and the image file is at the ZIP root with a matching filename

Tip: Download the error report to see all issues at once (available via the error icon on a completed upload row). Fix them in the template and re-upload.

Workflow Integration

Important: Bulk-uploaded and bulk-updated records do not currently trigger workflow transactions, even if a workflow template is configured for that entity's Create or Update event. Bulk operations write records directly in batches and bypass the normal per-record workflow trigger path. If a record needs to go through an approval workflow, create or edit it individually through its regular module screen instead of via Bulk Upload.

Tips for Successful Uploads

Tip Detail
Always use the template Download a fresh template for each upload, matching both the entity type and the selected Action (Create/Update), to ensure column headers match
Create master data first All referenced entities (categories, locations, etc.) must exist before upload
Use exact names Dropdown values must match master data names exactly (case-sensitive)
Validate before upload Review your data in the template for completeness and accuracy
Start small Test with a small batch (5–10 rows) before uploading thousands
Check the error report After a failed or partial-success upload, view the error details via the error icon
Leave blanks on update templates intentionally On a bulk update, a blank cell means "don't change this field" — don't leave a field blank unless you want the existing value kept

Related: Master Data Configuration · Asset Management · Workflow Management