Reports / Exports

🎯 Overview

The Reports & Exports Page serves as the central hub for generating, managing, and downloading various project reports and data exports. This interface provides a comprehensive job management system where users can initiate export operations, monitor progress in real-time, and access generated files. The system supports configurable export types, backup operations, and project publishing workflows.

🔐 Access Requirements

👥 Required Roles & Permissions

View Exports: exports.view permission
Start Exports: exports.start permission
Cancel Exports: exports.cancel permission
Remove Exports: exports.remove permission
Reset Export Sessions: exports.reset-export-sessions permission

🌐 Permission Scope

Project-Based: Access limited to exports within user's assigned projects
Role-Based Operations: Different actions available based on user permissions
Project State Dependency: Some exports require project to be in "closed" or "published" state

💻 Interface Layout

📊 Main Export Overview

┌─────────────────────────────────────────────────────────────┐
│ 🚀 [Publish Project Files] ←— Project Management            │
├─────────────────────────────────────────────────────────────┤
│ 🔧 System                                                   │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 💾 Backup                                               │ │
│ │ [Generate] ←— Start backup job                          │ │
│ │ 📋 Jobs: ⏳ Running (45%) | ✅ Completed | ❌ Failed    │ │
│ └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 📈 Data Exports                                             │
│ ┌─────────┬─────────┬─────────┐                             │
│ │ 📊 Scans │ 👥 Users │ 🏢 Zones │                          │
│ │[Generate]│[Generate]│[Generate]│                          │
│ │⏳ Running│✅ Ready  │❌ Failed │                          │
│ └─────────┴─────────┴─────────┘                             │
├─────────────────────────────────────────────────────────────┤
│ 📄 Financial Reports                                        │
│ ┌─────────────────┬─────────────────┐                       │
│ │ 💰 Cost Report  │ 📊 Statistics   │                       │
│ │ [Generate]      │ [Generate]      │                       │
│ │ ✅ Completed    │ ⏳ Running (78%) │                      │
│ └─────────────────┴─────────────────┘                       │
└─────────────────────────────────────────────────────────────┘

🎛️ Job Management Interface

📋 Jobs
├── ⏳ Running Job
│   ├── 🔄 Status: Running (75%)
│   ├── 📅 Started: Nov 3, 2025 14:30
│   ├── ▓▓▓▓▓▓▓▓░░ Progress Bar
│   └── [Cancel] [Details]
├── ✅ Completed Job
│   ├── ✅ Status: Completed ⚠️ (with warnings)
│   ├── 📅 Finished: Nov 3, 2025 14:25
│   ├── 📁 Files: [report.xlsx] [summary.pdf]
│   └── [Remove] [Details] [Reset Sessions]
└── ❌ Failed Job
    ├── ❌ Status: Failed
    ├── 📅 Failed: Nov 3, 2025 14:20
    ├── ⚠️ Error: Database connection timeout
    └── [Remove] [Details]

⭐ Key Features

📊 Export Types & Categories

System Operations:
- 💾 Project Backup: Complete project data backup
- 🚀 Project Publishing: Publish project files to production
Data Exports (configurable via ExportConfig):
- 📊 Scan Data: Complete scanning records with metadata
- 👥 User Data: User accounts and activity reports
- 🏢 Zone Information: Zone configurations and statistics
- 📋 Session Data: Zone session records and analytics
Financial Reports:
- 💰 Cost Analysis: Project cost breakdowns
- 📈 Statistical Reports: Performance and efficiency metrics

🔄 Job Management System

Real-time Progress: Live progress bars and status updates
Job Queuing: Prevents duplicate jobs for same export type
Status Tracking: Comprehensive job lifecycle monitoring
Error Handling: Detailed error reporting and recovery options

📁 File Management

Automatic Downloads: Direct download links for generated files
File Organization: Files grouped by job and export type
Multiple Formats: Support for Excel, PDF, CSV, and other formats
Retention Management: Automatic cleanup of old export files

📘 Usage Guide

🚀 Starting an Export

Navigate to Reports & Exports page
Select Export Type from available categories

Configure Variables (if required):

📊 Export Variables Modal
┌─────────────────────────────────────┐
│ Date Range: [2024-01-01] to [Today] │
│ Include Deleted: ☐ Yes              │
│ Format: [Excel ▼]                   │
│ [Cancel] [Generate Export]          │
└─────────────────────────────────────┘

Click Generate to start the export job
Monitor Progress in real-time

📊 Monitoring Export Jobs

Progress Indicators:
- ⏳ Running: Shows percentage complete
- ✅ Completed: Ready for download
- ⚠️ Completed with Warnings: Check details
- ❌ Failed: Review error messages
- 🚫 Cancelled: Manually stopped
Job Actions:
- Cancel: Stop running jobs
- Remove: Delete completed/failed jobs
- Details: View logs and error information
- Reset Sessions: Reset export-related zone sessions

📁 Downloading Reports

Wait for Completion: Job status shows ✅ Completed
Click File Links: Download generated files directly
Multiple Files: Some exports generate multiple formats
File Naming: Files include timestamp and export type

🔧 Managing Export Sessions

Export Sessions: Special zone sessions created during exports
Session Reset: Use "Reset Export Sessions" for cleanup
Session Tracking: Monitor which zones were exported
Dependency Management: Handle parent-child job relationships

⚠️ Troubleshooting

🚫 Common Issues

❌ "Project must be closed" Error

✅ Close Project: Change project status to "closed"
✅ Check Status: Verify project state in project settings
✅ Contact Admin: Request project closure if needed

❌ "Export job already running" Warning

✅ Wait for Completion: Only one job per type allowed
✅ Cancel Existing: Cancel running job if needed
✅ Check Queue: Monitor job queue status

❌ "Permission denied" Error

✅ Check Roles: Verify required export permissions
✅ Project Access: Confirm membership in target project
✅ Contact Admin: Request appropriate role assignment

❌ "Export failed" Status

✅ Check Details: Review error logs via Details button
✅ Data Validation: Ensure project data integrity
✅ Resource Check: Verify server resources availability
✅ Retry Export: Attempt export again after issue resolution

❌ "Files not downloading"

✅ Browser Settings: Check download permissions
✅ File Existence: Verify file was actually generated
✅ Network Issues: Check internet connectivity
✅ Server Access: Confirm file server accessibility

📱 Mobile/Responsive Considerations

Touch Interactions: All buttons optimized for touch
Progress Visibility: Progress bars scale to screen size
File Downloads: Mobile browsers handle downloads appropriately
Modal Dialogs: Full-screen on small devices

🔄 Performance Tips

Batch Exports: Avoid running multiple large exports simultaneously
Off-Peak Hours: Schedule large exports during low usage
Data Filtering: Use date ranges to limit export size
Regular Cleanup: Remove old export jobs to maintain performance

🛠️ Technical Details

📊 Export Configuration Structure

// ExportConfig Structure
{
  "exportType1": {
    "title": "Scan Data Export",
    "group": "Data Exports",
    "allowWhenProjectNotClosed": false,
    "isHidden": false,
    "exportVariables": [
      {
        "key": "dateRange",
        "title": "Date Range",
        "value": ["last30days", "last7days", "custom"]
      },
      {
        "key": "format",
        "title": "Export Format",
        "value": "excel"
      }
    ]
  }
}

🔧 Job Lifecycle States

// Job Status Flow
waiting → ready → running → completed/failed/cancelled

// Job Data Structure
{
  _id: "job123",
  type: "export",
  status: "running",
  progress: { percent: 75 },
  data: {
    projectId: "project456",
    exportType: "scans",
    exportVariables: { dateRange: "last30days" },
    userId: "user789",
    exportZoneSessionsResetted: false,
    dependentJobIds: ["childjob1", "childjob2"]
  },
  created: new Date(),
  log: [
    { level: "info", message: "Export started" },
    { level: "warning", message: "Some records skipped" }
  ]
}

📁 File Storage System

// Export File Structure
{
  _id: "file123",
  name: "scans_export_20241103_143052.xlsx",
  meta: {
    projectId: "project456",
    type: "scans",
    jobId: "job123",
    createdAt: new Date(),
    fileSize: 2048576,
    downloadCount: 3
  }
}

🔐 Security Features

Role-based Access: All operations require specific permissions
Project Isolation: Users can only access their project exports
File Access Control: Download links are user-specific and time-limited
Audit Trail: Complete logging of all export operations
Input Validation: All export parameters validated before processing

📈 Performance Optimizations

Job Queuing: Prevents resource conflicts with single-type job limits
Background Processing: Long-running exports don't block UI
Progress Streaming: Real-time progress updates via reactive subscriptions
File Compression: Large exports automatically compressed
Cleanup Automation: Automatic removal of old files and jobs

🔄 Integration Points

Project State: Exports respect project lifecycle states
Zone Sessions: Creates temporary sessions for data extraction
User Permissions: Dynamic permission checking for all operations
File Storage: Integration with GridFS or external storage systems
Job Processing: Uses Meteor Job Collection for reliable background processing

📊 Export Variable Types

// Variable Configuration Types
{
  "string": "Simple text input",
  "array": "Dropdown with predefined options",
  "date": "Date picker component",
  "boolean": "Checkbox input",
  "number": "Numeric input with validation"
}

This documentation covers the comprehensive export and reporting system. For specific export configurations or advanced job management, consult with your system administrator.

🎯 Overview​

🔐 Access Requirements​

👥 Required Roles & Permissions​

🌐 Permission Scope​

💻 Interface Layout​

📊 Main Export Overview​

🎛️ Job Management Interface​

⭐ Key Features​

📊 Export Types & Categories​

🔄 Job Management System​

📁 File Management​

📘 Usage Guide​

🚀 Starting an Export​

📊 Monitoring Export Jobs​

📁 Downloading Reports​

🔧 Managing Export Sessions​

⚠️ Troubleshooting​

🚫 Common Issues​

📱 Mobile/Responsive Considerations​

🔄 Performance Tips​

🛠️ Technical Details​

📊 Export Configuration Structure​

🔧 Job Lifecycle States​

📁 File Storage System​

🔐 Security Features​

📈 Performance Optimizations​

🔄 Integration Points​

📊 Export Variable Types​