Purpose
This tutorial explains how to use Label Server and hotfolders to convert incoming orders or job files into validated production jobs without manually opening each label template.
1. Choose the automation route
| Route | Best for | Typical input |
|---|---|---|
| Hotfolder | Simple production cells and shared network folders. | Job JSON, CSV, PDF, image, or template package. |
| CSV Watch | E-commerce batches exported from marketplaces or back-office tools. | CSV rows mapped to a label template. |
| REST API | ERP, WMS, web shop, or custom production system integration. | Authenticated HTTP job requests. |
| Webhook | Event-driven order intake from external platforms. | Order paid, order validated, shipment ready. |
| CLI | Scripts, scheduled tasks, and local automation. | Command-line job execution. |
2. Prepare the workspace
Create one workspace per production environment. Keep it outside the application bundle so it survives updates.
incoming/receives new jobs.processing/contains locked jobs being handled.done/stores successful jobs and output logs.error/stores rejected jobs with failure reason.templates/contains approved label templates.logs/contains production audit logs.
3. Job JSON structure
Use a stable job format so every system sends the same production intent.
{
"template": "shipping-label.lsc",
"quantity": 250,
"records": [{"sku": "RB3L-ROLL-50", "lot": "A42"}],
"printerRoute": "oki-pro1050-white",
"outputMode": "print",
"media": {"id": "pp-gloss-102mm", "roll": "R-2026-07-07"},
"preflight": {"proofRequired": true, "barcodeValidation": true},
"operator": "auto-hotfolder"
}4. Hotfolder behavior
Detect
The watcher detects a complete file in incoming/. Use atomic file copy or a temporary extension while uploading.
Validate
Template, data fields, quantity, printer route, media, barcode rules, and license status are checked.
Queue
Jobs can be held for proof approval, released to production, or blocked by preflight errors.
Archive
Completed jobs go to done/. Failed jobs go to error/ with a readable log.
5. Safety gates before printing
| Gate | Why it matters |
|---|---|
| Template approval | Prevents printing outdated artwork. |
| Data validation | Stops missing SKU, lot, expiry, barcode, or customer fields. |
| Proof approval | Blocks production until the BAT/proof is approved when required. |
| Inventory check | Confirms enough label stock, ribbon, roll, or sheet media exists. |
| Printer route | Ensures the job goes to the correct OKI, Epson ColorWorks, CUPS, RIP, or driver backend. |
| Trial watermark | Missing or invalid license must mark all print and export output according to product policy. |
6. Troubleshooting
| Symptom | Check |
|---|---|
| File not processed | Folder path, permissions, file extension, incomplete upload, server status. |
| Missing template | Template name and templates/ workspace path. |
| Wrong printer | printerRoute, OS default printer, CUPS queue, Windows printer name. |
| Invalid data | Required fields, JSON syntax, CSV delimiter, encoding, decimal separators. |
| Job blocked | Preflight results, proof approval, inventory status, license status. |
| No output | Driver, RIP route, backend logs, OS print queue, printer offline state. |
7. Final workflow checklist
Recommended flow: create workspace → configure route → place test job in incoming → validate queue entry → approve proof → print sample → verify archive done/error → connect ERP or e-commerce source.