Excel / CSV Connector¶

Read and write maintenance data from Excel (.xlsx) and CSV files using YAML-based schema mapping. No Python code required.

Install¶

pip install "machina-ai[cmms-rest]"

Quick Start¶

from machina.connectors.cmms import ExcelCsvConnector

connector = ExcelCsvConnector(
    file_path="data/assets.xlsx",
    read_only=True,
)
await connector.connect()
assets = await connector.read_assets()

Configuration (YAML)¶

connectors:
  assets:
    type: excel_csv
    primary: true
    settings:
      file_path: "data/asset_registry.xlsx"
      read_only: true

  workorders:
    type: excel_csv
    settings:
      file_path: "data/workorders.xlsx"
      write_mode: append  # append | overwrite

Schema Mapping¶

The connector uses YAML field mappings to translate between your spreadsheet columns and Machina domain entities. See the GenericCmms YAML Mapping documentation for the full FieldSpec syntax — the Excel connector uses the same mapping engine.

Capabilities¶

Capability	Mode	Description
`READ_ASSETS`	Read	Read asset rows from Excel/CSV
`READ_WORK_ORDERS`	Read	Read work order rows
`CREATE_WORK_ORDER`	Write	Append a new work order row
`READ_SPARE_PARTS`	Read	Read spare part rows
`READ_FAILURE_MODES`	Read	Read an optional failure-modes sheet — declared only when a `failure_modes` sheet schema is configured

Multi-valued cells (the asset failure_modes linkage column and the failure-mode list fields detection_methods, typical_indicators, recommended_actions) use a semicolon-delimited string, e.g. "BEAR-WEAR-01;SEAL-LEAK-01". A sample catalog lives at examples/sample_data/failure_modes.csv.

File Watcher¶

The connector supports file watching — it detects changes to the source file and reloads data automatically. Enable in settings:

settings:
  file_path: "data/assets.xlsx"
  watch: true
  poll_interval: 30  # seconds

Sandbox Mode¶

When sandbox: true, write operations (CREATE_WORK_ORDER, etc.) are logged but the file is not modified. The trace entry records what would have been written.

Durable & Safe Writes¶

When write_mode is set, updates are persisted by rewriting the file from cache to a temp sibling and atomically replacing the target — both for .xlsx and .csv — so a crash mid-write cannot truncate your data (and CSV updates are no longer cache-only).

CSV/Excel formula-injection is neutralised on write. A cell value that starts with a spreadsheet formula trigger (=, +, -, @) is written with a leading apostrophe so a spreadsheet app treats it as text rather than executing it when the exported file is opened. The guard is reversed on read, so values round-trip unchanged (a literal '=value is preserved, not corrupted). This protects downstream users who open Machina-written files in Excel/LibreOffice from a classic CSV-injection vector.

Use Cases¶

Quick demos: Load sample data from Excel without setting up a CMMS
Small teams: Use Excel as a lightweight CMMS alternative
Data migration: Read from Excel, write to a REST CMMS via GenericCmms
Starter-kit templates: The odl-generator-from-text template uses Excel as its default substrate