Initial Data Upload
Initial data upload lets you define seed data as JSON and have the framework load it automatically on server start. Instead of clicking through the UI or writing ad-hoc scripts, you describe what to create in structured files and the framework handles the rest.
How It Works
flowchart LR
A["lex_config.py
INITIAL_DATA = '...'"] --> B["Server starts
(lex start)"]
B --> C{"All referenced
models empty?"}
C -- Yes --> D["Process JSON files
create / update / delete"]
C -- No --> E["Skip — data
already exists"]On every server start, Lex App:
- Reads the
INITIAL_DATApath fromlex_config.py - Validates the path exists and the JSON is well-formed
- Resolves all subprocess references to build a flat action list
- Checks whether every model referenced in the JSON has zero rows
- If all models are empty, processes each action in order
The auto-load is all-or-nothing. If even one referenced model has existing data, the entire load is skipped. This prevents accidental double-loading.
Configuration
Create (or edit) lex_config.py in your project root:
INITIAL_DATA = "Tests/test_data.json"The path is relative to your project root (the directory containing .env).
Legacy alternative:
_authentication_settings.py
Older projects may use_authentication_settings.pyinstead:initial_data_load = "Tests/basic_test/test_data.json"The framework checks
lex_config.pyfirst and falls back to_authentication_settings.py. New projects should always uselex_config.py.
JSON Format
Top-Level File (Subprocess List)
The file referenced by INITIAL_DATA is an ordered list of subprocess references:
[
{"subprocess": "Tests/01_create_teams.json"},
{"subprocess": "Tests/02_create_employees.json"},
{"subprocess": "Tests/03_create_expenses.json"}
]Each subprocess entry points to another JSON file containing the actual actions. Subprocesses are executed in order, so create parent objects before children that reference them.
Subprocesses can themselves contain
subprocessreferences — the framework flattens them recursively into a single ordered action list.
Action Files
Each subprocess file is a list of action objects:
[
{
"class": "Team",
"action": "create",
"tag": "team_design",
"parameters": {
"name": "Design",
"budget": 15000.00,
"manager_email": "[email protected]"
}
}
]Every action object has these fields:
Field | Required | Description |
|---|---|---|
| ✅ | Model class name (must match a registered model) |
| ✅ | One of |
| For | A label to reference this object later via |
| For | Field names → values to set |
| For | A Django queryset filter to find existing objects |
Actions
create
Creates a new model instance with the given parameters, then saves it.
{
"class": "Employee",
"action": "create",
"tag": "emp_anna",
"parameters": {
"first_name": "Anna",
"last_name": "Schmidt",
"team": "tag:team_design"
}
}The tag is stored in memory so later actions can reference this object via tag:emp_anna.
update
Finds an existing object via filter_parameters, then sets the fields in parameters:
{
"class": "Employee",
"action": "update",
"tag": "emp_anna_updated",
"filter_parameters": {
"email": "[email protected]"
},
"parameters": {
"role": "manager"
}
}filter_parameters is a standard Django field lookup dictionary — the framework calls Model.objects.filter(**filter_parameters).first() to locate the object.
delete
Deletes all objects matching filter_parameters:
{
"class": "InvestorTrackRecord",
"action": "delete",
"filter_parameters": {}
}An empty filter_parameters ({}) deletes all instances of that model. Use specific filters to target individual records.
Special Value Prefixes
tag: — Foreign Key References
Use the tag: prefix to reference an object created earlier in the same data load:
"team": "tag:team_design"This resolves to the actual model instance tagged team_design during a previous create action. Use it for ForeignKey, OneToOneField, or any field that expects a model instance.
datetime: — Date and Time Parsing
Use the datetime: prefix to parse date strings into Python datetime objects:
"date": "datetime:2026-01-15"The framework uses dateutil.parser, so most common formats work: 2026-01-15, 2026-01-15T09:30:00, 15/01/2026, etc.
File Uploads
For FileField parameters, provide the relative path to the file (from the project root). The framework reads the file and stores it using Django's default storage:
{
"class": "UploadInvestmentStructure",
"action": "create",
"tag": "upload_structure",
"parameters": {
"upload_name": "Structure Upload",
"upload_time": "datetime:2022-06-30",
"vehicle_file": "Tests/UploadFiles/Structure/VehicleUpload.xlsx",
"investor_file": "Tests/UploadFiles/Structure/InvestorUpload.xlsx"
}
}Auto-Load Conditions
The framework only auto-loads initial data when all of the following are true:
Condition | Details |
|---|---|
| Either in |
The path is valid | The file exists and contains well-formed JSON |
The JSON structure is correct | Top-level list of |
All referenced models are empty | Every model class mentioned in |
Server is starting normally | Running via |
If any condition fails, the auto-load is silently skipped.
To re-trigger the load after data already exists, drop and recreate the database:
lex create_db lex Init lex start
Execution Order
- The top-level JSON is read and all
subprocessreferences are recursively resolved into a flat list of action objects - Actions are processed in order — first file's actions, then second file's, etc.
- For each action, the model class is looked up from the registered models
tag:anddatetime:values inparameters(orfilter_parameters) are resolved- The action (
create,update, ordelete) is executed - If audit logging is enabled, each operation is recorded in the audit trail
Order matters. If Employee references Team via
tag:team_design, the Teamcreateaction must appear before the Employee action — either in the same file or in an earlier subprocess.
Example Project Structure
A typical initial data setup looks like:
Tests/
├── test_data.json ← Top-level subprocess list
├── 01_create_teams.json ← Create Team objects
├── 02_create_employees.json ← Create Employees (references Teams)
├── 03_create_expenses.json ← Create Expenses (references Employees)
└── UploadFiles/ ← Files for FileField parameters
└── Structure/
├── VehicleUpload.xlsx
└── InvestorUpload.xlsxINITIAL_DATA = "Tests/test_data.json"For a hands-on walkthrough, see the TeamBudget tutorial Part 2 which builds a complete initial data setup from scratch.
Was this helpful?
Your feedback shapes what we write next.
