1. Functional overview

Olive Oil Mill Manager turns Dolibarr into a complete Olive Oil Industry ERP Suite. It covers the entire business of a modern olive mill, from buying olives from growers through to selling bottled oil to the end customer, so that the mill no longer needs a separate specialised application.

1.1 Target users

·       Industrial olive oil mills

·       Olive growing cooperatives

·       Agricultural estates

·       Virgin olive oil producers

·       Oil extraction units

·       Oil bottling and packaging stations

1.2 Business chain covered

Olive growers → olive reception → quality control → olive storage → crushing → malaxing → oil extraction → separation → filtration → oil storage → packaging → distribution → customers.

1.3 Functional scope

·       Olive collection, purchase contracts and grower management

·       Reception, weighing (gross / tare / net) and reception quality control

·       Temporary olive storage in silos, palox, crates and storage zones

·       Full olive processing: washing, crushing, malaxing, extraction and separation

·       Extraction lines and mill machines (mill, crusher, malaxer, centrifuge, decanter, filter, packaging line)

·       Oil production batches with automatic extraction yield calculation

·       Stainless steel oil storage tanks with level, temperature and lot tracking

·       Filtration and clarification with before/after quality results

·       Multi-format packaging (glass bottle, can, carton, bag-in-box) with bottle lot and best-before date

·       Full food traceability from grower and grove down to the invoiced customer

·       Integrated oil laboratory (free acidity, peroxide index, K232, K270, organoleptic analysis)

·       Certification tracking (organic farming, PDO, ISO 22000, HACCP)

·       Integrated CMMS for preventive and corrective equipment maintenance

·       HSE and environmental management (pomace, vegetation water, wastewater, energy)

·       Industrial costing and cost per litre

·       Artificial intelligence: production forecasting, extraction optimisation, anomaly detection

·       Industrial dashboard and reporting exportable to PDF, Excel, Word and CSV

·       REST API for weighbridge import, IoT probes, laboratory systems and mobile applications

 

2. Architecture

2.1 Business engines

Engine	Responsibility
Olive Supply Management	Growers, groves, olive campaigns, purchase contracts, collection
Olive Processing Management	Reception, quality control, olive storage, extraction lines, machines, production
Oil Storage Management	Tanks, oil lots, filtration, packaging
Quality Management	Samples, laboratory analyses, certifications
Traceability Management	Full olive → oil → customer traceability
Cost Management	Extraction cost, production cost, cost per litre
Business Intelligence	KPIs, dashboard, industrial reporting
Artificial Intelligence	Forecasting, extraction optimisation, anomaly detection

2.2 Technical design

·       Module identifier (numero): 518200. Rights class: oliveoilmillmanager. Table prefix: llx_olv_.

·       A generic object engine drives every list and card page from a single registry (lib/oliveoilmillmanager_objects.php), which guarantees consistent behaviour, filtering, column selection and permissions across all 21 business objects.

·       All user-visible labels are prefixed (Olv...) so that no other installed Dolibarr module can override this module's wording through the shared translation table.

·       A schema self-heal routine runs on activation and adds any column missing from an existing installation, because Dolibarr only ever creates tables and never alters them.

·       Vocabularies (oil types, machine types, statuses) are stored as language-independent codes and translated at display time.

·       Font Awesome 5 icon names are used throughout, matching the version bundled with Dolibarr.

2.3 Dolibarr integration

Native area	Integration
Third parties	Growers, customers and suppliers linked to olv_producer and packaging sales
Products	Bottled oil references, packaging and materials linked to olv_packaging
Sales	Quotations, orders and invoices reachable from the traceability downstream view
Stock	Warehouses and movements alongside oil tank levels
Equipment / CMMS	Machines and maintenance interventions
Business Intelligence	KPI box and dashboard widgets
API	REST endpoints for external applications

 

3. Modules description

The module ships 21 business objects. Hub objects carry a KPI cockpit on their card and aggregate their children.

Object key	Table (llx_ prefix)	Menu entry	Hub	Fields
olvproducer	olv_producer	Producers	Yes	17
olvgrove	olv_grove	Groves	-	12
olvcampaign	olv_campaign	Campaigns	Yes	12
olvcontract	olv_contract	Contracts	-	13
olvreception	olv_reception	Receptions	Yes	18
olvolivecontrol	olv_olive_control	OliveControls	-	13
olvolivestorage	olv_olive_storage	OliveStorages	-	13
olvline	olv_line	ExtractionLines	Yes	12
olvmachine	olv_machine	Machines	-	15
olvproduction	olv_production	Productions	Yes	20
olvtank	olv_tank	Tanks	-	14
olvfiltration	olv_filtration	Filtrations	-	14
olvpackaging	olv_packaging	Packagings	-	14
olvsample	olv_sample	Samples	-	10
olvlabanalysis	olv_lab_analysis	LabAnalyses	-	19
olvcertification	olv_certification	Certifications	-	12
olvmaintenance	olv_maintenance	Maintenances	-	14
olvwaste	olv_waste	Wastes	-	11
olvenergy	olv_energy	Energies	-	10
olvcost	olv_cost	Costs	-	10
olvaiinsight	olv_ai_insight	AiInsights	-	12

3.1 Menu structure

Top menu “Olive Oil Mill Manager” with the following entries: dashboard, olive growers, groves, campaigns, purchase contracts, olive reception, olive quality control, olive storage, extraction lines, mill machines, oil production, oil tanks, filtration, packaging, laboratory samples, oil analyses, certifications, equipment maintenance, waste and by-products, energy consumption, industrial costs, traceability, AI insights, AI assistant, reports and setup.

 

4. Database structure

Every table carries the standard Dolibarr envelope: rowid, entity, status, date_creation, tms, fk_user_creat, fk_user_modif and import_key. The import_key column tags demonstration rows so they can be removed without ever touching real data.

Table	Approx. rows (demo dataset)
llx_olv_ai_insight	9
llx_olv_campaign	2
llx_olv_certification	4
llx_olv_contract	8
llx_olv_cost	7
llx_olv_energy	5
llx_olv_filtration	18
llx_olv_grove	16
llx_olv_lab_analysis	24
llx_olv_line	3
llx_olv_machine	8
llx_olv_maintenance	7
llx_olv_olive_control	26
llx_olv_olive_storage	26
llx_olv_packaging	8
llx_olv_producer	8
llx_olv_production	24
llx_olv_reception	26
llx_olv_sample	24
llx_olv_tank	6
llx_olv_waste	4

4.1 Key relationships

·       olv_grove.fk_producer → olv_producer (a grower owns several groves)

·       olv_reception.fk_producer / fk_campaign / fk_contract / fk_grove → upstream origin of a delivery

·       olv_olive_control.fk_reception → reception quality control

·       olv_olive_storage.fk_reception → temporary storage before milling

·       olv_production.fk_reception / fk_line / fk_campaign / fk_tank → the milling operation itself

·       olv_machine.fk_line → machines belonging to an extraction line

·       olv_filtration.fk_production / fk_tank → clarification of an oil batch

·       olv_packaging.fk_production / fk_product → bottling and the native Dolibarr product

·       olv_sample.fk_production and olv_lab_analysis.fk_sample / fk_production → laboratory chain

·       olv_maintenance.fk_machine → CMMS interventions

·       olv_waste / olv_energy / olv_cost .fk_campaign → environmental and cost tracking per campaign

 

5. REST API

Routes are exposed under /api/index.php/oliveoilmillmanager/. Authentication uses the standard Dolibarr DOLAPIKEY header; an invalid or missing key returns HTTP 401. Every route is additionally gated by the module right group matching the data it touches.

Method	Route	Purpose	Right
GET	producers	List olive growers	supply/read
GET	receptions	List olive receptions	supply/read
POST	receptions	Create a reception from a weighbridge; net weight and amount are derived	supply/write
GET	productions	List oil production batches	processing/read
GET	tanks	List oil storage tanks	storage/read
PUT	tanks/{id}/measure	Push an IoT level/temperature measure; fill rate is recomputed	storage/write
GET	analyses	List laboratory analyses	quality/read
POST	analyses	Push a laboratory result; classification is derived from the values	quality/write
GET	traceability/{lot}	Full history of an olive, oil or bottle lot	reporting/read
GET	kpi	Key industrial indicators of the mill	reporting/read

5.1 Example

curl -H "DOLAPIKEY: <key>" \
  -H "Content-Type: application/json" \
  -d '{"ref":"REC-2026-101","fk_producer":3,"gross_weight_kg":5400,
       "tare_weight_kg":420,"variety":"Aglandau"}' \
  -X POST https://<host>/api/index.php/oliveoilmillmanager/receptions

The reception above is stored with a derived net weight of 4980 kg. Pushing {"current_level_l":3111.5,"temperature":18.4} to tanks/{id}/measure updates the tank and recomputes its fill rate server-side.

 

6. Security

6.1 Permissions

The module declares 23 permissions across 7 read/write/delete groups plus reporting and administration. Read and write are granted by default so the module is usable immediately after activation; delete and admin are not.

Group	Covers	Rights
supply	Growers, groves, campaigns, contracts, receptions	read / write / delete
processing	Controls, olive storage, lines, machines, productions	read / write / delete
storage	Tanks, filtration, packaging	read / write / delete
quality	Samples, laboratory analyses, certifications	read / write / delete
maintenance	Equipment maintenance	read / write / delete
hse	Waste and energy	read / write / delete
cost	Industrial costs	read / write / delete
reporting	Reports, traceability and AI insights	read
admin	Module administration	admin

6.2 Application security

·       Every page checks the matching permission before rendering and calls accessforbidden() otherwise.

·       All forms carry a CSRF token validated by the Dolibarr core.

·       User input is escaped before reaching SQL; API sort fields are whitelisted against the real table columns so they can never be injected.

·       Multi-company aware: every query is filtered by entity.

·       Record history: each row stores its author, creation timestamp and last modification timestamp; Dolibarr's standard user logs and audit trail apply to the module.

·       The AI engine runs entirely on the instance's own data. No data is sent to any external service.

 

7. User guide

7.1 Installation

·       1. Copy the oliveoilmillmanager folder into the Dolibarr custom/ directory (or upload module_olive_oil_mill_manager-1.0.zip from Home > Setup > Modules).

·       2. Go to Home > Setup > Modules, find “Olive Oil Mill Manager” and enable it.

·       3. Tables, menus, permissions and the demonstration dataset are created automatically on activation.

·       4. Open the module setup page to adjust the business parameters.

7.2 Business parameters

Parameter	Default	Effect
Yield alert threshold	16 %	An extraction yield below this raises a dashboard alert and an AI anomaly
Maximum extra virgin acidity	0.8	Free acidity limit used to classify an oil as extra virgin
Tank fill alert threshold	90 %	A tank above this fill rate is flagged on the dashboard
Alert on laboratory non-conformity	Yes	Raises an alert when an analysis is non-conform

7.3 Demonstration data

The setup page provides two buttons. “Install demonstration data” creates a complete, coherent dataset: growers, groves, campaigns, contracts, receptions, quality controls, olive storage, extraction lines, machines, oil productions, tanks, filtrations, packagings, samples, laboratory analyses, certifications, maintenance interventions, waste, energy readings and costs, plus the matching native customers and bottled-oil products. “Remove demonstration data” deletes only those rows, including any records created underneath a demonstration parent, and never touches real data.

7.4 Daily workflow

·       Record the grower and their groves, then the purchase contract for the campaign.

·       On delivery, create the reception: weigh gross and tare, the net weight is derived. The reception can also be created automatically from a weighbridge through the API.

·       Run the olive quality control (maturity, estimated acidity, humidity, sanitary state) and accept, reject or quarantine the batch.

·       Store the olives briefly (palox, silo) then mill them on an extraction line: the production record captures the malaxing parameters and computes the yield automatically.

·       Send the oil to a tank, filter it, sample it and record the laboratory analysis. The oil classification follows from the analytical values.

·       Package the oil into bottles, cans, cartons or bag-in-box with a bottle lot and best-before date, linked to a native Dolibarr product for sale.

·       At any point, type any lot number into the Traceability page to rebuild the entire history.

·       Run the AI assistant to obtain the production forecast, recommended extraction settings and the list of yield, quality, energy and maintenance anomalies.

·       Use the Reports menu for campaign, extraction, yield, analyses, non-conformities, tank situation, available lots, lot history and global performance, exportable to PDF, Excel, Word and CSV.

7.5 Languages

The module ships complete translations in French, English, Spanish, Italian and German.