Data Onboarding (Generic)¶
This guide describes every data entity required to onboard a tenant into Mirabelle. It is tenant-agnostic; for concrete examples (pooled-asset, cycling, MRO), see the per-tenant guides under tenants/<name>/docs/.
For each entity you will find:
- The table name and column definitions (required vs optional)
- The business context explaining why the data matters
Minimum Viable Dataset¶
To get started with Mirabelle forecasting + supply planning, you must provide:
| # | Entity | Why |
|---|---|---|
| 1 | Items | Your product catalog |
| 2 | Locations | All warehouses, depots, customer sites, zones |
| 3 | Routes | How items flow between locations |
| 4 | Demand History | 2+ years of weekly demand per (item, site) |
| 5 | On-Hand Inventory | Current stock snapshot |
Everything else adds incremental value but is not required for day-1 forecasting.
Delivery Format¶
File format
- CSV or Excel (.xlsx) — one file per entity
- Column headers must match the names listed below
- Dates in ISO format (
YYYY-MM-DD); weekly demand dates = Monday of the week - Numbers use dot as decimal separator
- Text encoding: UTF-8
- Use your own ERP codes as
xuidvalues — Mirabelle maps them automatically during import
1. Items (item.csv)¶
Your product / part catalog.
| Column | Type | Required | Description |
|---|---|---|---|
xuid |
text | Yes | Your ERP SKU code (external universal ID) |
name |
text | Yes | Human-readable item name |
description |
text | No | Free-text description |
item_type_xuid |
text | No | Item category (see Item Types below) |
price |
number | No | Selling price |
cost |
number | No | Item-level cost |
unit_cost |
number | No | Unit cost (used by MEIO for safety-stock investment) |
expiry_period_weeks |
integer | No | Shelf life; leave empty if never expires |
priority_class |
text | No | One of: aog, critical, premium, standard (default), low |
strategic_weight |
number | No | Allocation scoring weight (default 0) |
revenue_weight |
number | No | Allocation scoring weight (default 0) |
criticality_weight |
number | No | Allocation scoring weight (default 0) |
For pooled-asset / reverse-logistics networks, each physical state is typically a separate SKU (e.g. serviceable vs unserviceable), and a REPAIR route converts one into the other via the route's source_item_id, not via the BOM.
2. Item Types (item_type.csv) — Optional¶
If you categorise items into types (e.g. pooled asset, fastener, raw material), provide this lookup table.
| Column | Type | Required | Description |
|---|---|---|---|
xuid |
text | Yes | Type code |
name |
text | Yes | Type name |
description |
text | No | Free-text description |
3. Locations / Sites (site.csv)¶
Your warehouses, depots, factories, and customer sites. Locations can be organised into zones (virtual collaborative pools) and regions.
| Column | Type | Required | Description |
|---|---|---|---|
xuid |
text | Yes | Your ERP site code |
name |
text | Yes | Human-readable site name |
description |
text | No | Free-text description |
site_type_xuid |
text | No | Site category (see Site Types below) |
longitude |
number | No | Geographic longitude |
latitude |
number | No | Geographic latitude |
zone_xuid |
text | No | Parent zone (for sites) or empty (for zones) |
region_xuid |
text | No | Parent region |
max_capacity_qty |
number | No | Total stock capacity; empty = unlimited |
Zone rows must come first
If you organise sites into regions or collaborative zones, provide zone rows first — site rows reference them via zone_xuid.
4. Site Types (site_type.csv) — Optional¶
If you classify sites into categories (depot, factory, customer, etc.), provide this lookup table.
| Column | Type | Required | Description |
|---|---|---|---|
xuid |
text | Yes | Type code |
name |
text | Yes | Type name |
description |
text | No | Free-text description |
5. Item-Location (item_location.csv)¶
Per-item, per-site planning parameters. This is where you specify ordering costs, holding rates, and the balancing excess ratio that controls how much stock a location can hold above its lead-time demand.
| Column | Type | Required | Description |
|---|---|---|---|
item_xuid |
text | Yes | Item code |
site_xuid |
text | Yes | Site code |
order_cost |
number | No | Fixed cost per order |
holding_rate |
number | No | Annual holding rate (%) |
cost_price |
number | No | Cost price at this location |
price |
number | No | Selling price at this location |
cost |
number | No | Cost at this location |
unit_cost |
number | No | Unit cost at this location |
balancing_excess_ratio |
number | No | X in "balance ≥ X × LTD + SL"; default 1.0 |
6. Routes / Supply Network (route.csv)¶
Most critical table
Routes define how items flow through your network. Every physical movement — replenishment, transfer, use, return, repair, balancing, purchase — is a route row.
| Column | Type | Required | Description |
|---|---|---|---|
item_xuid |
text | Yes | Item being moved |
site_xuid |
text | Yes | Destination site |
route_type_xuid |
text | Yes | Route type (see Route Types below) |
source_site_xuid |
text | No | Origin site (empty for BUY) |
lead_time |
integer | No | Total lead time in days |
pick_pack_time |
integer | No | Pick & pack time in days |
transit_time |
integer | No | Transit time in days |
inspection_time |
integer | No | Inspection time in days |
safety_lead_time |
integer | No | Safety lead time buffer in days |
min_qty |
number | No | Minimum order quantity |
mult_qty |
number | No | Order multiple (lot size) |
max_qty |
number | No | Maximum order quantity |
quota |
number | No | Fraction of demand served by this route (0–1) |
priority |
integer | No | Priority (lower = higher priority) |
unit_cost |
number | No | Cost per unit on this route |
order_cost |
number | No | Fixed cost per order |
yield |
number | No | Repair/processing yield (0–1); e.g. 0.92 = 8% scrap |
detention_time |
integer | No | Days the item is held at the destination (USE routes) |
stock_type |
text | No | good (default) or bad — the stock pool the route moves |
end_date |
date | No | Route validity end date |
Route Types and Their Semantics¶
| Route Type | Meaning | Key Fields |
|---|---|---|
| BUY | External supplier → site (new stock entering the network) | unit_cost, lead_time |
| TRANSFER | Site → Site (replenishment or inter-site) | quota splits demand across multiple routes |
| MAKE | Assembly / production at a site (BOM-driven) | BOM edges define the build |
| USE | Site → Consumer (item deployed / in use) | detention_time = days at consumer; return_rate |
| RETURN | Consumer → Site (reverse-logistics flow) | stock_type = bad |
| REPAIR | Site (bad in) → Site (good out) | yield = fraction surviving processing |
| BALANCING | Site ↔ Site (intra-zone excess redistribution) | Bi-directional; stock_type good or bad |
7. Route Types (route_type.csv)¶
Defines the types of supply routes in your network.
| Column | Type | Required | Description |
|---|---|---|---|
xuid |
text | Yes | Type code |
name |
text | Yes | Type name |
planning_type |
text | Yes | Planning engine category (BUY, TRANSFER, MAKE, RETURN, REPAIR, BALANCING, USE) |
description |
text | No | Free-text description |
8. Route Quota Overrides (route_quota_override.csv) — Optional¶
Historical changes to route quotas over time. For example, when a customer contract changes and the split between two routes shifts.
| Column | Type | Required | Description |
|---|---|---|---|
item_xuid |
text | Yes | Item code |
site_xuid |
text | Yes | Destination site |
route_type_xuid |
text | Yes | Route type |
effective_date |
date | Yes | Date the new quota takes effect |
expiry_date |
date | No | Date the quota expires (empty = still active) |
quota |
number | Yes | New quota value (0–1) |
note |
text | No | Reason for the change |
9. On-Hand Inventory (on_hand.csv)¶
Current stock snapshot at each location, optionally separated by stock type.
| Column | Type | Required | Description |
|---|---|---|---|
item_xuid |
text | Yes | Item code |
site_xuid |
text | Yes | Site code |
qty |
number | Yes | Current quantity on hand |
on_hand_type_xuid |
text | No | Stock type (see On-Hand Types below) |
batch |
text | No | Batch / lot number |
unit_cost |
number | No | Unit cost for this stock |
expiry_date |
date | No | Expiry date (for perishable items) |
10. On-Hand Types (on_hand_type.csv) — Optional¶
Defines the categories of stock you track (e.g. unrestricted, quarantined, in-transit).
| Column | Type | Required | Description |
|---|---|---|---|
xuid |
text | Yes | Type code |
name |
text | Yes | Type name |
description |
text | No | Free-text description |
planning_type |
text | No | Engine classification: lowercase bad for unserviceable stock; anything else (e.g. AVAILABLE, good, new) = serviceable. Case-sensitive — see On-Hand Stock Types. |
allocation_sequence |
integer | No | Priority order for allocation (1 = highest) |
See On-Hand Stock Types for the full classification rule, where good/bad stock surfaces in the app, and a worked tenant example.
11. Customers (customer.csv)¶
Your customers.
| Column | Type | Required | Description |
|---|---|---|---|
code |
text | Yes | Unique customer code |
name |
text | Yes | Customer name |
customer_type |
text | No | Free-text category (e.g. enterprise, retail) |
country |
text | No | ISO country code |
contact_email |
text | No | Planner contact email |
longitude |
number | No | Geographic longitude |
latitude |
number | No | Geographic latitude |
12. Customer-Site Links — REMOVED (Sept 2026)¶
customer_site was dropped project-wide: no engine consumed it. The wash/return parameters live on RETURN routes (return_wash_rate, repair_wash_rate).
<!-- historical section removed
Maps customers to their designated return-logistics depots. Useful for reverse-logistics networks.
| Column | Type | Required | Description |
|---|---|---|---|
customer_code |
text | Yes | Customer code |
site_xuid |
text | Yes | Return depot site code |
wash_rate |
number | No | Fraction of returned items surviving processing (0–1) |
lead_time |
number | No | Days for the return journey |
13. Demand History (demand_actuals.csv)¶
Core time-series data
This is the primary input for forecasting. Provide at least 2–3 years of weekly data for best forecast accuracy.
| Column | Type | Required | Description |
|---|---|---|---|
item_xuid |
text | Yes | Item code |
site_xuid |
text | Yes | Site code (where demand occurs) |
date |
date | Yes | Monday of the week (YYYY-MM-DD) |
qty |
number | Yes | Total demand quantity for that week |
demand_type |
text | No | e.g. Regular demand, Urgent demand |
customer_code |
text | No | Customer code |
is_forecast |
boolean | No | true (default) for historical demand; false for firm orders |
channel_xuid |
text | No | Sales channel |
priority_class |
text | No | Priority class |
14. Firm Demand Orders (demand_actuals.csv with is_forecast=false)¶
Confirmed customer orders for the near-term horizon. These are in the same table as demand history, distinguished by is_forecast = false. They consume the statistical forecast in the netting step.
| Column | Type | Required | Description |
|---|---|---|---|
item_xuid |
text | Yes | Item code |
site_xuid |
text | Yes | Site code |
date |
date | Yes | Required delivery date |
qty |
number | Yes | Order quantity |
is_forecast |
boolean | Yes | Must be false for firm orders |
order_id |
text | No | Your ERP order reference |
15. External Features (feature_values.csv) — Optional¶
Customer-submitted forecasts, promotions, price signals, weather, or any other exogenous regressor. Each feature is registered in the feature registry and loaded as a futr_exog regressor for ML/Neural forecast methods, gated by an automatic reliability score.
Per-customer forecasts are a special case: a feature named CF:{customer_code} is registered per customer, and the generic feature-reliability evaluator scores it against customer-attributed actuals.
| Column | Type | Required | Description |
|---|---|---|---|
feature_name |
text | Yes | Feature name (e.g. CF:CUST01, PROMO, PRICE) |
item_xuid |
text | No | Item code (series-scoped feature); empty for global |
site_xuid |
text | No | Site code (series-scoped feature); empty for global |
date |
date | Yes | Feature date (Monday of the week for weekly) |
value |
number | Yes | Feature value |
future_available |
boolean | No | true if the value is known in advance (futr_exog) |
16. Firm Supply Orders (firm_supply_orders.csv)¶
Open purchase, transfer, return, repair, and balancing orders already in the pipeline.
| Column | Type | Required | Description |
|---|---|---|---|
external_id |
text | Yes | Your ERP order reference |
item_xuid |
text | Yes | Item code |
site_xuid |
text | Yes | Destination site |
source_site_xuid |
text | No | Origin site (for TRANSFER, RETURN, REPAIR) |
order_type |
text | Yes | One of: BUY, TRANSFER, RETURN, REPAIR, BALANCING |
qty |
number | Yes | Order quantity |
release_dt |
date | Yes | Order release date |
arrival_dt |
date | Yes | Expected arrival date |
unit_cost |
number | No | Cost per unit |
order_cost |
number | No | Fixed cost per order |
erp_status |
text | No | One of: firm, released, in_transit, received |
received_qty |
number | No | Qty received so far |
17. Processing Capacity (capacity.csv) — Optional but Recommended¶
Capacity constraints on how many items a site can process per week (e.g. a repair/wash line). Without this data, the supply engine runs constrained routes unconstrained — it will plan unlimited throughput regardless of actual capacity.
| Column | Type | Required | Description |
|---|---|---|---|
site_xuid |
text | Yes | Site code |
resource_type |
text | Yes | Resource type (e.g. WASH, REPAIR) |
capacity_per_week |
number | Yes | Maximum units that can be processed per week |
Without capacity data
If capacity.csv is not provided, capacity-constrained routes run unconstrained. The supply engine will plan as much throughput as needed, which may exceed your actual capacity. This leads to overly optimistic supply plans.
18. Currency Conversions (currency_conversion.csv) — Only if Multi-Currency¶
| Column | Type | Required | Description |
|---|---|---|---|
from_currency |
text | Yes | Source currency code (e.g. EUR) |
to_currency |
text | Yes | Target currency code (e.g. USD) |
rate |
number | Yes | Conversion rate |
effective_date |
date | Yes | Date the rate takes effect |
source |
text | No | Rate source (e.g. ECB, Bloomberg) |
Optional / Domain-Specific Tables¶
The following tables are optional and only needed for specific business models:
| Table | When needed |
|---|---|
| Bill of Materials | MAKE/assembly routes (BOM edges define the build) |
| Purchase Receipts | Historical supplier lead-time data for parametric lead-time distributions |
| Causal / asset data | Asset-driven demand (asset types, failure rates, fleet plans) — see the MRO / fleet tenant guides |
| Calendars | Sites with holiday shutdowns or non-7-day operating weeks |