Charger cutover runbook: flip and rollback

This is the field runbook for moving chargers from a previous platform to Ivora through the charger proxy, one charger at a time, and for moving them back. It is also the training exercise for migration teams: rehearse it end to end on a bench project with simulated chargers before the first real site.

The charger proxy sits at the address your chargers already dial. For each charger it holds the connection and routes it to one platform, the previous one or Ivora:

• A flip moves one idle charger to Ivora. The charger keeps its connection: the proxy holds its messages for about two seconds, connects it to Ivora, and asks it to report its boot and connector status to Ivora.
• A rollback moves it back the same way. It is always allowed, also while the charger charges.
• Every charger starts on the previous platform. A platform that fails keeps its chargers: the proxy never moves a charger to the other platform by itself, so a session never starts on one platform and ends on the other without a person deciding it.

The charger proxy, its operator commands and its rehearsal lab are Ivora's migration tooling. They are maintained apart from the API, in Ivora's ivora-migrate repository, and reach Ivora only through the public API on these pages: each station's own password, the project's proxy key and the documented routes. Ivora's migration team runs them; this runbook says what each step needs from you.

Roles and credentials

Use a bench project and its own keys for a rehearsal, never your production project or keys.

Before the first flip

Start from the network's answers to the migration discovery questionnaire: they list the charger models, SIMs, payment terminals, card formats and quiet windows each step below depends on.

1. Import the site (Network import): dry run, review every row, then apply that dry run. Each charger keeps its own ID and connects at its project URL.
2. Import the driver cards (RFID tokens): dry run, then apply. A card Ivora does not know is refused at the charger after the flip.
3. Store each station's Ivora password, on Ivora and on the proxy. The chargers keep connecting without OCPP security, as they do to the previous platform today, and nothing on them changes. The proxy sends the previous platform no credentials, and signs in to Ivora for each charger with that station's own Ivora password, a new one per station that only Ivora and the proxy hold (the proxy keeps it in its secret store or a file only it can read, never on the charger):
   • Generate one password per station, give the list to the proxy operator, and set the same password on each Ivora station (PUT /v1/tenants/{tenant_id}/stations/{station_id}/credentials).
   • Only while the station is not connected to Ivora, that is before its flip. Ivora then stores it for the charger's next connection (result.applied = "stored", Credentials). A PUT while the station is connected to Ivora pushes the password to the charger (AuthorizationKey), which leaves a credential on it, also after a rollback. To change the password of a flipped station, roll it back first, set the new password on Ivora and the proxy, then flip it again.
   • The proxy refuses to flip a charger it holds no Ivora password for. A password that differs between the proxy and Ivora shows as a flip that never lands: Ivora refuses the connection, and you roll the charger back.
4. Tariffs on every connector (Tariffs), or sessions after the flip are not priced.
5. QR stickers (QR sticker redirects): the previous platform's origins and the stickers, so a scan follows each charger as it moves.
6. The proxy key is on the proxy host, and the proxy refuses any other key.

Shadow mode (optional, before flipping)

In shadow mode the previous platform keeps control and the proxy sends Ivora a copy of each charger's traffic. Ivora answers nothing that reaches the charger and bills nothing; it records what it would have done, so you can compare sessions before any charger moves. Ivora turns shadow mode on and off per station; a station must leave shadow mode before its flip (409 station_in_shadow otherwise). Ending shadow mode means one planned reconnect of every charger while the proxy drops its copy connections.

Flip one charger

One charger at a time, in an agreed window:

1. Idle at the site. No car plugged in. The proxy checks it too, from the charger's own messages: every connector reported Available (or Unavailable, Faulted) and no transaction open. Busy or "can't tell" refuses the flip and nothing changes; try again later.
2. Flip it with the proxy's operator command, with your name. Only a rollback or a forced action needs a reason.
3. Within a minute, the station shows online on Ivora (GET /v1/tenants/{tenant_id}/stations/{station_id}), with a fresh boot.
4. Report the route for QR scans (the proxy does this with its key), then check one sticker: GET /v1/tenants/{tenant_id}/qr/resolve?code=<sticker> answers ivora.
5. A test session with a site card: it starts, the charger's screen shows the running cost where the tariff and the charger support it, it stops, and the transaction appears on Ivora with its energy (GET /v1/tenants/{tenant_id}/transactions?station_id=…, energy_wh). If the charger reports the California Pricing keys (DefaultPrice or DefaultPriceText), switch on Ivora's display pricing for the station at the flip (PUT /v1/tenants/{tenant_id}/stations/{station_id}/display-pricing with {"enabled": true}, Charger displays; off by default in production); otherwise the screen keeps the previous platform's last price. After a rollback, the previous platform's next DefaultPrice push restores its price.
6. Two minutes later, the charger still gets answers (its heartbeats and status messages are answered). A charger that is connected but unanswered is reconnected or rolled back.
7. Write it down: the time, the charger, who flipped it.

Abort criteria

Stop flipping and roll back the affected charger (or all of them) when:

• a charger is not online on Ivora within three minutes of its flip;
• a charger is connected but its messages go unanswered;
• a session is missing on Ivora, or its energy differs from what the charger metered;
• a card that works on the previous platform is refused on Ivora;
• a QR scan of a flipped charger does not reach Ivora checkout;
• Ivora's connection or API is unavailable;
• anything you cannot explain. A rollback is cheap; a split session is not.

Roll back

• One charger: the proxy's rollback command with a reason. No idle check runs first. The charger keeps its connection and is controlled by the previous platform again within seconds.
• A site or every charger: the proxy's rollback command for each charger.
• From the Migration page (Pilot charger rollback, or the migration's workspace in the Migration portal): Ivora records the rollback, and only a proxy that collects it applies it: the pilot's routing proxy while its sync runs, or a migration runner. The per-charger cutover proxy does not collect them yet, and the lab rehearsal does not exercise this path. With the cutover proxy, roll back with its own command and treat a rollback asked on the Migration page as a request to the operator. The page catches up afterwards: the proxy reports the charger's route after the rollback, and the charger's recorded route there follows it.
• After a rollback: the QR route goes back to the previous platform (a scan no longer resolves to ivora), and a test session on the previous platform works.
• A rollback while charging leaves that session to reconcile by hand on both platforms: the charger sends its stop to the previous platform with a transaction only Ivora knows.

Rehearse it

Run the whole runbook on a bench project with simulated chargers (OCPP 1.6 and 2.0.1) behind a rehearsal proxy, then once more on the real proxy host before the first site:

1. Import the bench fleet (dry run first), its cards and its passwords.
2. Optionally shadow, then end shadow mode.
3. Flip every charger, one at a time, only when idle; check each one online, its QR route and a session on Ivora.
4. Roll every charger back; check the QR route and a session on the previous platform.

Then, if the previous platform's operator agrees, repeat it with a few test stations on the previous platform itself (a separate test site, free, not public) as the old side:

• Observe first, without any flip: record what the previous platform sends the chargers when they connect (its BootNotification answer and heartbeat interval, configuration reads and changes, triggers). Expected: configuration reads, triggers, changes of intervals and measurands, and a ChangeConfiguration of the screen-price keys (DefaultPrice/DefaultPriceText), which only sets the price text on the charger's screen; record the price it pushes.
• Keep the two platforms' credentials apart. Chargers that connect to the previous platform without security keep doing so: the proxy sends the previous platform no credentials and signs in to Ivora with each station's own Ivora password, held only on the proxy. Nothing is pushed to the chargers, so a rollback leaves no credential on any of them.
• Check sessions on the previous platform by the charger's own answers (a transaction ID, the card accepted), not by its portal.
• Stop and roll back at any unexpected call from the previous platform, such as a change of the charger's server URL, a firmware update or a reset.

Record, per direction and charger type, as the rehearsal report does:

A rehearsal passes only when every row passes. Keep the report with the migration's records.