Skip to content

admin-guide.md

Latest commit

 

History

History
561 lines (416 loc) · 22.2 KB

admin-guide.md

File metadata and controls

561 lines (416 loc) · 22.2 KB
Raw

Admin Guide

This guide covers installation, configuration, and administration of OpenMES.

Table of Contents

Installation

Deploying OpenMES in a plant for the first time? This chapter covers the software. The Implementation Runbook covers the whole procedure around it — infrastructure, configuration order, master data, pilot, go-live and handover.

Prerequisites

  • Docker 20.10+ and Docker Compose
  • Git

Steps

# 1. Clone the repository
git clone https://github.com/Mes-Open/OpenMes.git
cd OpenMes

# 2. Start containers
docker-compose up -d

# 3. Open browser
# Navigate to http://localhost

The web installer will guide you through three steps:

  1. Basic Configuration — site name, URL and the plant timezone
  2. Database Configuration — PostgreSQL connection details
  3. Admin Account — your admin username, email, and password

After completing the wizard, the system is ready.

Plant timezone. Pick the timezone of the plant, not of the server: every timestamp, report boundary and shift edge is expressed in it, so a mismatch makes a day's report cover different hours than the shift that was worked. The wizard stores it in the database, and that value takes precedence over APP_TIMEZONE — on Docker the environment variable comes from docker-compose.yml and cannot be changed from inside the application.

Production Deployment

For production use, see the deployment notes in the main README. Ensure:

  • APP_DEBUG=false in your .env
  • HTTPS is configured (use a reverse proxy like Caddy or Nginx)
  • The .env file is secured and not committed to version control

First Steps After Installation

After installing, complete this checklist:

  1. Create production lines — at least one line is required before operators can work
  2. Add users — create accounts for supervisors and operators
  3. Assign users to lines — operators must be assigned to see their queue
  4. Create product types — categories for your products
  5. Create process templates — step-by-step workflows for each product
  6. Import or create work orders — orders to be produced
  7. Load sample data (optional) — Settings → Sample Data loads realistic test data

User Management

Go to Admin → Users to manage accounts.

Roles

Role Access
Admin Full system access: settings, all data, user management
Supervisor Accept/reject orders, manage issues, view reports
Operator View assigned line queue, execute steps, report issues

Creating a User

  1. Click New User
  2. Fill in username, email, password, and select a role
  3. For Operator/Supervisor roles, assign them to one or more lines
  4. Click Save

Assigning Lines

Operators see only the lines they are assigned to. Assign lines:

  1. Open the user's profile
  2. In the Lines section, select lines from the list
  3. Save changes

Production Structure

Factories and Divisions

Use Factories and Divisions to organise your physical locations:

  • Factory → Division → Line → Workstation

Navigate to Admin → Structure → Factories and Admin → Structure → Divisions.

Lines

Lines are the core production units. Each work order is assigned to a line.

  1. Go to Admin → Production → Lines
  2. Click New Line
  3. Enter name, code, and optionally assign a division
  4. Set Active to true for the line to appear in operator selection
  5. Save

Workstations

Workstations are individual machines or work positions within a line.

  1. Go to Admin → Structure → Workstations (or from within a Line's detail page)
  2. Assign a workstation type, line, and optionally a division

Product Configuration

Product Types

Product types are categories that group similar products.

  1. Go to Admin → Production → Product Types
  2. Create types (e.g. "Wooden Chair", "Metal Frame", "Assembly Kit")

Process Templates

Process templates define the step-by-step production workflow for a product.

  1. Go to Admin → Production → Process Templates
  2. Click New Template
  3. Add steps with:
    • Name — e.g. "Cut", "Drill", "Paint", "Assembly", "Quality Check"
    • Order — sequence number
    • Required role — optional, restrict step to a specific role
  4. Assign the template to one or more product types

When creating work orders, selecting a product type automatically selects the associated process template.

Work Orders

Creating Orders Manually

  1. Go to Admin → Work Orders → New
  2. Fill in:
    • Order number (unique)
    • Product name
    • Quantity
    • Line (production line)
    • Product type and Process template
    • Due date and Priority (1–5)
    • Week/month/year numbers (if production period is configured)
  3. Save — the order is created with status Pending

A supervisor must accept the order before operators can work on it.

Importing data (Admin → Import)

One importer loads master data and orders from spreadsheets — the same screen for every entity, in the style of a shop-system import page:

  1. Go to Admin → Import (supervisors: Supervisor → Orders → Import, work orders only). The page sits on its own import tab in Settings → Access; after an upgrade only Admin holds it.
  2. Pick what to import: product types, materials, work orders or bills of materials. The right-hand panel lists the available fields for that entity (required ones starred) and offers a sample CSV per entity.
  3. Upload a .csv, .txt, .xls or .xlsx file (max 32 MB). For CSV you can pin the field separator (auto-detected by default: ;, , or tab) and the encoding (UTF-8, ISO-8859-1, Windows-1250 for older Polish exports).
  4. Set the run options for the entity — the strategy (insert or update / insert only / update only / error on duplicates), and per entity: the external system and category filter (product types, materials), a default material type, a target line and planning period (work orders), replace vs merge (recipes).
  5. Map columns: each file column is assigned to a field. Columns are auto-detected from common English and Polish headers; work orders also accept custom:<key> targets that are kept as extra data on the order. Mappings can be saved as profiles and reused.
  6. Run: the import is queued and processed in the background. The run page shows a live progress bar and, when done, per-row errors with the file line, the field and the reason — downloadable as CSV. The Recent imports list on the import page updates live as well.

Rows are processed independently: one bad reference never fails the whole file. The older addresses (/admin/csv-import, /admin/materials-import) redirect here.

Sample files for every entity, matched to the demo data, live in docs/import-samples/.

HR Management

OpenMES includes basic HR tracking linked to production:

  • Workers — Shop floor workers (separate from system users)
  • Crews — Work groups assigned to shifts
  • Skills — Competency tracking
  • Wage Groups — Pay classification (for reporting)

Navigate to Admin → HR to manage these.

System Settings

Go to Settings → System (Admin only).

Production Period

Controls whether work orders must specify a week or month number:

Value Behavior
none No period required
weekly Week number required on all orders
monthly Month number required on all orders

Overproduction

allow_overproduction: if enabled, operators can produce more units than planned on a work order. If disabled, the batch completion form enforces the planned quantity as a ceiling.

Sequential Steps

force_sequential_steps: if enabled, operators must complete steps in defined order. If disabled, steps can be completed in any order.

Configuration and Scenario Files (Settings → System → Data)

Import on the Data tab (Admin only) takes a JSON file with a plant's configuration, an example production history, or both. The file is applied in one transaction: if anything in its scenario fails, nothing from the file is saved and the message names the entry that failed. Export writes the configuration in the same shape.

A clean start for testing a file is Reset system on the same tab, then the configuration file, then the production flow mode the scenario needs (Settings → Production), then the scenario file.

Configuration. One array per table (warehouses, lines, workstations, material_types, materials, product_types, line_product_type, process_templates, template_steps, bom_items, lot_sequences, label_templates, scrap_reasons, shifts, …) plus system_settings as key: value.

  • A row's id is the file's own reference. Foreign keys point at those ids, for example a workstation's line_id or a BOM item's template_step_id. They are remapped to the ids the rows get in this database, so the file never depends on the database's numbering.
  • Rows are matched on their natural key: a code, a name, or a combination such as a routing's product and name, or a step's routing and number. Importing the same file again updates rows instead of duplicating them.
  • Tables are applied in dependency order, whatever order the file uses. Unknown columns are ignored.
  • Settings take the settings form's own keys. Infrastructure and security keys are never read from a file, and neither is the production flow mode: switch it under Settings → Production, where its checks run. A timezone is taken only when it is a valid zone.
{
  "system_settings": { "language": "pl", "app_timezone": "Europe/Warsaw" },
  "lines": [{ "id": 1, "code": "L1", "name": "Line 1" }],
  "workstations": [{ "id": 1, "code": "ST-A", "name": "Assembly", "line_id": 1,
                     "operator_screens": ["queue", "workstation", "unit_labels"] }],
  "product_types": [{ "id": 1, "code": "PRD-A", "name": "Product A" }],
  "process_templates": [{ "id": 1, "product_type_id": 1, "name": "Routing A", "is_active": true }],
  "template_steps": [{ "id": 1, "process_template_id": 1, "step_number": 1,
                       "name": "Assemble", "workstation_id": 1 }]
}

Production scenario. A scenario section replays shop-floor work on top of the configuration. Each event goes through the same service the operator screens use, so statuses, quantities, consumption and unit history come out as the line would produce them. The clock is set to each event's time, so durations and waiting times look like a real shift.

  • requires.production_flow_mode makes the import refuse to run under the other flow mode.
  • users creates accounts: username, name, role, lines, workstation and password; "account_type": "workstation" makes a bench's own terminal login, locked to its workstation. An existing account is used as it is and never changed.
  • material_lots adds lots: material is the code, plus lot_number, quantity and received.
  • events is the timeline. Each event has do and at. The acting user is by, and the importing admin acts when by is left out. Configuration is referenced by code.

Event times are relative to the import and must be in time order:

at Meaning
-2d 07:30 two days before the import, at 07:30
-3h20m 3 h 20 min before the import
+4m 4 minutes after the previous event
(omitted) 10 seconds after the previous event

Events happen in the past. Only a schedule window and a due date may lie ahead, for example +1d 06:00.

do Fields Does what the screen does
work_order order_no, product, line, quantity, due, customer_order_no, description creates the order
schedule order, start, end, line, shift, force places it on the planner; an overlap on the line is refused unless force
batch order, quantity, lot (auto draws one), workstation issues a batch
step_start / step_log / step_complete order, batch (default 1), step; good, scrap, note for a log starts, logs and closes a step
unit_start order, ref, psn (auto draws one), workstation starts a unit on its PSN
subassembly order, material, sn, ref, workstation registers a sub-assembly by its own serial where it is made
unit_serial unit, sn (auto), workstation binds the SN label to the unit
component unit, identifier, material, step, workstation scans a component into the unit
test unit, workstation, result, steps (name, value, unit, low, high, verdict), duration_s files a tester's run; the failed-test policy applies
block / unblock / scrap unit, reason (an error code for block), note, workstation holds, releases or scraps a unit
pack unit, workstation, weight_g, pallet scans the unit at the packing bench; a carton opens by itself
carton_close order, pallet, workstation closes the open carton and puts it on the pallet
pallet_open / pallet_close / pallet_ship order, ref, pallet, workstation creates, closes or ships a pallet

unit and pallet take the ref given when the unit or pallet was created, or its real number.

{
  "scenario": {
    "requires": { "production_flow_mode": "transfer" },
    "users": [{ "username": "op-a", "name": "Operator A", "role": "Operator", "lines": ["L1"], "password": "…" }],
    "events": [
      { "at": "-1d 07:00", "do": "work_order", "order_no": "WO-1", "product": "PRD-A", "line": "L1", "quantity": 2 },
      { "at": "+1m", "do": "batch", "order": "WO-1", "quantity": 2 },
      { "at": "+2m", "do": "step_start", "order": "WO-1", "step": 1, "by": "op-a" },
      { "at": "+1m", "do": "unit_start", "order": "WO-1", "ref": "u1", "workstation": "ST-A", "by": "op-a" },
      { "at": "+5m", "do": "step_log", "order": "WO-1", "step": 1, "good": 1, "by": "op-a" },
      { "do": "schedule", "order": "WO-1", "start": "-1d 07:00", "end": "-1d 15:00" }
    ]
  }
}

Warehouses

Warehousing is an optional module — enable Warehouses under Settings → System → Modules (see Modules). With it off, the pages below are hidden and nothing in this section applies.

Rolling this out on an existing production install? Follow the Warehouses & ERP Sync rollout runbook — it covers the deployment order, loading opening stock, the acceptance test and the rollback path.

Setting Up Warehouses

  1. Go to Admin → Production → Warehouses → All Warehouses
  2. Click + New Warehouse and give it a code, a name and a kind:
    • Raw materials — materials are issued out of it
    • Finished goods — product is received into it
    • Mixed — both
  3. Optionally set an ERP code — the identifier of the same warehouse in your ERP, so stock syncs and documents can be matched up on both sides
  4. Tick Default for its kind on the warehouse that should be used whenever an import or an automatically generated document names no warehouse

Set one default for raw materials and one for finished goods before you rely on automatic document generation — without them, nothing is generated.

Admin → Production → Warehouses → Stock On Hand shows live balances. A row with an empty Lot column (shown as total) is the item's total in that warehouse; rows carrying a lot are its breakdown — don't add the two together.

A warehouse that still holds stock or carries documents cannot be deleted; deactivate it instead.

Stock Documents

Admin → Production → Warehouses → Stock Documents lists the warehouse paperwork:

Type Meaning
Material release Raw material leaving a warehouse for production
Material receipt Raw material arriving (ERP receipt, return from the floor)
Product receipt Finished product arriving when an order is concluded
Product release Finished product leaving (shipment, correction)

Every document is a draft until posted, and posting is what moves stock — it updates the warehouse balance, the material's stock quantity and the stock-movement ledger. Cancelling a posted document reverses all of it, so a mistake is undone without editing balances by hand. A posted document must be cancelled before it can be deleted.

Completing a work order creates its paperwork automatically (drafts): a material release for what it consumed — from the lots the shop floor actually booked, or from the order's BOM × produced quantity when it didn't — and a product receipt for what it produced. Review and post them from this page. To turn generation off, set WAREHOUSE_AUTO_DOCUMENTS=false in .env.

Create a document by hand with + New Document: pick the type, the warehouse, and add one line per item. The item picker follows the type — material documents list materials, product documents list products.

Syncing Stock With an ERP

With both the Warehouses and ERP integration modules enabled, an ERP can keep OpenMES in step over the REST API:

  • push balances — a quantity snapshot per warehouse and item; the ERP owns the warehouse, so a synced quantity replaces the OpenMES figure and re-running the sync converges instead of drifting
  • push lots — lot numbers with their available quantities
  • pull documents — the backlog of posted releases and receipts the ERP has not booked yet, then acknowledge each one with the ERP's own document number so it leaves the backlog

Create a key under Admin → API keys with the erp:stock:read / erp:stock:write scopes (and erp:masterdata:write for products, materials, lots and recipes). Endpoints, payloads and scopes: API documentation → ERP Integration API.

Modules

Modules are optional extensions that add functionality to OpenMES without modifying core code.

Enabling and Disabling Modules

  1. Go to Admin → Modules → Installed
  2. Each module shows its status (enabled/disabled)
  3. Click Enable or Disable as needed
  4. A server restart may be required for full effect

Installing a Module from ZIP

  1. Go to Admin → Modules → Install
  2. Upload a .zip file containing the module
  3. The module is extracted and appears in the installed list
  4. Enable it to activate

Module ZIP structure:

MyModule.zip
└── MyModule/
    ├── module.json        (required: name, display_name, version)
    ├── Providers/
    │   └── MyModuleServiceProvider.php
    ├── Controllers/
    ├── Models/
    ├── views/
    └── migrations/

See HOOKS.md and development.md for how to build modules.

API Tokens

OpenMES provides a token-based REST API for ERP integration, custom dashboards, and automation.

  1. Go to Settings → API Tokens
  2. Click Create Token
  3. Enter a name (e.g. "ERP Integration")
  4. Copy and store the token immediately — it is not shown again
  5. Use the token in the Authorization: Bearer <token> header

See API Documentation for full endpoint reference.

To revoke a token, click the Revoke button next to it in the list.

Shifts

Shifts define working hours for automatic shift-based reporting and module features.

  1. Go to Admin → Schedule → Shifts
  2. Create shifts with start time, end time, and name (e.g. "Day Shift", "Night Shift")
  3. Shifts are used by modules (e.g. Packaging) and reports

Audit Logs

Every data-changing action in OpenMES is logged with the user, timestamp, entity type, and old/new values.

  1. Go to Admin → Audit Logs
  2. Filter by date, user, or entity type
  3. Export logs as CSV for compliance reporting

Audit logs are immutable — enforced at the database level. They cannot be edited or deleted through the application.

Maintenance

The Maintenance section tracks equipment and tooling:

  • Maintenance Events — scheduled and unscheduled maintenance with costs and duration
  • Tools — inventory of tools with last-service dates
  • Cost Sources — categories for maintenance cost classification

Navigate to Admin → Maintenance.

Updates

OpenMES can check for and apply updates:

  1. Go to Admin → System → Updates
  2. Click Check for Updates
  3. If an update is available, click Apply Update

The update process pulls the latest release ZIP and applies it. A changelog is shown before applying.

Backup first. Always back up your database and .env before applying updates in production.

# Manual backup
docker compose exec postgres pg_dump -U openmmes_user openmmes > backup_$(date +%Y%m%d).sql