Equipment Model Version Management

Overview

This section explains how Equipment Model versioning is handled when upgrades are processed through the component Installer → ServiceManager automated lifecycle pipeline, and what practices should be followed to ensure that Equipment Model updates remain consistent, safe, and reliable across different upgrade paths.

Equipment Model Versioning Has No Stored Version Number

The ServiceManager does not rely on a version number for Equipment Model components.

Reason: Customers may restore an older RTDB database backup after a component upgrade.

This causes:

If version numbers were trusted, ServiceManager would wrongly skip required updates.

Therefore, the lifecycle mechanism must rely on:

Content-based detection

The Install.bat uses the built-in upgrade logic (RTDB_upgrade_database.bat) to inspect the actual database structure, not metadata.

Idempotent update logic

The RTDB upgrade tools apply updates only when needed.

Re-run safety

If the same Install.bat runs again, no harm should occur.

This design makes version numbers unnecessary and unsafe.

How Version Control Works Automatically During Lifecycle Processing

The version control behavior emerges automatically from three facts:

(1) ServiceManager always runs Install.bat when a component changes

Whether the component folder contains:

• updated SQL definitions
• modified metadata files
• new dashboards
• new model structures ...

ServiceManager always triggers the Install.bat after copying the changed files to InstalledComponents.

Result:

The Equipment Model component is brought to the latest packaged state, regardless of previous state.

(2) Install.bat uses RTDB_upgrade_database, which performs content-based updates

The built-in RTDB upgrade mechanism:

• Checks whether required tables/columns exist
• Adds missing fields
• Updates definitions only when needed
• Never drops customer data
• Preserves all instance contents

This means the version change is decided by database content, not metadata.

(3) Multi-version jumps are automatically safe

Example scenarios that work without special handling:

Upgrading 5.1 → 6.0 directly

Upgrading 5.1 → 5.2 → 5.3 → 6.0

Restoring DB from 5.0 after metadata is at 5.3

Reapplying Install.bat many times

Why it works:

The upgrade scripts embedded in the system use structural checks (column exists, table exists, index exists) instead of version numbers.

Rules: How to Keep Versioning Safe

Rule 1 — Never Rename Equipment Model Elements

• No renaming Equipment
• No renaming EquipmentProperty
• No renaming indexes/columns used by Equipment Model

Why: renamed items cannot be matched using content checks.

Rule 2 — Try Not Delete Old Properties

Deleting might break:

• historic values
• dashboards
• calculations
• scripts

Safe option:

• Leave unused properties in the table.
• Mark as obsolete if necessary.

Rule 3 — Always Add New Definitions Instead of Replacing

This ensures:

• Upgrade works regardless of previous version
• Missing items are added
• Existing items remain unchanged
• Repeated upgrades do not corrupt the model

Rule 4 — Trust the Built-in Upgrade Logic

The version branching should not be manually implemented. Let these system tools handle it:

RTDB_upgrade_database.bat

Standard Install.bat generated by component installer

Structural check operations (ColumnCheckType, column-exists checks)

ServiceManager + RTDB upgrade tools will do the rest.

Documenting Equipment Model Changes Between Versions

Documentation enables predictable upgrades, reproducible results, clear traceability for reviews and audits, and effective communication across teams.