What Is Migrated
The project is exported/imported in a single file in MergenHub's own package format. Purpose: backup, moving to another machine, sharing field templates, and migrating from WinCC/Kepware.
Connections → Export offers two scopes:
| Full project bundle | Channels · devices · tags · tag groups, Advanced Tags, Aliases, modules (Historian groups, alarm definitions, Data Bridge agents, SCADA screens/zones/symbols, counter / metric / water profile / report definitions) and portable server settings. Optional: counter history and manually entered values. Recommended. |
| Configuration only | Channels/devices/tags + Advanced Tags + Aliases. Compatible with Kepware JSON. |
A single channel or device can also be exported separately by right-clicking it in the tree (Export (JSON)).
Driver limits also apply on import: if, at the end of the import, a driver's channel count or a channel's device count would exceed the limit, the whole import is rejected and the existing project is left unchanged (no partial import).
| Format ID | "format": "mergenhub-project" |
| Format version | "version": 2 — an unreadable version produces a clear error |
| Application version | "app", "exportedAt", "exportedBy" |
| Scope | "scope": project / channel / device |
Migrating with History and Full System Backup
By default the full project bundle carries only the definitions. To move the system to another server with its history (or to hand over history migrated from another system), you can also add the history to the bundle when exporting.
Exporting with history
- Connections → Export, scope Full project bundle.
- Tick the Include counter history and manually entered values box.
- Export. The file grows (a hundred thousand period records are about 10 MB).
| Included in the bundle | Each counter's state (last index, reset count…), period records (hour, day, week, month, year), events (reset, rollover, manual correction…) and manual corrections; the values of every manual input (with the note and the user who entered them). |
| Not included in the bundle | Data log (Historian) rows, alarm history, audit and event records, users. For these use the full system backup below. |
Importing with history
| Merge (default) | History is written only to counters and inputs that have no records at all on this system. A counter that has records is not touched and is reported by name on the summary screen: measured records are never silently overwritten. |
| Replace | The history in the bundle replaces the records on this system. |
| The counter continues where it left off | An imported counter knows its last index: when the device connects, the increase in between is added as consumption; no reset or spike arises. |
| Time zone | Day and month boundaries were cut according to the time zone of the source system. If the target is in another zone a warning is shown on the summary screen (the boundaries may appear shifted). |
Full system backup
The project bundle is for migration; for backup use Settings → Backup (only the Root user sees it). A backup is a consistent copy of the data folder and is written as a zip file. Definitions are always backed up: project, settings, users, SCADA screens, alarm / counter / metric / report definitions, licence and certificates. Because records can take a lot of space, you choose which of them go into the backup.
Setting up the backup: step by step
- Tick the Daily automatic backup box; enter the Time, the Target folder (a local disk or a network share / NAS; if empty, backups under the data folder) and the number of Copies to keep.
- In the Records included in the backup section tick the boxes. Next to each box is the current size of that record; at the bottom is the Estimated backup content (before compression) total, which updates as you change the boxes.
- If you wish, tick the Notify / send the backup by e-mail box and enter the Recipients (separated by commas). The mail server is taken from the e-mail settings in Settings.
- Press Save. Back up now takes a backup immediately; the backups taken are downloaded from the list.
| Definitions (always) | Cannot be turned off; everything needed to rebuild the system. |
| Counter history and manually entered values | The period records of counters and the manual inputs. If you turn it off, the counter history comes back empty on restore. |
| Alarm history | Past alarm records (not the definitions). |
| Event log and audit log | The event log and the record of who changed what. |
| Data logger (Historian) | Tag logs; this takes the most space. On large systems it is more suitable to keep it out of the daily backup and back it up separately. |
| Attach the backup file; at most … MB | If the backup is smaller than this size it is attached to the e-mail; if larger, only the notification is sent and the file stays in the target folder (between 1 and 50 MB). |
| Send only when the backup fails | No e-mail is sent on a successful backup; you are notified only if there is an error. |
| Send a test e-mail | Sends a test message to the recipients you entered right away; you see that the e-mail settings work without saving. |
| Restore | The service is stopped, the backup (zip) is extracted into the data folder, the service is started. |
Sensitive Data Policy
Covered fields: driver passwords (mqtt.PASSWORD, opcuaclient.…_PASSWORD, iec_61850_mms_client.DEVICE_AUTHENTICATION_PASSWORD…), the Historian DB password and PWD= in the ODBC string, SMTP/SMS passwords, Data Bridge agent passwords and OPC UA user passwords. The rule works on the key name (every field containing PASSWORD, SECRET, APIKEY, TOKEN, PRIVATE_KEY) — driver fields added later are covered automatically.
The package reports which fields were removed with the "redactedFields" list; on the target system you only need to enter those by hand. Information needed to establish the connection, such as server address, user name and port, is kept.
If the user explicitly chooses "Include credentials", passwords are written in plain text; the package carries the "includesSecrets": true stamp and the operation is additionally recorded in the audit log.
Which Settings Are Migrated
| Migrated | OPC UA server (endpoints, security policies, user list — without passwords, session limits) · Data Bridge agents · email/SMS server settings · message templates · scan/monitoring/retention parameters · branding (logo, company name) · SCADA map tile URL · Windows service startup preference |
| Not migrated | The api section: web listen URL, HTTPS port, certificate binding |
api is not migrated The listen address is specific to the machine. If imported, the target server's web listener breaks and the administrator is locked out of their own UI. This is the most common and most dangerous migration mistake; that is why it is deliberately out of scope.Importing the settings is optional — it is chosen with a separate checkbox on the preview screen, and is off by default.
Import: Merge / Replace
Import has two steps. First the file is uploaded and scanned (stream-based — a 450,000-tag file is not loaded into memory); nothing changes at this step. The preview screen shows what is coming (how many channels/devices/tags/advanced tags/modules) and which names conflict. It is applied after the mode and conflict behavior are chosen.
| Merge (default) | The existing project is kept; incoming new channels are added. The project name does not change. |
| Replace | The existing project is deleted entirely. It cannot be undone; it does not run unless a separate confirmation checkbox is ticked. |
On a name conflict there are three behaviors — chosen in bulk, and changeable per item if desired:
| Skip (default) | The existing item is kept, the incoming one is skipped. |
| Rename | The incoming item is added as Ad_1; both remain. Incoming Advanced Tag expressions, aliases, Historian items and alarm tag paths are corrected automatically to the new name. |
| Overwrite | The existing item is deleted, the incoming one is written. |
When finished, the counts of added / overwritten / renamed / skipped items and an item-by-item result list are shown; the same summary is written to the audit log.
After the Import: What Is Where
When the import finishes, the summary screen lists what arrived and how many. This section tells where each imported item lives in the interface and covers the "did it not arrive?" situations asked most often after an import. If a number on the summary screen is not zero, that definition is in the system; look in the place given in the table below.
Row in the summary → place in the interface
| On the summary screen | Where it appears |
|---|---|
| channels, devices, tags | The Connectivity tree in the left menu. |
| screens, symbols, zones | The SCADA page (screen list and zone tree). |
| alarms | Plugins → Alarms (alarm definitions). |
| log groups | Plugins → Data Logs. |
| counters, metrics, manual inputs | Plugins → Counters & Metrics: the Counters, Metrics and Manual inputs tabs. |
| counter history (period records), manual input values | On the same page, by clicking the counter or the input; the Period report tab and the reports use this history. It arrives if the package was exported "with history". |
| Counter tracking lists | The third tab of the Plugins → Reports page, Counter tracking lists; the same list is also on the Counters & Metrics → Excel reports tab. Click the report to open it; the Excel button downloads the file with grouped, coloured headers. |
| Report pages | Plugins → Reports → Report pages (first tab). |
| Table reports | Plugins → Reports → Table reports (second tab). |
| water footprint profiles, water efficiency profiles, water flow diagrams | The three pages under Plugins → Water Management. This entry is shown while the Water Management feature group is on; if the package brought a water profile, the import turns the group on by itself. |
| category and group names, group colours ("kategori ve grup adı", "grup rengi") | The Categories and groups window on the Counters & Metrics page. Group colours are the header colours of grouped reports. |
Frequently asked
| Situation | Why | What to do |
|---|---|---|
| The counter tracking list (Excel report) is not visible on the Reports page. | The report did arrive; the page opens on the first tab, so the list on the third tab is not in view. | Open the Reports → Counter tracking lists tab (its title shows the count), or look at the Counters & Metrics → Excel reports tab. |
| On the Water Footprint page only blue water is filled in; green and grey water are empty. | The page opens the current year. Green water needs rainfall; grey water needs discharge and laboratory values (COD, BOD, TSS). If these were not entered for that year the cell stays empty. It is the same on the source system. | Switch the year to one whose inputs are filled in; or enter the missing values on the Counters & Metrics → Manual inputs tab (or in the cell marked ✎ on the water page). The calculation fills in by itself. |
| The Water Management entry is missing from the left menu. | The Water Management feature group is off (the default on a new installation). In 3.10.1 and earlier the import did not turn it on. | Turn on Settings → Feature groups → Water management. From 3.10.2 on, a package that brings a water profile turns the group on by itself. |
| In a grouped report all group headers have the same colour. | In 3.10.1 and earlier, group colours were not carried by the package. | Import the package once more with 3.10.2 in Merge mode (channels show as "skipped", counter history is not touched, the colours arrive); or pick the colours in the Categories and groups window. |
| The summary title is a red Finished with errors; a box at the top says "N section(s) could not be imported". | The named sections could not be written to disk; the most common cause is that the file was held by another program at that moment (real-time virus scanning, backup). The other sections were applied. In 3.10.2 and earlier, in such a case all later sections (log groups, alarms, screen images, counters, water management, settings) were silently skipped and the title still said "Done". | Import the same package again in Merge mode: existing items are kept and the missing ones are completed. If it keeps happening, exclude the data folder (C:\ProgramData\MergenHub) from the scan of your virus protection. |
| Screens show a red "Screen background not found"; the summary has a "EKSİK EKRAN ALTLIĞI" (missing screen background) line. | The background image of the screen is not on this server: the image could not be imported, or the package does not carry images (a package prepared with 3.9.x or earlier). | Import the package again in Merge mode; the summary must show an ekran altlığı: N (screen backgrounds) line. If the package carries no images, export it again from the source system as a Full project package. |
| Counter history did not arrive; the warning says the counter "already has records on this system". | Merge mode never silently overwrites measured records. | If you want to replace them with the history in the package, use Replace mode (see Migrating with history). |
| Devices do not connect, or alarms do not work. | The package may have been exported with data collection, alarms and log groups turned off, so that a test machine does not connect to the field. | When commissioning, in this order: turn on data collection on the device, see that values arrive, then turn on the log groups and the alarms. |
MergenHub