MngInstallSystemUpdate

Starts an asynchronous update to a specific published version returned by MngGetSystemUpdates.

Access

The router accepts SESSION_ADMIN and SESSION_CRM_ADMIN, but the resolved staff manager must additionally have super_admin = 1. A regular BackOffice or CRM brand administrator cannot install an update.

The authorization decision is based on the current enabled staff manager record, not solely on values contained in the JWT.

Request

Field	Type	Required	Description
version	string	Yes	Exact published version from MngGetSystemUpdates.releases[].version

{
  "command": "MngInstallSystemUpdate",
  "data": {
    "version": "1.25.216"
  },
  "extID": "MngInstallSystemUpdate_1",
  "__token": "<superadmin-jwt>"
}

The server revalidates that the requested version is published and newer than the running version. Clients must not derive or submit an arbitrary version without first retrieving the available release list.

Accepted response

Handler status: 202.

{
  "accepted": true,
  "version": "1.25.216",
  "status_available": true,
  "update_id": "upd-1790142000-a1b2c3d4e5f6",
  "status_port": 8098,
  "status_token": "<per-update-bearer-token>",
  "status_retention_seconds": 60
}

status_available is always returned. The remaining status fields are present when the updater status endpoint is enabled on the server. BackOffice must retain the hostname of its current platform connection and replace only the TCP port with status_port.

accepted: true means the updater process was launched. Installation then continues outside the request lifecycle: it downloads and validates the runtime package, prepares staging, stops the service, replaces runtime files, restarts the service and checks its state. If the new service does not become stable, the updater attempts to restore the previous runtime.

The main TCP connection closes when the server is stopped. BackOffice should treat the 202 response as the final response for this request and then poll the temporary updater endpoint.

Update status endpoint

The updater runs a temporary read-only TCP server before stopping the main platform process. It uses the same JSON plus \r\n framing as the manager TCP API but supports only GetUpdateStatus.

{
  "command": "GetUpdateStatus",
  "data": {
    "update_id": "upd-1790142000-a1b2c3d4e5f6",
    "token": "<per-update-bearer-token>"
  },
  "extID": "GetUpdateStatus_1"
}

Response:

{
  "extID": "GetUpdateStatus_1",
  "status": 200,
  "data": {
    "update_id": "upd-1790142000-a1b2c3d4e5f6",
    "target_version": "1.25.216",
    "state": "installing",
    "progress": 75,
    "message": "Runtime files installed",
    "started_at": 1790142000,
    "updated_at": 1790142024,
    "terminal": false,
    "success": false
  }
}

Field	Type	Description
update_id	string	Identifier received from MngInstallSystemUpdate
target_version	string	Version being installed
state	string	Current updater stage
progress	int	Stage-based progress from 0 to 100; it is not download byte progress
message	string	Human-readable stage or failure information
started_at	int64	Updater start time as a Unix timestamp
updated_at	int64	Time of the latest state change
terminal	bool	No further update stages are expected
success	bool	true only for a successfully completed installation

Possible states are:

• preparing
• downloading
• validating
• staging
• stopping
• backing_up
• installing
• starting
• verifying
• completed
• rolling_back
• rolled_back
• failed

Status endpoint errors:

Status	Error	Meaning
400	INVALID_REQUEST	Malformed JSON or required request envelope is missing
403	PERMISSION_DENIED	update_id or status token does not match this update
404	COMMAND_NOT_FOUND	Any command other than GetUpdateStatus was requested
413	REQUEST_TOO_LARGE	Request exceeded the temporary endpoint limit

After terminal: true, or if the temporary endpoint disappears, BackOffice should retry the regular platform TCP endpoint and confirm its reported version. The updater keeps a terminal status available for status_retention_seconds and then exits.

Errors

Handler status	Error	Meaning
400	INVALID_DATA	version is missing, is not a string or violates its length constraints
403	NOT_ENOUGH_RIGHTS	The resolved manager is not a SuperAdmin
409	RELEASE_NOT_AVAILABLE	Version is not published, is not newer than the running version or is absent from the current registry index
500	UPDATER_START_FAILED	Server could not refresh or launch the updater process
503	RELEASE_NOT_AVAILABLE	Registry could not be reached or validated while checking the target version

The message field may contain a registry diagnostic for RELEASE_NOT_AVAILABLE.

Journal

Every install attempt is written to the product journal with its request. The response is intentionally omitted because it contains the temporary status token. Listing available updates uses failures-only journal policy.