Skip to content

Data Management

Guide for managing application data, including data export, data import, sample data, and the Django admin interface.

Target Audience: Organization owners, organization admins, superusers

Data Export

Organization Owners and Admins can create a full backup of their organization data by exporting it to a JSON file.

Exported Data

An export includes all data belonging to the selected organization:

Category Included Data
Hives Hive details, photos, breeding hive extensions
Queens Queen records, lineage (mother queen), breeding record links
Inspections All hive inspection records
Operations Feeding, treatments, maintenance, hive combines, queen replacements
Harvests Harvest records, honey batches, buckets, and jars
Breeding Queen breeding records, colony splits
Warehouse Inventory items, locations, transactions, product sales
Configuration Organization settings, configurable choices per category
Photos Operation photos and hive photos (optional, base64-encoded)

Creating an Export

  1. Navigate to Data Exchange in the sidebar
  2. Open the Exports list
  3. Click Create Export
  4. Choose whether to include media files (photos):
    • Enabled (default): Photos are embedded as base64-encoded data in the JSON file. This increases the file size significantly.
    • Disabled: Only data is exported, without photos. This produces a smaller file.
  5. Click Create Export
  6. The export is processed and appears in the export list when complete

Downloading an Export

  1. Go to the Exports list
  2. Find the completed export (status: Completed)
  3. Click the Download button

The downloaded file is named export_<organization>_<timestamp>.json.

Export File Format

Exports use JSON format (version 2.0.0) with the following structure:

  • export_version: Format version for compatibility checking
  • export_date: Timestamp of when the export was created
  • organization_id / organization_name: Source organization
  • data: All exported records organized by model name
  • metadata: Record counts, list of exported models, SHA-256 checksum

Deleting an Export

  1. Go to the Exports list
  2. Click the Delete button next to the export you want to remove
  3. Confirm the deletion

Deleting an export removes both the database record and the associated file from the server. Old exports are automatically cleaned up when more than 10 completed exports exist for an organization.

Note

Only Owners and Admins can create, download, and delete exports. Members and Viewers do not have export access.

Data Import

Organization Owners, Admins, and Superusers can import data into an organization from a previously exported JSON file.

Import Strategies

When importing data, you choose one of two strategies:

Strategy Behavior Risk Level
Merge (recommended) Keeps existing data. New records are added. If a record with the same name already exists, the imported record is automatically renamed (e.g., "My Hive" becomes "My Hive (imported)"). Low
Full Restore Deletes all existing organization data first, then imports all records from the file. High -- all current data is permanently deleted

Danger

Full Restore permanently deletes all existing data for the organization before importing. This action cannot be undone. Always create a fresh export backup before using Full Restore.

Importing Data

  1. Navigate to Data Exchange in the sidebar
  2. Open the Imports list
  3. Click Upload & Import
  4. Select a JSON export file (.json, maximum 50 MB)
  5. Choose the import strategy: Merge or Full Restore
  6. Click Upload & Validate
  7. Review the Import Preview page:
    • Validation status (passed or failed with error details)
    • Any warnings (e.g., version migration, existing data detected)
    • Total record count and breakdown by model
  8. If validation passed, click Execute Import to start the import
  9. After completion, view the Import Detail page for a summary of what was imported

Validation Checks

Before import, the file is validated for:

  • File format: Must be a valid JSON file with .json extension
  • File size: Maximum 50 MB
  • Structure: Must contain required fields (export_version, export_date, organization_id, data, metadata)
  • Version compatibility: Export version must be between 1.0.0 and 2.0.0 (current)
  • Checksum: Integrity check when a SHA-256 checksum is present in the file
  • Conflict detection: Warns if the target organization already has existing data

Version Migration

Import files from older export versions (1.0.0) are automatically migrated to the current format (2.0.0) during import. The migration handles renamed fields and removed models from earlier versions.

Import Behavior Details

During import, the system:

  • Temporarily disconnects signals (health status tracking, automatic batch creation, inventory transactions) to prevent unintended side effects
  • Maps old record IDs to new IDs so that relationships between records are preserved
  • Resolves foreign key references in a two-pass process: first creates records, then links deferred relationships (queen-to-hive assignments, harvest-to-batch links)
  • Runs the entire import inside a database transaction -- if any error occurs, all changes are rolled back
  • Skips user-specific fields (created_by, inspector, etc.) since users are not transferred between systems
  • Preserves unique identifiers (batch charge numbers, bucket numbers, jar numbers) when possible

Viewing Import History

  1. Go to the Imports list to see all past imports
  2. Click View Details on any import to see:
    • Import type and status
    • Completion timestamp
    • Summary of created records (by model)
    • Any errors that occurred
    • Renamed records (for merge imports)

Deleting an Import Record

  1. Go to the Imports list
  2. Click the Delete button next to the import you want to remove
  3. Confirm the deletion

Note

Deleting an import record only removes the import job entry and uploaded file. It does not undo any data that was already imported.

Sample Data

Bifolk includes a sample data import feature for demonstration and testing purposes. This is useful for new organizations that want to explore the application with realistic beekeeping data.

What Sample Data Includes

Dataset Size Content Approximate Records
Quick Demo (Minimal) 5 hives, 5 queens, basic inspections, harvest records, breeding records, inventory items ~30 records
Full Dataset (Comprehensive) 10-15 hives, 15-20+ queens, extensive inspection history, harvest records, breeding lineage, inventory items ~200+ records

The comprehensive dataset offers additional options:

  • Include sample photos: Hive photos and operation documentation images
  • Include inventory transactions: Transaction history and product sales records

Importing Sample Data

  1. Navigate to Data Exchange in the sidebar
  2. Click Sample Data
  3. Select a dataset size: Quick Demo or Full Dataset
  4. If using Full Dataset, configure the advanced options (photos, transactions)
  5. If your organization already has data, check the confirmation box acknowledging that sample data will be added alongside existing records
  6. Click Import Sample Data
  7. After completion, a summary page shows what was created

Tip

It is recommended to import sample data into an empty organization. If you want to keep your real data separate, create a new test organization first.

Sample Data via Command Line

System administrators can also load sample data through the command line:

docker compose exec bifolk-app python manage.py load_sample_data

This creates a complete set of sample data including users, organizations, hives, inspections, and more.

Django Admin Interface

The Django admin interface provides direct database access for superusers.

Accessing Django Admin

  • URL: http://your-domain/admin/
  • Requires: Superuser account

Available Sections

Section Models
Authentication Users, Groups
Organizations Organizations, Memberships, Invitations, Settings
Hives Hives, Queens, Inspections, Harvests, Operations
Breeding Queen Breeding, Colony Splits
Warehouse Inventory Items, Transactions, Sales
System Config Choice Categories, Configurable Choices
Notifications Notifications
Data Exchange Export Jobs, Import Jobs

Common Admin Tasks

  • Bulk delete records: Select multiple records, use "Delete selected" action
  • Search: Use the search bar to find specific records
  • Filter: Use sidebar filters to narrow results
  • View history: Check the change history of any record
  • View export/import jobs: Monitor the status of data exchange operations

Permissions

Data exchange operations require specific roles:

Operation Required Role
Export data Owner or Admin
Download export Owner or Admin
Delete export Owner or Admin
Import data Owner, Admin, or Superuser
Delete import Owner or Admin
Import sample data Owner, Admin, or Superuser
Django admin access Superuser

Note

The organization must be active for export and import operations to be available. Superusers can always perform import operations regardless of membership.