User Guide - Import/Export Functionality

Last Updated: November 23, 2025 at 10:47 PM
Back to Home

Import/Export Functionality Guide

Overview

The application now supports:

  1. Import Projects from Excel files for bulk project creation
  2. Export BOQ (Bill of Quantities) in XLSX and PDF formats with complete pricing

📥 IMPORT FUNCTIONALITY

How to Import a Project

  1. Navigate to Projects Page
  2. Go to /projects/
  3. Click "Import Project" button
  1. Download Template (Optional but Recommended)
  2. Click "Download Template" button
  3. This downloads an Excel file with the correct structure
  1. Fill in the Template
  2. Open the downloaded template
  3. Fill in your project data following the structure:
  4. Project Sheet: Project name, card wire, sensor wire, info
  5. Floors Sheet: List of floor names
  6. Zones Sheet: Zone names with corresponding floor names
  7. Systems Sheet: System names (must exist in database) with zone names
  8. Sub Systems Sheet: Sub system names (must exist in database) with quantities
  1. Upload the File
  2. Click "Import Project" button
  3. Select your filled Excel file
  4. Click "Import Project"
  5. You'll be redirected to the project builder if successful

Excel Template Structure

The template contains 5 sheets:

Sheet 1: Project

Field Value
Project Name My Project
Card Wire (meters) 3
Sensor Wire (meters) 15
Info Project description

Sheet 2: Floors

Floor Name
Ground Floor
First Floor

Sheet 3: Zones

Floor Name Zone Name
Ground Floor Zone A
Ground Floor Zone B

Sheet 4: Systems

Zone Name System Name
Zone A Fire Alarm System
Note: System names must exactly match existing systems in the database.

Sheet 5: Sub Systems

System Name Sub System Name Quantity
Fire Alarm System Smoke Detector 5
Note: Sub System names must exactly match existing sub systems in the database.

Import Requirements

  • File format: .xlsx or .xls
  • Maximum file size: 10MB
  • System and Sub System names must exist in the database
  • All sheets must be present (even if empty)

Import Process

  1. Validates file format and size
  2. Reads each sheet in order
  3. Creates project with floors, zones, systems, and sub-systems
  4. Shows success message with counts of created items
  5. Redirects to project builder for further configuration

📤 EXPORT FUNCTIONALITY

How to Export BOQ

  1. Navigate to Project Dashboard
  2. Go to a project's dashboard: /dashboard//
  3. You'll see export buttons at the top
  1. Choose Export Format
  2. Export BOQ (XLSX): For Excel format with full formatting
  3. Export BOQ (PDF): For PDF format suitable for printing/sharing
  1. Download the File
  2. Click the desired export button
  3. File downloads automatically
  4. File name format: BOQ__.xlsx or .pdf

Export Contents

The exported BOQ includes:

1. Project Information

  • Project name
  • Card wire length
  • Sensor wire length

2. Cards and Enclosures

  • Floor, Zone, System details
  • Sub Systems list
  • AI, DI, AO, DO counts
  • Point totals (Single Unit, Soft Points, Total)
  • Item descriptions (cards and enclosures)
  • Unit costs, quantities, and total costs
  • Subtotal for Cards & Enclosures

3. Sensors

  • Sensor descriptions with brand
  • Quantities
  • Unit costs
  • Total costs
  • Subtotal for Sensors

4. Cables

  • Cable types
  • Quantities
  • Unit costs
  • Total costs
  • Subtotal for Cables

5. Soft Integration Points

  • Descriptions
  • Point quantities
  • Unit costs
  • Total costs
  • Subtotal for Soft Integration

6. Grand Total

  • Sum of all subtotals

XLSX Format Features

  • Professional formatting with colors
  • Headers with blue background
  • Borders and alignment
  • Auto-sized columns
  • Currency formatting
  • Multiple sheets if needed (future enhancement)

PDF Format Features

  • Professional layout
  • Table formatting
  • Page breaks for long content
  • Headers and footers
  • Suitable for printing

🔧 Technical Details

Files Created/Modified

  1. projects/export_import.py
  2. Main export/import logic
  3. Functions: export_boq_xlsx(), export_boq_pdf(), import_project_from_excel()
  1. projects/views.py
  2. View functions: export_boq_xlsx_view(), export_boq_pdf_view(), import_project_view(), download_import_template()
  1. automation_cards_selection/urls.py
  2. URL routes for export/import
  1. Templates
  2. templates/projects/import_project.html - Import form
  3. templates/dashboard/dashboard.html - Export buttons added
  4. templates/projects/projects.html - Import button added

Dependencies Added

  • openpyxl==3.1.2 - For Excel file handling
  • reportlab==4.0.7 - For PDF generation

URL Routes

  • /projects//export/xlsx/ - Export BOQ as XLSX
  • /projects//export/pdf/ - Export BOQ as PDF
  • /projects/import/ - Import project form
  • /projects/import/template/ - Download import template

🚀 Usage Examples

Example 1: Import a New Project

  1. Create Excel file with project structure
  2. Go to Projects page
  3. Click "Import Project"
  4. Upload Excel file
  5. Project is created and you're redirected to builder

Example 2: Export BOQ for Client

  1. Complete project configuration
  2. Go to project dashboard
  3. Click "Export BOQ (PDF)"
  4. Share PDF with client
  5. Or export as XLSX for further editing

Example 3: Bulk Project Creation

  1. Prepare multiple Excel files
  2. Import each one
  3. All projects created automatically
  4. Saves time on repetitive data entry

⚠️ Important Notes

  1. System/Sub System Names: Must match exactly with database entries (case-sensitive)
  2. File Size: Maximum 10MB for import files
  3. File Format: Only .xlsx and .xls files supported
  4. Data Validation: Import validates data but may show warnings for missing systems
  5. Export Data: Export uses current project state - ensure project is finalized before exporting

🐛 Troubleshooting

Import Issues

Problem: "System 'X' not found in database"
  • Solution: Check system name spelling, or create the system in admin panel first
Problem: "Sheet 'X' not found"
  • Solution: Ensure all 5 sheets exist in your Excel file
Problem: "File size exceeds 10MB"
  • Solution: Reduce data or split into multiple files

Export Issues

Problem: Export shows empty data
  • Solution: Ensure project has systems configured and card selection is done
Problem: PDF formatting issues
  • Solution: Use XLSX format for better compatibility, or check reportlab version

📝 Future Enhancements

Potential improvements:

  • Import/export for master data (Systems, Cards, Sensors)
  • Bulk import of multiple projects
  • Custom export templates
  • Email export directly from dashboard
  • Export with images/diagrams
  • Import validation with preview before import

📞 Support

For issues or questions:

  1. Check this guide first
  2. Review error messages carefully
  3. Ensure data matches template structure
  4. Verify system/sub-system names exist in database