Upgrade Notes

This section describes required updates for integrations and initial boot behaviors for each version. The upgrade procedure (rerunning the installation one-liner) is located in Upgrade. The newest version is listed first.

2026.11 — Pre-upgrade Tasks and Renamed Fields

Support Range

The support range covers the three most recent versions from 2026.11 onwards. Upgrades are not supported from versions 2026.10 or earlier; please perform a clean installation (attempting an upgrade will result in failure and an automatic rollback to the original version). See Upgrade. The name changes and integration updates listed below also apply to clean installations.

Prepare in the following order. Cassandra upgrades are irreversible, and renamed fields have no backward compatibility — old paths, columns, and tool names disappear at the moment of upgrade; therefore, integrations must be upgraded together with the server. Frontline apps must also be upgraded to the same version. Changes to work order quantities and names are detailed in the Next Section.

1. Backup — Cassandra r4 is Irreversible

The Cassandra version for this release is Aster TSDB v6.0.0-r4.

Nodes booted with r4 cannot be rolled back to r3 or below

The snapshot format of the cluster metadata has changed, making it unreadable by older versions. To ensure a rollback path, backups must be performed before upgrading.

Full PostgreSQL backup — ./backup.sh --postgres full
Full Aster TSDB backup — ./backup.sh --cassandra full(Backup and Recovery)
Copy system_cluster_metadata of the Cassandra data directory on each node.
Proceed with the new version upgrade.

2. Migration V121~ — Initial Boot May Take Longer

During the first boot, Flyway applies V121~V152 in a single batch. This includes major structural changes: alarm table cleanup (V121~~V124), five-layer equipment tree (V137~~V139), record table keys and maintenance names (V140), and foreign keys (V127~V133). Since V123 modifies all rows in mm_alarm, the time required increases proportionally to the number of alarm rows. The server will be unresponsive during this process, and health checks may trigger unhealthy — do not restart the container; wait for Flyway migration completed. in the logs.

If data does not meet the required conditions, the migration will halt and the server will not start. Changes in the halted step are rolled back, while previous steps remain. Correct the data according to the message following Platform version update failed in the logs and restart the server to resume from that step. Use the following SQL to preview data in the DB before upgrading.

-- V121: 0 행이어야 합니다 — 숨겨진 채 켜져 있는 알람
SELECT alarm_seq FROM pp.mm_alarm WHERE shelved AND is_on;

-- V121: 0 이어야 합니다 — 숨겨진 알람에 확인 · 라벨이 붙은 행
SELECT count(*) FROM pp.mm_alarm
 WHERE shelved AND (is_read IS TRUE OR read_user_id IS NOT NULL OR disposition IS NOT NULL
       OR cause_note IS NOT NULL OR labeled_by IS NOT NULL OR labeled_at IS NOT NULL
       OR failure_record_id IS NOT NULL);

-- V128: 0 이어야 합니다 — 고장 기록을 가리키지 못하는 알람 연결
SELECT count(*) FROM pp.mm_alarm a
 WHERE a.failure_record_id IS NOT NULL
   AND (a.failure_record_id !~ '^[0-9]{1,18}$'
        OR NOT EXISTS (SELECT 1 FROM pp.mm_ram_failure f WHERE f.failure_id = a.failure_record_id::bigint));

-- V137: 1 행이어야 합니다 — 설치당 기업은 하나
SELECT enterprise_id FROM pp.mm_enterprise;

3. Renamed Fields — No Backward Compatibility

Old names are neither accepted nor returned. Old V5 paths will return 404.

Maintenance «Record» is now Maintenance «Order».

Location	Old	New
V5 Path	`/api/v5/maintenance-records…`	`/api/v5/maintenance-orders…`
V5 Path	`/api/v5/asset/{asset_id}/maintenance-records`	`/api/v5/asset/{asset_id}/maintenance-orders`
MCP Tool	`list_maintenance_records`	`list_maintenance_orders`
Column · Query	`record_id`	`maintenance_order_id` — Number → String
Column · Query	`kind` · `status` · `cancel_reason`	`maintenance_kind_code` · `status_code` · `cancel_reason_code`
Column	`failure_id`	`failure_record_seq`
Column	`plan_id` · `plan_name`	`maintenance_plan_id`(Number → String) · `maintenance_plan_name`
Column · Query	`failure_mode` · `failure_mechanism` · `failure_cause` · `maintainable_item`	Ends with `_code`. Display names `*_name` and `cause_code` remain same
Column	`checklist_results[].attachment_id`	`checklist_results[].maintenance_attachment_seq`
Attachment Response	`attachment_id` · `record_id`	`maintenance_attachment_seq` · `maintenance_order_id`
List `sort` Value	`status` · `kind`	`status_code` · `maintenance_kind_code`
Maintenance Schedule Calendar	`record_id` · `record_status` · `open_record_id` · `open_status` · `record_ids`	`maintenance_order_id` · `maintenance_order_status_code` · `open_maintenance_order_id` · `open_status_code` · `maintenance_order_ids`
DB Table	`mm_maintenance_record` · `mm_ram_failure`	`mm_maintenance_order` · `mm_failure_record`

Do not read or compare maintenance_order_id · maintenance_plan_id as numbers. Old rows are strings maintaining the original number ("12"), while new rows follow the MAINTENANCE_ORDER_000013 format.

CMMS Webhook Keys(PP_MAINTENANCE_WEBHOOK_URL) — Update the receiving end first.

Old Key	New Key	Value
`record_id`	`maintenance_order_id`	String
`kind`	`maintenance_kind_code`	Same
`status`	`status_code`	Same
`failure_mode`	`failure_mode_code`	Same
`cancel_reason`	`cancel_reason_code`	Same
`plan_id`	`maintenance_plan_id`	String
`checklist_results[].attachment_id`	`checklist_results[].maintenance_attachment_seq`	Same

text · event · asset_id · asset_name · description · requested_by · accepted_by · assignee_employee_id · external_system · external_id · owner · anomaly_found · plan_due_at · at · version remain unchanged — CMMS Webhook.

Other Record Keys and ID Columns.

Location	Old	New
`/ram/failures…`	`failure_id` · `asset_class` · `equipment_class` · `code_status`	`failure_record_seq` · `asset_class_code` · `equipment_class_code` · `raw_code_status_code`
`/ram/failures…`	`failure_mode` · `mechanism` · `iso_cause` · `maintainable_item`	`failure_mode_code` · `failure_mechanism_code` · `failure_cause_code` · `maintainable_item_code`
Failure · Maintenance Code Mapping	`map_id`(Number)	`fault_code_map_id` · `maintenance_code_map_id`(String)
`/defects…`	`defect_id`	`defect_record_seq`
`/order/{id}/notes` · `/progress`	`note_id` · `progress_id`	`order_note_seq` · `order_progress_seq`
`/alarm/config/{id}/revisions`	`revision_id`	`alarm_config_revision_seq`
Work Schedule Interval	`generation_id`	`asset_plan_generation_seq`
Alarm `label`	`failure_id`	`failure_record_seq`

Equipment · Site.

Old	New	Notes
`table_type`	`asset_class_code`	UI label is «Equipment Category». Code column in table `mm_asset_class` is `code`
Site `status`	`operational_status_code`	`ACTIVE` → `IN_OPERATION`, `INACTIVE` → `OUT_OF_SERVICE`, `CLOSED` → `DECOMMISSIONED`. Common columns for all levels
Tree: Zone · Line · Equipment only	Enterprise → Site → Zone → Line → Equipment	`E` · `S` are newly added to `asset_type`. Filter these out when counting equipment

ID Format. Newly created IDs consist of the domain full name + 6-digit number. Existing IDs remain valid and unchanged. Do not determine the level or type by the ID prefix; read asset_type instead.

Domain	Old Format (Still Valid)	New Format
Zone · Line · Equipment	`ASSET_…`	`AREA_000001` · `LINE_000001` · `EQUIPMENT_000001`
Work Order	`ORD_…`	`ORDER_000001`
Calendar · Shift Exception	`CAL_…` · `OV_…`	`CALENDAR_000001` · `SHIFT_OVERRIDE_000001`
Equipment Relation · Process Segment	`REL_…` · `SEG_…`	`ASSET_RELATION_000001` · `PROCESS_SEGMENT_000001`
Command Area · Equipment Command	`CMDAREA_…` · `CMD_…`	`COMMAND_AREA_000001` · `ASSET_COMMAND_000001`
Image	`IMG_…`	`IMAGE_000001`
Employee	`EMP_…`	`EMPLOYEE_…`
Alarm Configuration	`ALARM_CONFIG_00375` · `ALARM_CONFIG_<태그 ID>`	`ALARM_CONFIG_000376`

Numbers may have gaps and will increase in length if they exceed 999,999. For details, see Domain ID Rules.

Alarm Configuration.

Entering a manually created ID into POST /alarm/config results in a 422 alarm.invalid.alarm_config_id. New IDs are received via GET /alarm/config/new-id. Old format IDs can only be modified.
Band alarm configurations are limited to one per tag. A second entry results in a 409. EQL alarm configurations have no limit on quantity.
Do not create band alarm configuration IDs as ALARM_CONFIG_<태그 ID> to search for them. New configurations do not exist by that name. Search for items where alarm_config_priority is BAND in GET /alarm/config/list/by-tag?tag_id=….

Statement Mandatory Columns

Mandatory output columns are checked by type during saving. Missing columns result in a 422 asset_statement.eql.missing_columns rejection, specifying the missing fields.

Type	Mandatory Columns
`EVENT`	`timestamp` · `plugin` · `name` · `color` · `from_timestamp` · `to_timestamp` · `value`
`CONTEXT` · `AGGREGATION` · `COMMAND`	`timestamp` · `plugin` · `key` · `value`

Previously saved statements will not be deleted or stopped by the upgrade and will be deployed as-is during boot. However, statements missing mandatory columns—which did not record results previously—will continue to fail per event, triggering diagnosis diagnostic.asset.statement_failing. Such statements will be caught by the check above during modification and saving, so columns must be filled to save. Locate and fix these codes in the diagnosis screen after upgrading.

4. Diagnosis — CEP Dead Letter Retention: 24 Hours / 256 MiB

A limit has been set for the dead letter (PP:CEP-DEAD-LETTER) that stores events CEP failed to process. Events are removed starting from the oldest once 24 hours have passed or the total exceeds 256 MiB. Only events that fail to be processed after three delivery attempts are entered. Use this to investigate failure events — Data Retention.

5. CEP — No Esper Backend or Per-Statement CPU Metrics

The cep.backend value is either aster or flink, defaulting to aster if not set. The standard deployment template is cep.backend=aster, so installations not manually modified require no action.

CEP will not start if set to cep.backend=esper

Booting stops when values are provided with typos. Before upgrading, change the line in plantpulse-cep.properties to aster or delete it.

For installations using Esper, use GET /api/v1/eql/portability before upgrading to identify statements that Aster CEP cannot receive. These statements are not deleted but remain as REJECTED — Limits and Rejection Tokens.
GET /api/v1/eql/{name}/metrics has been removed. Per-statement CPU and wall-clock time metrics are no longer available via Gauge, REST, Console panel, or storage. For statement metrics, use the match rate and output rate of GET /api/v1/eql/metrics/snapshot. No values will appear in the EQL_CPU_TIME panel of the PlantPulse Dashboard.
The following configurations no longer have reading code: cep.ha.* · cep.monitor.statement_metrics_enabled · cep.monitor.cpu_estimate_max_error · cep.performance.cpu_warn_threshold_ns · cep.performance.wall_warn_threshold_ns · cep.storage.max_inflight_writes. Rule state preservation is handled by cep.aster.state.* — Properties Reference.

6. Post-Upgrade

Enter PP_UI_CONSOLE_URL in the settings screen. If left empty, alarm emails will lack links and QR Labels cannot be created. If using the frontline app, also enter PP_UI_FRONTLINE_URL.
QR public pages start as disabled for all sites.
Fixed a defect where the MAIL_SMTP_* value in the settings screen was not applied to sending, and a defect where STARTTLS failed with «No appropriate protocol». Emails may actually begin to be sent; verify settings — Mail Settings.

Plugins applied on a 2026.11 build from before 2026-11-05 — RAM_FAILURE_CODE_TAG and OEE_PRODUCT_BAD_COUNT_CODED keep their old statements, which listen to tags that do not exist (<tag>_CODE, <tag>_CAUSE). Applying the plugin again changes nothing, because the dialog shows «already exists (skipped)». Delete those statements (DELETE /api/v5/asset/{asset_id}/statement/{statement_name}), then apply the plugin again and choose the code tag and the defect cause tag. Leave other statements alone. Failures that occurred before you reapply stay without a code. Installations where the code tag really exists as <failure tag ID>_CODE and everything was working need no action.

2026.11 — Work Order Quantities and Names to ISA-95 / B2MML

Work order quantities have changed from «single number» to Value + Unit Object (ISA-95 / B2MML QuantityValueType). Column names have been updated to ISO 22400 terminology, and defects are now split into Scrap and Rework. In the same version, column names for work orders, calendars, customers, and products have changed to ISA-95 / B2MML names (title → order_name, fix_start_timestamp → planned_start_timestamp …, see Name Changes below). There are no compatible columns, compatible paths, or aliases — integrations reading or sending old names must be updated along with the upgrade.

Reference: V5 API 5.0 · Quantity Contract 2026-10-30 · Name Wave 2026-10-31 · server-web 974891b4(Quantity wave starts from 30b7d9af) · Flyway V99·V100·V103 · core migration V12~~V16·V21~~V23 · Event Schema plantpulse.order.*·plantpulse.calendar.* major 2, plantpulse.kpi.oee.finalized major 1.

Changes Overview

Area	Changes	Details
V5 Quantity Columns	`target_units`+`unit` → `planned_quantity`, `total_good_count` → `good_quantity`, `total_bad_count` → `scrap_quantity`, `total_production_count` → `produced_quantity` etc. Value is `{quantity_string, data_type, unit_of_measure}` object	Order Service — Quantity
Scrap · Rework	`scrap_quantity` is now Scrap only(ISO 22400 SQ); rework is now the new column `rework_quantity`(RQ). Old `total_bad_count` was the sum of defects — if the sum is needed, add the two. UI shows «Scrap» for scrap-only fields and «Defect» for the sum	Order Service — Scrap and Rework
Units	13 allowed UN/ECE Rec 20 units (`EA`·`H87`·`C62`·`BX`·`SET`·`KGM`·`GRM`·`TNE`·`LTR`·`MLT`·`MTQ`·`MTR`·`MTK`). Actuals are received only in work order units (no conversion). Rejections: 422 `E1002` + `reason`(`quantity.unit_mismatch`·`quantity.not_integer` …)	Order Service — Request Rules and Rejections
Product Base Unit	Product `unit_of_measure` becomes the base unit for new work orders. Old values are moved to codes (`BOX` → `BX`, `KG` → `KGM`, `PCS`·`개` → `EA` …); unknown values become «Unitless» (new work orders for that product use `EA`)	Production Management — Quantities and Units
Priority	`priority` becomes B2MML Priority integer (1 Urgent·2 High·3 Normal·4 Low; lower is higher). Old `URGENT`·`HIGH`·`NORMAL`·`LOW` are mapped to 1~4
Period KPI	If single unit: Number + `unit_of_measure`; if mixed: do not sum, use `quantities_by_unit`	Same location
EMS Value per Unit	Denominator unit `unit_of_measure` added next to `energy_per_unit_kwh`·`co2_per_unit_kg`	Same location
Names (Work Order·Calendar·Customer·Product)	`title` → `order_name`, `fix_start_timestamp`/`fix_end_timestamp` → Work order: `planned_start_timestamp`/`planned_end_timestamp`, Calendar: `start_timestamp`/`end_timestamp`, `external_order_id` → `external_id`, `external_po_id` → `customer_po_id`, Customer/Product `external_customer_id`/`external_product_id` → `external_id`(+ `external_system`). Applies to V5·SDK·Event·MCP·Flow Node·DB Columns. No aliases	Name Changes
External Work Order Identification	`(external_system, external_id)` pair. V5 `POST`·`PUT`·`PATCH /order` both receive and response/actual documents both carry. Delete `GET /order/performance/by-external/{external_order_id}` and use `…/by-external/{external_system}/{external_id}`. Single work order is `GET /order/by-external/{system}/{external_id}`	MES Integration
Events	`planned_quantity_unit_of_measure`·`external_system` added to `plantpulse.order.`, `_quantity` + `unit_of_measure`(Original) and rework `rq`·`rq_quantity` added to `plantpulse.kpi.oee.finalized`. Appended without type change. Due to name changes, `plantpulse.order.`·`plantpulse.calendar.` are Schema Major 2(`dataschema` ends with `:2`)	Order Service — Quantity
Flow	Quantity in `OEE_EVENT` is now Quantity object (adds `rework_quantity`). Unit value is mandatory for `flow_create_work_order` (Path `unit_of_measure_field`, Default `data.unit_of_measure`). Path setting names for this node have also changed (`title_field` → `order_name_field` …)	Flow
UI	Unit symbols are attached to each quantity (language independent — `EA`, `kg`, `L`, `m²` …). Unit column added to work order form	Production Management — Quantities and Units

Numbers do not change. Work orders prior to upgrade are all moved to EA; since integer counts are preserved, OEE, Availability, Performance, Quality, and quantity sums are identical before and after upgrade. Rework is filled as the sum of existing REWORK defect records (0 if none), and only by that amount is scrap_quantity smaller than the old total_bad_count.

Name Changes — Old Names and New Names

Column names for work orders and calendars are unified to ISA-95 / B2MML names. Wire, SDK, Event, and DB columns all use the same new name; there are no aliases, compatible views, or dual-writing for old names (server-web 974891b4, Flyway V103 order_calendar_names_isa95).

Old Name	New Name	Changed Locations
`title`	`order_name`	Work Order — V5 Request·Response·`/order/query` row, SDK `setOrder_name`, Event `plantpulse.order.*`(appended to all types, including `deleted`), MCP `list_work_orders`·`get_work_order_kpi`, DB `mm_order`·`mm_order_revision`, Cassandra `tm_asset_order`
`fix_start_timestamp` / `fix_end_timestamp`	`planned_start_timestamp` / `planned_end_timestamp`	Work Order — Same as above. MCP `fix_start_at`/`fix_end_at` become `planned_start_at`/`planned_end_at`
`fix_start_timestamp` / `fix_end_timestamp`	`start_timestamp` / `end_timestamp`	Calendar — V5 Request·Response·Revision History, SDK `setStart_timestamp`/`setEnd_timestamp`, Event `plantpulse.calendar.created`·`updated`·`entry.*`, DB `mm_calendar`·`mm_calendar_revision`·`mm_shift`
`target_units`	`planned_quantity`	DB Columns `mm_order`·`mm_order_revision`·`mm_order_oee`. V5·SDK·Event were already `planned_quantity`
`external_order_id`	`external_id`	Work Order — V5 Request·Response·Actual Document·`/order/query` filter, SDK `setExternal_id`·`OrderQuery.externalId(..)`, Event, MCP `get_work_order_kpi`, DB
`external_po_id`	`customer_po_id`	Work Order — V5 Request·Response·Actual Document, SDK `setCustomer_po_id`, Transition Event(`started`~`aborted`), MCP, DB
`external_customer_id` / `external_product_id`	`external_id` + New Column `external_system`	Customer·Product — V5 Request·Response, SDK, DB. Pair lookup `GET /customer/by-external/{system}/{external_id}`·`/product/by-external/…` newly created
`baseline_fix_start` / `baseline_fix_end`	`baseline_planned_start_timestamp` / `baseline_planned_end_timestamp`	Work Order `deviation` object (V5·SDK·MCP)
Sort `fix_start_desc` / `fix_start_asc`	`planned_start_desc` / `planned_start_asc`	`sort` of `/order/query`
Flow `title_field` · `target_units_field` · `external_order_id_field` · `external_po_id_field`	`order_name_field` · `planned_quantity_field` · `external_id_field` · `customer_po_id_field`	`flow_create_work_order` Node Settings. Default paths also change to `data.order_name` · `data.planned_quantity` · `data.planned_start_timestamp` · `data.planned_end_timestamp` · `data.external_id` · `data.customer_po_id`

Old names are not accepted — some may be silently ignored, so update integrations first.

Sending old names to POST·PUT /order results in the column not being read. order_name becomes empty, leading to a validation rejection (order_name is mandatory and cannot be blank — order.name.required), and the planned time also becomes empty. If new and old names are mixed, saving is possible, but since PUT replaces the entire request column, external_order_id·external_po_id sent with old names will be deleted.
Sending old names to PATCH /order results in 422 «not patchable».
/order/query?external_order_id=… is not ignored and is rejected with 422 — use external_id and external_system.
Events are sent only as major 2. Major 1 schema files remain for playback only; new events carry new names.
Column names for /kpi/* responses and plantpulse.kpi.oee.finalized are not subject to this change (remain same).

Pre-Upgrade — Duplicate Check for External Identification Pairs

The new version applies an index ensuring uniqueness among work orders where both external identification fields are not empty (Flyway V100, ux_mm_order_external_pair). If two or more work orders already share the same pair, that step will fail. Use the following SQL to verify in the pre-upgrade DB. It uses the old column name external_order_id (which V103 later changes to external_id).

SELECT external_system, external_order_id, count(*)
  FROM pp.mm_order
 WHERE external_system <> '' AND external_order_id <> ''
 GROUP BY 1, 2
HAVING count(*) > 1;

The result must be 0 rows. If rows appear, correct either external_system or external_order_id before upgrading. Work orders with only external_order_id and an empty external_system are not considered a pair and are not affected (they remain as-is).

Initial Boot Behaviors

Repository	When	Action
PostgreSQL	server-web boot (Flyway V99 `order_quantity_isa95` · V100 `order_external_id_pair_unique`)	Changes quantity columns to `numeric(18,4)` and fills `unit_of_measure` as `'EA'` for each work order. Fills `REWORK` as the sum of defect records by adding `mm_order_oee.total_rework_count`. Moves product units to codes and changes `priority` to integer
PostgreSQL	Following Flyway V103 `order_calendar_names_isa95`	Changes DB columns in the Name Changes table to `RENAME COLUMN` — data, indexes, constraints, and views follow. Adds `external_system` column and pair uniqueness index to Customer·Product (system field left empty for existing rows). Halts if work order `status` is outside `WAIT`·`START`·`PAUSED`·`END`·`ABORTED`. Sets trigger to ensure status changes only occur with revision rows
Cassandra · Stored EQL	Platform first boot (core V21~V23)	Adds `order_name`·`planned_start_timestamp`·`planned_end_timestamp` to `tm_asset_order` and moves old column values (V21·V22, few seconds, old columns not deleted). Updates old property names in stored equipment statements (EQL) to new names (V23, SYSTEM revision) — statements that cannot be updated remain as diagnosis `diagnostic.asset.statement_not_renamed`
Cassandra	Platform first boot	Version migration adds new `decimal` quantity columns and `unit_of_measure` to small tables(OEE·EMS current·order, `tm_asset_order`) and fills existing rows (`'EA'`) — few seconds. Large tables(OEE·EMS rolling·rollup·history, `tm_kpi_oee_count`) are moved in the background after boot. Boot time remains the same

While large tables are moving, history KPIs are read from old columns with the same values. Once a table's migration is complete, it automatically reads only from the new column. Progress is shown in the server-web boot logs in lines starting with «Cassandra migration» (docker logs plantpulse-server-web | grep 'Cassandra migration').
Old integer columns (target_units·total_production_count·total_good_count·total_bad_count) are no longer read or written to after migration. Deleting these columns is scheduled for a future version, not this one. They are absent in fresh cluster installations.

2026.11 — Pre-upgrade Tasks and Renamed Fields​

1. Backup — Cassandra r4 is Irreversible​

2. Migration V121~ — Initial Boot May Take Longer​

3. Renamed Fields — No Backward Compatibility​

Statement Mandatory Columns​

4. Diagnosis — CEP Dead Letter Retention: 24 Hours / 256 MiB​

5. CEP — No Esper Backend or Per-Statement CPU Metrics​

6. Post-Upgrade​

2026.11 — Work Order Quantities and Names to ISA-95 / B2MML​

Changes Overview​

Name Changes — Old Names and New Names​

Pre-Upgrade — Duplicate Check for External Identification Pairs​

Initial Boot Behaviors​

Integration Update Checklist​