Factorizer/Cluster ERP WikiCluster ERP Türkçe
Home / Business modules

Reference

Nesting integration and KPI

Reference for nesting/integration, the export and import of layouts with an external nesting tool, and nesting/kpi, the utilisation report.

This page lists the export format, the import format and its checks, and the KPI report of the nesting module. The code is in src/cluster_erp/modules/nesting/integration/ and src/cluster_erp/modules/nesting/kpi/. Jobs and parts are on jobs, parts, and remnants; the geometry helpers are on nesting engine.

Scope and source

  • Defined in: integration/schemas.py (NestingExportPart, NestingExportData, NestingImportPlacement, NestingImportRemnant, NestingImportPart, NestingImportResult), integration/services.py (NestingIntegrationService), kpi/schemas.py, kpi/services.py (NestingKpiService), kpi/routes.py.
  • Count: 6 integration schemas (classes in integration/schemas.py); 1 KPI route; 3 KPI granularities.

Export

POST /api/v1/nesting/nesting-jobs/{job_id}/export returns the job as JSON for an external tool (src/cluster_erp/modules/nesting/nesting_jobs/routes.py:251-264).

Field Meaning Source
job_id, job_code The job src/cluster_erp/modules/nesting/integration/schemas.py:19-21
material_grade, thickness_mm, surface_coating Material src/cluster_erp/modules/nesting/integration/schemas.py:22-24
sheet_length_mm, sheet_width_mm Sheet size src/cluster_erp/modules/nesting/integration/schemas.py:25-26
kerf_width_mm, part_gap_mm, edge_margin_mm, max_sheets, allow_mirror, allowed_rotations Process rules; rotations default to 0, 90, 180, and 270 src/cluster_erp/modules/nesting/integration/schemas.py:27-32, src/cluster_erp/modules/nesting/integration/services.py:153-158
parts One entry per live part: nesting_part_id, part_id, qty_requested, part_length_mm, part_width_mm, priority, geometry_polygon, ordered by priority src/cluster_erp/modules/nesting/integration/schemas.py:9-16, src/cluster_erp/modules/nesting/integration/services.py:121-143

Import

POST /api/v1/nesting/nesting-jobs/{job_id}/import-result takes the tool's result (src/cluster_erp/modules/nesting/nesting_jobs/routes.py:267-281).

Field Meaning Source
external_software Name of the tool, 1 to 100 characters src/cluster_erp/modules/nesting/integration/schemas.py:65
placements Each with nesting_part_id, x, y, rotation, mirrored, sheet_index src/cluster_erp/modules/nesting/integration/schemas.py:36-42, src/cluster_erp/modules/nesting/integration/schemas.py:66
remnants Leftover rectangles with x, y, width, height, sheet_index src/cluster_erp/modules/nesting/integration/schemas.py:45-50, src/cluster_erp/modules/nesting/integration/schemas.py:67
parts True outlines per part, in millimetres, one exterior ring src/cluster_erp/modules/nesting/integration/schemas.py:53-61, src/cluster_erp/modules/nesting/integration/schemas.py:68
sheets_used At least 1 src/cluster_erp/modules/nesting/integration/schemas.py:69
utilization_pct Optional yield from the tool, 0 to 100 src/cluster_erp/modules/nesting/integration/schemas.py:70-73

Import checks and results

The import locks the job row and accepts a result only for a job in queued or failed (src/cluster_erp/modules/nesting/integration/services.py:168-182). It then runs these checks; each failure answers NESTING_IMPORT_INVALID_PARTS:

  1. Every placement names a part of this job (src/cluster_erp/modules/nesting/integration/services.py:192-199).
  2. Every placement's sheet index is between 0 and sheets_used minus one (src/cluster_erp/modules/nesting/integration/services.py:201-212).
  3. Every returned outline names a part of this job; the outline is stored and the part is marked as parsed (src/cluster_erp/modules/nesting/integration/services.py:214-228).
  4. The placed part area does not exceed the sheet area times sheets_used (src/cluster_erp/modules/nesting/integration/services.py:284-301).
  5. When every placed part has a true outline, no part extends outside its sheet and no two parts on a sheet overlap (src/cluster_erp/modules/nesting/integration/services.py:48-106, src/cluster_erp/modules/nesting/integration/services.py:303-306).

Part area is the true polygon area when an outline exists, else length times width (src/cluster_erp/modules/nesting/integration/services.py:31-45). Utilisation is the tool's value when given; otherwise placed area divided by sheet area, in percent. Used and waste areas are derived from it (src/cluster_erp/modules/nesting/integration/services.py:308-319). The job becomes completed with result_source external, the layout and remnants are stored, and NestingCompleted is emitted (src/cluster_erp/modules/nesting/integration/services.py:321-361). Any other error during the update answers NESTING_IMPORT_FAILED (src/cluster_erp/modules/nesting/integration/services.py:341-348).

KPI report

GET /api/v1/nesting/nesting-jobs/kpi takes period_start, period_end, granularity (daily, weekly, or monthly, default monthly), and an optional material_grade (src/cluster_erp/modules/nesting/kpi/routes.py:16-31, src/cluster_erp/modules/nesting/kpi/schemas.py:8). It counts only live, completed jobs whose run completed inside the period (src/cluster_erp/modules/nesting/kpi/services.py:224-238).

Part of the answer Contents Source
summary jobs, sheets, material, used and waste area, scrap rate, utilisation src/cluster_erp/modules/nesting/kpi/schemas.py:11-18, src/cluster_erp/modules/nesting/kpi/services.py:71-111
material_breakdown the same per material grade and thickness src/cluster_erp/modules/nesting/kpi/schemas.py:21-29, src/cluster_erp/modules/nesting/kpi/services.py:113-165
trend jobs, utilisation, and scrap rate per day, week, or month src/cluster_erp/modules/nesting/kpi/schemas.py:32-36, src/cluster_erp/modules/nesting/kpi/services.py:167-222

Utilisation is area-weighted: total used area divided by total used plus waste area, in percent, to two places. The docstring states that this weights each job by the sheet area it consumed, unlike an average of percentages (src/cluster_erp/modules/nesting/kpi/services.py:24-33). The scrap rate is total waste divided by total used plus waste, in percent (src/cluster_erp/modules/nesting/kpi/services.py:93-98).

Constraints and validation

  • Import requires nesting_job.run; export and the KPI require nesting_job.read (src/cluster_erp/modules/nesting/nesting_jobs/routes.py:254, src/cluster_erp/modules/nesting/nesting_jobs/routes.py:271, src/cluster_erp/modules/nesting/kpi/routes.py:22).
  • An import resets all placement fields of every part before applying the new layout, so an import replaces the previous layout (src/cluster_erp/modules/nesting/integration/services.py:230-238).
  • Each part keeps the coordinates of its first placement; the full list is in the job's layout_placements (src/cluster_erp/modules/nesting/integration/services.py:243-270).

Terms introduced

Term Code identifier Definition Turkish term Source
nesting export NestingExportData The JSON description of a job sent to an external nesting tool. Yerleşim dışa aktarımı src/cluster_erp/modules/nesting/integration/schemas.py:19
nesting import NestingImportResult The layout an external tool returns: placements, remnants, outlines, and sheets used. Yerleşim sonucu içe aktarımı src/cluster_erp/modules/nesting/integration/schemas.py:64
scrap rate scrap_rate_pct Waste area as a percentage of used plus waste area. Fire oranı src/cluster_erp/modules/nesting/kpi/schemas.py:17

Verified against commit 92f8051 on 2026-11-13.

Verified against commit 92f8051 · 2026-11-13