Admin: RPI version rollback procedure

Overview

This topic provides guidance to system installers and operations teams about rolling back your RPI version on Kubernetes or Docker Compose, SQL Server or PostgreSQL operational databases. This is the generic baseline procedure; adapt the environment-specific details (backup tooling, Helm release names, change-control steps) per deployment.

What a rollback involves

An RPI upgrade changes four kinds of state; a rollback must deal with each:

Two things decide the relative risk of a rollback:

• The release's Rollback Risk score (0–5), published in the release summary for every release. It reflects the riskiest change in the release.

• How much has happened since the upgrade. Work performed on the new version (workflow runs, saved changes, configuration edits) may not fully survive a rollback.

Choosing a strategy

Before every upgrade (rollback preconditions)

A clean rollback is prepared before the upgrade runs. Make these part of the standard upgrade procedure:

1. Enter maintenance mode: POST /api/maintenance/maintenancemode/enter on the Deployment Service. Wait for in-flight workflow executions to drain or reach a stable state. This is important: workflow state written mid-flight during an upgrade window can severely complicate an upgrade or a rollback.

2. Back up all operational databases: Pulse, Pulse_Logging, and every tenant's Interaction and InteractionAudit databases. These backups are the only way to recover customer-set values on settings that the new version deletes or renames, and the only rollback path for releases scored 5.

3. Record the installed version. Connect to the Pulse database and run the query for your database platform.

   SQL Server

   SQL

   SELECT Version FROM rpi_Cluster;
   

   PostgreSQL

   SQL

   SELECT "Version" FROM "rpi_Cluster";
   

   The query returns one row. Note the value returned, for example 7.8.20261015.1302.

Rollback overview (both strategies)

1. Enter maintenance mode (if not already in it).

2. Announce the outage; stop any external integrations that write through the Integration or Realtime APIs if your change process requires it.

3. Execute Strategy A (database restore) or Strategy B (in-place), below.

4. Perform the post-rollback manual steps and any release-specific steps.

5. Verify, then exit maintenance mode.

Strategy A: database-restore rollback

Database-restore rollback recovers everything, including customer-set values and permission assignments, at the cost of losing all work done since the backups were taken (workflow runs, audience changes, saved assets, configuration edits).

1. Stop all RPI services.

2. Restore Pulse, Pulse_Logging, and every tenant's Interaction and InteractionAudit databases from the pre-upgrade backups. Restore them as a set; mixing pre-upgrade and post-upgrade databases is not a supported state.

3. Redeploy the previous version's containers (Helm: set the image tags back to the previous release and upgrade the release; Compose: previous image tags).

4. Start the services. Because the databases and binaries are both back at the previous version, no reconcile is needed.

5. Continue at post-rollback manual steps, then verify.

Strategy B: in-place rollback

In-place rollback keeps all data and work done since the upgrade. The previous version's own Deployment Service reconciles the databases back to that version's baseline. Available when the version being rolled back to is v7.8.20261015.1302 or later; for older targets use Strategy A.

1. Redeploy the previous version's containers (image tags back, all services including the Deployment Service).

2. Call the rollback operation on the previous version's Deployment Service:

   POST /api/deployment/rollback?exitMaintenanceMode=false&waitTimeoutSeconds=300
   

   (Use exitMaintenanceMode=true only if no manual steps from post-rollback manual steps and release-specific steps apply.)
   The operation, per database (Pulse, Pulse_Logging, every tenant Interaction and InteractionAudit):

   • Re-creates missing tables and re-adds missing columns against this version's schema definitions.

   • Refreshes every stored procedure to this version's definition.

   • Restores deleted baseline configuration values, alerts, permissions, health checks, housekeepers, and cluster tasks at default values.

   • Clears the plugin registry and reseeds it from this version's plugin manifest.

   • Stamps rpi_Cluster.Version back to this version and restores the "what's new" content.

   Everything is guarded and idempotent: existing rows are never modified or duplicated, nothing is dropped, and re-running the operation is safe.

3. Read the returned deployment log (also available at GET /api/deployment/status). It reports, per database, what was repaired (missing tables/columns re-added, procedures refreshed, baseline rows ensured present) and states explicitly what a rollback deliberately does not restore. Keep this log: it is the rollback audit record.

What an in-place rollback does NOT restore

Communicate these to stakeholders before choosing an in-place rollback:

Additionally, in-flight workflow executions started under the newer version may not resume cleanly on the older binaries. Draining executions before the original upgrade (step 1 of Before every upgrade…) avoids this entirely.

Post-rollback manual steps (baseline)

1. Desktop clients do not downgrade: the RPI client self-upgrades only. Users whose clients updated to the newer version must reinstall the previous client (the server's Files/Client download serves the version now deployed). A newer client against an older server is not a supported combination.

2. Re-grant restored permissions: any permission the newer version had deleted is back at default (assigned to no group); re-grant.

3. Re-key customer values: restore customer-set values for any settings listed in the release's rollback notes as deleted/renamed, from the pre-upgrade backup or records.

Release-specific rollback steps

Each release's summary carries a Rollback Risk score per work item, and items scored 3+ carry the specific manual steps needed to make their rollback safe, including, where no step can make it safe, an explicit escalation to the database-restore strategy. Review the release summary for the release being rolled back before starting, and fold its steps into the post-rollback manual steps.

Verification checklist

Appendix: API quick reference (Deployment Service)

Last updated: November 12, 2026