Skip to content

System Configuration

Guide to Bifolk's configurable choices system for managing dropdown options.

Target Audience: System administrators, organization owners and admins

Overview

Bifolk uses a SystemConfig module that allows administrators to customize dropdown options across the application. Instead of hard-coded choices, many dropdown fields are populated from configurable database records that belong to your organization.

Choice Categories

When Bifolk is first set up, 28 choice categories are automatically created. Each category groups related options that appear in dropdown fields throughout the application. The warehouse module adds one additional category (item_type) for inventory items.

Categories are organized by the area of the application they serve.

Hive Management

Category Code Display Name Used For Default Choices
hive_style Hive Style Hive construction type (e.g., when creating or editing a hive) Langstroth, Top Bar, Warre, Dadant, National
health_status Health Status Health status for hives and queens Excellent, Good, Fair, Poor, Critical, Unknown
temperament Temperament Colony temperament observed during inspections Calm, Moderate, Aggressive
combine_method Combine Method Method used when combining two hives Newspaper Method, Direct Combination, Slow Merge, Other

Inspections

Category Code Display Name Used For Default Choices
inspection_status Inspection Status Workflow status of hive inspections Planned, In Progress, Completed, Cancelled
drone_presence Drone Presence Level of drone activity observed during an inspection None, Few, Moderate, Many, Very Many

Queens

Category Code Display Name Used For Default Choices
queen_origin Queen Origin How the queen was acquired Bred Here, Purchased, Swarm Capture, Supersedure, Emergency Cell, Unknown
queen_replacement_method Queen Replacement Method Method for introducing a new queen Direct Introduction, Cage Introduction, Push-in Cage, Walk-away Split, Queen Cell Introduction, Other
queen_replacement_reason Queen Replacement Reason Reason for replacing a queen Old Age, Poor Laying Pattern, Aggressive Colony, Disease/Health Issues, Supersedure, Breeding Upgrade, Other

Breeding

Category Code Display Name Used For Default Choices
breeding_method Breeding Method Method used for queen breeding Grafting, Natural Queen Cells, Jenter Kit, Nicot System, Walk-Away Split, Other
breeding_status Breeding Status Status stages of the breeding process Planning, Grafted, Accepted, Capped, Emerged, Mated, Laying, Failed
breeding_quality Breeding Quality Quality assessment of breeding results Excellent, Good, Fair, Poor

Colony Splits

Category Code Display Name Used For Default Choices
split_type Split Type Type of colony split or reproduction Standard Split, Walk-Away Split, Nucleus Colony, Captured Swarm, Artificial Swarm, Other
split_status Split Status Status of a colony split operation Planned, Completed, Queen Right, Queenless, Failed, Combined Back

Operations (Feeding, Treatment, Maintenance)

Category Code Display Name Used For Default Choices
operation_status Operation Status Workflow status shared by all operations (feeding, treatment, maintenance) Planned, In Progress, Completed, Cancelled
operation_priority Operation Priority Priority level shared by all operations Low, Medium, High, Urgent
feed_type Feed Type Type of supplemental feed Sugar Syrup, Fondant, Pollen Patty, Protein Supplement, Other
treatment_type Treatment Type Type of disease or pest treatment Varroa Mite Treatment, Nosema Treatment, Foulbrood Treatment, Small Hive Beetle, Wax Moth, Other
treatment_effectiveness Treatment Effectiveness How effective a treatment was Excellent, Good, Fair, Poor, Unknown
maintenance_type Maintenance Type Type of hive or equipment maintenance Repair, Cleaning, Painting, Box Addition/Removal, Frame Replacement, Equipment Upgrade, Winterization, Other

Harvests

Category Code Display Name Used For Default Choices
honey_type Honey Type Type of honey by floral source (used on harvest records and honey batches) Spring Blossom, Wildflower, Clover, Acacia, Forest Honey, Rapeseed, Linden

Warehouse & Inventory

Category Code Display Name Used For Default Choices
equipment_type Equipment Type Types of beekeeping equipment Hive Box/Super, Frame, Foundation, Feeder, Queen Excluder, Tool, Protective Gear, Other Equipment
supply_type Supply Type Types of consumable supplies Feed, Medication/Treatment, Packaging Material, Other Supply
product_type Product Type Types of bee products Honey, Beeswax, Propolis, Pollen, Royal Jelly, Other Product
unit_type Unit Type Units of measurement for inventory quantities Piece, Kilogram, Liter, Jar, Box, Frame
item_type Item Type Specific inventory item types (created by the warehouse module) Box, Frame, Smoker, Veil, Gloves, Uncapping Knife, Extractor Parts, Jar, Wax Sheet, Bucket, Honey, Pollen, Propolis, Sugar Syrup, Fondant, Pollen Patty, Other

Sales & Transactions

Category Code Display Name Used For Default Choices
transaction_type Transaction Type Types of inventory transactions Purchase, Sale, Production, Usage/Consumption, Harvest, Loss/Damage, Adjustment, Transfer, Return

System-managed transaction types

Six transaction types are written automatically by the application and cannot be modified or deleted: Sale, Harvest, Usage, Return, Batch Register, and Adjustment. These are shown in an info banner on the Transaction Type configuration page (/system/transaction_type/). You can still add your own custom types alongside them.

| payment_method | Payment Method | Payment methods for sales | Cash, Card, Bank Transfer, Other |

Managing Choices

Accessing System Configuration

  1. Go to System > System Configuration in the sidebar
  2. You see a list of all choice categories with the number of choices configured for your organization

Note

Only users with Admin or Owner role in at least one organization can access System Configuration.

Loading Default Choices

If you are starting with an empty system, you can load a set of default choices for all categories.

  1. Open System > System Configuration
  2. Click the Load Defaults button
  3. Default choices are created for your current organization

Tip

You can also load defaults using the command line: python manage.py load_default_categories

Adding a Choice

  1. Select a category from the list
  2. Click Add Choice
  3. Fill in:
  4. Label: Display text for this choice (e.g., "Acacia Honey"). A unique internal value is automatically generated from the label.
  5. Description (optional): Additional details about this choice
  6. Active: Whether this choice is available for selection
  7. Default: Whether this is the pre-selected default for this category. Only one choice per category and organization can be the default.
  8. Organization: Which organization this choice belongs to
  9. Click Save

New choices are automatically placed at the end of the list.

Note

The internal Value field is automatically generated from the label as a URL-friendly identifier (e.g., "Acacia Honey" becomes acacia-honey). You do not need to enter it manually.

Editing a Choice

  1. Select the choice from the category list
  2. Click the edit button (pencil icon)
  3. Update the fields as needed
  4. Click Save

Reordering Choices

Drag and drop choices directly in the list to change the order in which they appear in dropdowns. Click and hold the grip icon (⠿) on the left of a row, drag it to the desired position, and release — the new order is saved automatically.

Note

Global choices (shown with a Global badge) cannot be reordered by organisation admins. Only choices belonging to your organisation have a draggable grip icon.

Deleting a Choice

Choices can only be deleted if no other records reference them. The system automatically checks for references before allowing deletion.

  1. Click the delete button (trash icon) next to the choice
  2. If the choice is referenced by other records (e.g., hives, harvests, inspections), the system shows which records use it and prevents deletion
  3. If the choice is not referenced, confirm the deletion

Warning

If a choice cannot be deleted because it is in use, consider deactivating it instead.

Deactivating a Choice

Instead of deleting a choice (which may not be possible if records reference it), deactivate it:

  1. Edit the choice
  2. Uncheck Active
  3. Save

Deactivated choices are no longer shown in dropdowns but existing records referencing them are preserved.

Hive Style Special Fields

The Hive Style category has additional fields for configuring weight parameters used in honey harvest estimation:

Field Description
Brood Chamber Weight (kg) Weight of an empty brood chamber box
Honey Chamber Weight (kg) Weight of an empty honey super box
Honeycomb Weight (kg) Weight of empty wax honeycomb frames per honey super

These additional fields only appear when editing choices in the Hive Style category.

Harvest Estimation Formula

During hive inspections, if the total hive weight is recorded along with chamber counts, the system estimates harvestable honey:

Estimated Harvest = Total Weight
                   - (Brood Chambers x Brood Chamber Weight)
                   - (Honey Chambers x Honey Chamber Weight)
                   - (Honey Chambers x Honeycomb Weight)

The honeycomb weight is subtracted because the wax comb remains after honey extraction.

Setting Weight Values

When configuring hive styles, enter accurate weight values for your specific hive equipment. This enables more accurate harvest predictions during inspections.

Organization-Specific Choices

All choices belong to a specific organization. When you create a choice, it is assigned to your current organization (or you can select a different one if you manage multiple organizations).

When a user opens a dropdown in a form, they see only the choices configured for their current organization.

Note

Staff users (superusers) can create choices for any organization and see choices from all organizations.

Missing Configuration Notifications

When you log in, the system automatically checks whether your organization has configured choices for all active categories. If any category has no choices, you receive a notification with a link to the configuration page.

These notifications:

  • Are created once per login (not repeated within 24 hours)
  • Only appear for categories that have no active choices for your organization
  • Include a direct link to the relevant category page
  • Are sent only to users with Owner or Admin role

Default Choices

When Bifolk is first installed, the 28 choice categories are created automatically (without any choices). Choices can be added in three ways:

  1. Load Defaults button in System Configuration -- creates a standard set of choices for your organization
  2. Sample Data via the Data Exchange module -- includes choices as part of the sample dataset
  3. Manual entry -- add choices one by one through the interface

When a dropdown field in a form has no options configured, the system displays a warning message ("No options configured") and a link to the relevant System Configuration page. This allows you to quickly navigate to the configuration and add the missing choices without leaving your current workflow.