DataExchange App Reference¶

The DataExchange app provides organization data backup and restore functionality, import/export with media support, version compatibility handling, and sample data loading for demos and testing.

Overview¶

Location: app/dataexchange/

Purpose: Organization data backup/restore, sample data import

Key Models: ExportJob, ImportJob

Dependencies: All other apps (exports/imports all organization data), notifications (completion alerts)

File Structure¶

dataexchange/
├── models.py              # ExportJob, ImportJob
├── views/                 # Views package (2 modules)
│   ├── __init__.py        # Re-exports all 10 views
│   ├── export_views.py    # 4 views (list, create, download, delete)
│   └── import_views.py    # 6 views (list, upload, preview, detail, delete, sample)
├── urls.py                # 10 URL patterns
├── permissions.py         # 2 permission mixins
├── validators.py          # Import file validation
├── compatibility.py       # Version compatibility and migration
├── mappings.py            # Model mappings and field configurations
├── admin.py               # Django admin configuration
├── services/
│   ├── export_service.py  # Export generation
│   ├── import_service.py  # Import execution
│   ├── image_utils.py     # Image handling
│   ├── rename_utils.py    # Field renaming
│   └── sample_data_service.py # Sample data
├── exporters/
│   ├── base.py            # DataExporter base class
│   └── model_exporters.py # 27 model-specific exporters
└── management/commands/
    └── generate_sample_export.py

Models¶

ExportJob¶

Tracks export operations for organization data backup.

Status flow: pending → processing → completed / failed

Field	Type	Description
organization	FK(Organization)	Organization being exported
created_by	FK(User)	User who initiated the export
status	CharField	pending, processing, completed, failed
file_path	CharField	Path to generated export file
include_media	BooleanField	Whether to include media files (default: True)
total_records	IntegerField	Count of exported records
file_size	BigIntegerField	File size in bytes
error_message	TextField	Error details if export failed
created_at	DateTimeField	When the job was created
completed_at	DateTimeField	When the job finished

Indexes: (organization, created_at), (status)

ImportJob¶

Tracks import operations for organization data restore.

Status flow: pending → validating → processing → completed / failed

Field	Type	Description
organization	FK(Organization)	Target organization for import
imported_by	FK(User)	User who initiated the import
status	CharField	pending, validating, processing, completed, failed
file_path	CharField	Path to uploaded import file
import_type	CharField	full, merge (default), or partial
summary	JSONField	Import results summary
error_message	TextField	Error details if import failed
created_at	DateTimeField	When the job was created
completed_at	DateTimeField	When the job finished

Indexes: (organization, created_at), (status)

Views¶

Export Views¶

View	Type	Purpose
ExportListView	ListView	List exports for organization, paginate 20, sortable columns
ExportCreateView	View	Show export form (GET), create and generate export (POST)
ExportDownloadView	View	Download completed export as JSON file
export_delete_view	Function	Delete export job and associated file (POST, owner/admin only)

Import Views¶

View	Type	Purpose
ImportListView	ListView	List imports for organization, paginate 20, sortable columns
ImportUploadView	View	Show upload form (GET), validate and create import job (POST)
ImportPreviewView	View	Preview import with validation results (GET), execute import (POST)
ImportDetailView	View	Display import details and summary
import_delete_view	Function	Delete import job and associated file (owner/admin only)

Sample Data¶

View	Type	Purpose
SampleDataImportView	View	Show sample data form (GET), import sample data (POST)

The sample data import supports two modes: minimal (basic data) and comprehensive (full dataset with optional photos and transactions).

Permissions¶

Location: app/dataexchange/permissions.py

Mixin	Required Role	Details
CanExportOrganizationDataMixin	Owner or Admin	Requires active organization
CanImportOrganizationDataMixin	Owner or Admin (or Superuser)	Superusers bypass org membership checks

Both mixins resolve the organization from the view's get_organization() method or from the middleware's current_organization. They raise PermissionDenied if the user lacks the required role.

Exporters¶

Location: app/dataexchange/exporters/

DataExporter Base Class¶

The DataExporter base class provides common serialization functionality for all model exporters:

Automatically handles field serialization: ForeignKey to PK, ManyToMany to list of PKs, File/Image to base64, Date/DateTime to ISO format, JSONField stored as-is
export() returns a list of serialized dictionaries for all records in the queryset
get_queryset() must be overridden in subclasses to filter by organization

Model Exporters¶

27 model-specific exporters are defined, each extending DataExporter with organization-scoped querysets. They are listed in EXPORT_ORDER to maintain referential integrity during import:

Group	Models Exported
Organization	Organization, OrganizationSettings, OrganizationMembership
Configuration	ChoiceCategory, ConfigurableChoice
Warehouse	WarehouseLocation, InventoryItem
Hives	Hive, BreedingHive, Queen, HivePhoto, HiveInspection
Honey	HarvestRecord, HoneyBatch, HoneyBucket, HoneyJar
Breeding	QueenBreeding, ColonySplit
Operations	HiveFeeding, HiveTreatment, HiveMaintenance, HiveCombine, QueenReplacement
Sales	ProductSale, ProductSaleItem, InventoryTransaction
Media	OperationPhoto (uses GenericForeignKey with ContentType filtering)

Validators¶

Location: app/dataexchange/validators.py

The ImportValidator class performs multi-step validation on uploaded import files:

File size check -- maximum 500 MB
File extension check -- must be .json
JSON parsing -- validates valid JSON format
Structure validation -- checks for required fields: export_version, export_date, organization_id, data, metadata
Version compatibility -- checks against min/max supported versions
Checksum verification -- validates integrity if checksum present
Model validation -- ensures Organization data present, counts records
Conflict detection -- warns if organization already has existing data

The ValidationResult class holds the validation state with errors, warnings, and informational data.

The convenience function validate_import_file(file, organization) creates a validator and returns the result.

Compatibility¶

Location: app/dataexchange/compatibility.py

Handles version compatibility checking and data migration between export format versions.

Current version: 2.0.0

Minimum supported version: 1.0.0

Version Compatibility¶

The VersionCompatibility class checks if an export version is within the supported range and determines whether migration is needed.

Data Migration¶

The DataMigrator class applies sequential migrations along the version path.

v1.0.0 to v2.0.0 migration:

Removes deprecated models: Activity, FeedingRecord, TreatmentRecord, ActivityPhoto
Renames Queen fields: current_hive to hive, mother to mother_queen
Removes Queen field: father

Schema Validation¶

The SchemaValidator class validates the structure of export data, ensuring all required root fields are present and data types are correct.

Mappings¶

Location: app/dataexchange/mappings.py

Defines the configuration for how each model is handled during export and import operations.

FieldMapping¶

Per-field configuration including:

Whether to include in export/import
Required flag for import
Default values
Transform functions for import and export

ModelMapping¶

Per-model configuration including:

dependencies -- models that must be imported before this one
unique_fields -- fields used to identify existing records during merge
auto_fields -- fields to skip during import (e.g., id, created_at)
file_fields -- fields containing files/images (need base64 decoding)
fk_fields -- foreign key mappings (field_name to related model name)

27 model mappings are defined in MODEL_MAPPINGS, covering all exported models.

EXPORT_ORDER and IMPORT_ORDER define the dependency-respecting processing order.

Utility functions: get_model_mapping(), get_dependencies(), get_unique_fields(), get_fk_fields(), should_skip_field_on_import(), get_file_fields(), validate_import_order()

Import Types¶

Type	Behavior
full	Delete existing organization data, import everything
merge	Keep existing data, add imported data (default)
partial	Selective import of specific models

URL Patterns¶

dataexchange/exports/                       --> ExportListView (export-list)
dataexchange/exports/create/                --> ExportCreateView (export-create)
dataexchange/exports/<int:pk>/download/     --> ExportDownloadView (export-download)
dataexchange/exports/<int:pk>/delete/       --> export_delete_view (export-delete)
dataexchange/imports/                       --> ImportListView (import-list)
dataexchange/imports/upload/                --> ImportUploadView (import-upload)
dataexchange/imports/<int:pk>/preview/      --> ImportPreviewView (import-preview)
dataexchange/imports/<int:pk>/              --> ImportDetailView (import-detail)
dataexchange/imports/<int:pk>/delete/       --> import_delete_view (import-delete)
dataexchange/sample-data/                   --> SampleDataImportView (sample-data-import)

Admin Interface¶

Location: app/dataexchange/admin.py

Both models are registered with full admin configuration:

ExportJobAdmin -- List display with organization, status, records, file size. Filters by status, include_media, date. Grouped fieldsets for basic info, options, results, and timestamps.
ImportJobAdmin -- List display with organization, status, import type. Filters by status, import type, date. Grouped fieldsets for basic info, file, results, and timestamps.

Signals¶

The DataExchange app has no signal handlers of its own. Export and import completion triggers notifications via signal handlers in the Notifications app (notifications/signals.py).

When an ExportJob or ImportJob is saved with status completed or failed, a notification is automatically created for the user who initiated the operation.

Services (Summary)¶

Services handle the core business logic and are documented in detail in the services documentation (Chunk 2).

Service	Key Functions
Export Service	`create_export()`, `generate_export_file()`, `cleanup_old_exports()`
Import Service	`create_import_job()`, `execute_import()`
Sample Data Service	`import_sample_data()` (modes: minimal, comprehensive)