Skip to content

ZEV Export and Import

Export a whole community as a single archive file and import it into the same or another OpenZEV instance. This replaces the old tariff-only JSON transfer: an export with just the Tariffs section selected does what that used to do.

What it is for

  • Moving a community between instances — from a trial installation to a production one, or between hosting providers.
  • Taking a copy off the instance — an archive is a readable record of a community. The default export captures the structure (settings, participants, metering points and tariffs); tick readings and invoices for a full copy including billing history, and invoice PDFs too if you need the original issued documents rather than a reprint.
  • Starting a new community from an existing one — export the tariffs and the metering-point layout, import them, then add participants by hand.

It is not a backup. For that, see Backups.

It is not a disaster-recovery restore. An import always creates a new ZEV with new internal identifiers, so anything referring to the old ones — audit log entries, bookmarked links, references held by other systems — does not follow. The archive records the original identifiers so a true in-place restore can be added later, but today an import is a copy.

Exporting

  1. Open Setup → Settings → Export / transfer for the community.
  2. In the Transfer archive card, click Export ZEV.
  3. Pick the sections you want. The structure sections are pre-ticked — ZEV settings, participants, metering points and tariffs — and readings, invoices, invoice PDFs and participant documents start unticked, because they are the bulk of the file and can take a while to stream.
  4. Click Download archive.

The Export panel names the selected community. Tab switches keep any unsaved settings draft; Save remains available across the tabs. Viewers can export on purpose — a read-only role such as a trustee may keep a copy of the data — and so can anyone for a disabled community. Importing an archive is done by an administrator in the platform's ZEV list; the card says so, and gives administrators a link there.

Below the archive, the same tab holds Deactivate for the community. A deactivated community loses participant access and can only be viewed by its managers; no data is deleted, and only an administrator can reactivate it — the card and the confirmation both say so. Download a transfer archive first if you may need the data outside this instance.

You get a file named openzev-export-<community>-<date>.zip.

An export is a personal-data extract. It contains participants' names, addresses, email addresses and their full consumption profiles in one file. Treat it the way you would treat the participant list itself: encrypt it in transit, and delete it once the transfer is done. Every export is recorded in the audit log with the sections that left the instance.

Sections

Section What travels
ZEV settings Name, type, grid operator, billing interval, invoice prefix and language, payment term, bank details, VAT number, notes, the invoice email template, and the contract-PDF notes
Participants Names, addresses, contact details and validity windows
Metering points & assignments The community's buildings, meters (each in its building) and which participant held each one over which period
Tariffs Every tariff, all its versions, and their price bands
Charges The community's one-off charges and who each is billed to — needs Participants
Meter readings Billable and held SDAT-CH readings, with delivery provenance and quality, as CSVs per meter
Own energy data The energy data sources participants connected for a PV system behind their meter, and their quarter-hour values — opt-in, see below
Invoices Invoices, line items, and reading-correction review flags with their source evidence
Invoice PDFs The original rendered document for every invoice that has one — needs Invoices
Participant documents Everything in the participants' document inboxes — invoices, contracts, statements and operator documents, with the exact files delivered — needs Participants

Own energy data

Own energy data is a participant's household profile — what their own system measured, every quarter hour. They connected it for statistics, and you, as manager, see it as statistics rather than as raw values. So this section is never ticked by default, and a request that names no sections (a script calling the export) leaves it out. Tick it deliberately, for instance when you move a community to a new instance and want the history to come along.

What travels is the data and what describes it (the source type, its Solar Manager ID or name, the period covered). No key and no push token travels, and neither does anything about the live connection. After an import every source is disconnected: it keeps its data, but no new data arrives until the participant opens Account → Energy data and connects again with their own key or a new push token. The import tells you so. It needs Participants and Metering points & assignments, because a source belongs to a participant's metering point.

Some sections need others. Assignments point at participants, readings point at metering points, invoices point at participants, and invoice PDFs point at invoices — so the dialog greys out a section whose prerequisite is unticked and tells you what it needs. You cannot build an archive that could not be imported.

Participant invoice access does not travel. An imported ZEV always arrives with Participant QR code on the invoice switched off, whatever the exporting instance had it set to. Importing an archive must never grant access to anything; if you want it on the new instance, turn it on there deliberately.

Tariffs and invoices are deliberately independent of one another: an invoice records what was charged rather than pointing at a live tariff, so billing history can travel without the pricing structure and vice versa.

What deliberately does not travel

  • User accounts. Participants are exported without any link to a login, so an archive can never grant anybody access to anything.
  • Generated invoice PDFs — unless you explicitly tick Invoice PDFs. Left unticked, an imported invoice reports "not generated" until one is next rendered, and that render uses today's template — it will not be byte-identical to the document the participant received. If you have a retention obligation for the original documents (or are retiring the community and want to keep exactly what was issued), tick the section and the original bytes travel with the archive instead.
  • Email and PDF templates stored in the admin console. These are instance-wide customisations rather than ZEV data. The per-ZEV invoice email template and contract notes do travel, in the ZEV settings section.
  • Audit events, import logs and system settings. Instance-scoped.

Importing

Importing is admin-only, because it creates a ZEV and only admins create ZEVs on an OpenZEV instance.

  1. Open Platform → Overview → ZEVs.
  2. Click Import ZEV.
  3. Choose the .zip archive. OpenZEV reads its manifest and shows what is inside, with a row count per section.
  4. Optionally rename the new community.
  5. Untick anything you do not want.
  6. Click Import.

The importing admin becomes the manager of the new ZEV. The participants section also brings the community's people and organisations (also those who are not participants) and who was its issuer, representative and landowner, and since when. An archive from an older OpenZEV version has no issuer, so its documents carry the community's name until one is set.

Importing twice creates two communities. There is no "have I already imported this?" check, so if you are unsure whether an import went through, look at the ZEV list rather than clicking again.

Participants arrive unlinked

Even when an account with the same email address already exists on the instance, imported participants are not connected to it. Matching on an email address found inside an uploaded file would let anyone who can edit that file hand an existing account access to a community's data. Link accounts by hand afterwards — see Participant Management.

Invoice numbering

If the archive carries invoices, the new ZEV's invoice counter is set above the highest number imported, so the next billing run cannot mint a number the community already has. Importing without the invoice section starts numbering at 1.

When an import is rejected

Nothing is created unless everything validates. If any entry fails, the whole import is rolled back and the dialog lists every problem it found at once — by section, entry and reason — so an archive with several issues takes one pass to diagnose rather than one per issue.

Meter IDs are unique across the whole instance

This is the most common rejection. A meter ID identifies a physical meter, and OpenZEV allows it to exist only once per instance — so a community cannot be imported alongside one that already holds the same meters:

Metering point 'CH-DEMO-CONS-0001' already exists on this instance.
Meter ids are unique instance-wide, so this ZEV cannot be imported
alongside the one that already holds this meter.

Every colliding meter is named. This is what you will hit trying to import a ZEV back into the instance you exported it from. Either delete the original first, or import into a different instance — which is what the feature is for.

Format versions

Every archive records the format version it was written with. An archive from a newer OpenZEV than the one you are importing into is refused outright rather than partially understood:

Unsupported archive format version 2. This instance reads version(s): 1.

Upgrade the target instance and try again.

Archives without buildings. Archives written before buildings existed (format 5 and older) import fine. Their metering points are placed the way OpenZEV placed existing communities when it added buildings: a ZEV gets one building, a vZEV one building per distinct participant address. That is a guess from billing addresses; check the buildings after importing. If you import without the metering-points section, the new community gets a single building.

Corrupt or inconsistent archives

An archive that cannot be read — a file that is not really a ZIP, a manifest that is damaged, a readings file that is unreadable — is refused with a clear message instead of failing halfway through. Nothing is created unless everything validates, and the import also checks that each section really contains the number of entries its manifest promises; if the archive's own declaration disagrees with its contents, it is rejected as inconsistent.

Readings member names

Inside the archive, each meter's readings live in a file named after the meter ID, with a short checksum suffix so two meter IDs that look similar after sanitising still get separate files (e.g. A/B and A_B).

Archive contents

The archive is an ordinary ZIP; you can open it to check what you are about to move.

openzev-export-demo-community-2026-08-04.zip
  manifest.json          format version, export time, sections, row counts
  zev.json               community settings
  participants.json
  buildings.json         the community's buildings
  metering_points.json   including assignments and each meter's building
  tariffs.json           versions and price bands
  invoices.json          invoices and line items
  readings/<meter>.csv   one file per meter (name includes a short checksum)
  supplementary_sources.json            energy data sources, if ticked
  supplementary_readings/<meter>.csv    their quarter-hour values, one file per source
  invoices/pdf/<invoice>.pdf   one file per invoice that has a rendered PDF, if ticked
  delivered_documents.json     the participant documents, if ticked
  delivered_documents/<id>.pdf the delivered files, one per document

Readings use the same column layout the metering import reads — meter_id, timestamp, energy_kwh, direction — plus resolution and import_source so nothing is lost in a round trip. An individual CSV can therefore be fed to the normal metering import if you only want one meter's data.

Size and timing

Archives compress well, because meter readings are highly repetitive. As a reference point, a three-meter community with four months of 15-minute data — 34,848 readings — produces a 180 KB archive in about a second, and imports in about seven.

A large community with several years of data will take proportionally longer, and the export runs while your browser waits. If you are moving something very large and the request times out, split the export into separate archives — the structure sections are the default, readings can be exported afterwards — and import them as separate steps.