Skip to main content
Import represents an individual execution of an ImportDefinition. Each Import record tracks the status, progress, and metadata of a bulk data import operation.

​
Core Purpose

  • Execution Tracking: Records each run of an import processor
  • Status Management: Tracks progress from pending to completed/failed
  • Audit Trail: Links imports to users and organizations
  • Error Handling: Stores error messages when imports fail

​
Entity Structure

Import {
  id: "imp-...",
  importDefinitionId: "impdef-...",  // The definition used
  userId: "user-...",                 // Who executed the import
  organizationId: "org-...",          // Organization context
  rowCount: 150,                      // Total rows in source file
  status: "completed",                // pending, processing, completed, failed
  error: null,                        // Error message if failed
  processedAt: "2024-01-15T10:30:00Z" // When processing completed
}

​
Import Lifecycle

1. Creation: Import record created when user initiates an import 2. Processing: Status changes to “processing” during execution 3. Completion: Status becomes “completed” with processedAt timestamp 4. Failure: Status becomes “failed” with error message stored

​
Status Values

StatusDescription
pendingImport created but not yet started
processingCurrently processing rows
completedSuccessfully finished
failedEncountered an error

​
Relationships

ImportDefinition: Each Import uses one ImportDefinition for transformation rules User: Tracks which user initiated the import Organization: Scopes the import to an organization ImportResult: One Import can have many ImportResult records (one per site/period)

​
Row Count

The rowCount field stores the total number of rows in the source file before processing. This helps track:
  • How much data was provided
  • Progress during processing
  • Comparison with actual results produced

​
Error Handling

When an import fails, the error field contains details: 
{
  "status": "failed",
  "error": "Invalid column mapping: 'consumption' not found in source file"
}
Common error scenarios:
  • Missing required columns
  • Invalid data types
  • Processor code errors
  • Database constraint violations

​
Access Control

  • Imports are scoped to organizations via RLS policies
  • Users can only see imports from their current organization
  • The executing user is recorded but doesn’t restrict access

​
Querying Imports

Recent imports for an organization: 
SELECT * FROM "Import"
WHERE "organizationId" = 'org-123'
ORDER BY "createdAt" DESC
LIMIT 10;
Failed imports: 
SELECT * FROM "Import"
WHERE status = 'failed'
  AND "organizationId" = 'org-123';