Upgrading

About 14 min read

This page describes how to upgrade an existing 2WinScada installation to a new version, how to repair the same version and how to uninstall it. For the changes in a version, see the Release Notes.

Before upgrading

1. Read the release notes. In particular, check the "Upgrade notes" and "Behavior changes" sections.
2. Plan a maintenance window. During the upgrade, the 2WinScada services are stopped; the web interface cannot be used, and data collection and archiving stop.
3. Take backups:
   • Take a configuration backup from the web interface. See Backup and Restore.
   • Take a full backup of the SQL Server database.
   • Back up the data folder of the archive database (QuestDB).
   • Keep a copy outside the server. Also keep the installation package of the previous version.
4. Prepare the SQL backup directory. Setup backs up the database to this directory before an upgrade or repair. If SQL Server is on this computer, the wizard fills in the field with the instance's default backup folder. The directory must be an absolute local disk path on the SQL server that the SQL Server service account can write to; a network share is not accepted. The directory must have free space equal to the allocated size of the database plus 1 GB. For the required SQL permissions, see Permissions.
5. Prepare the installation account. If Setup will upgrade the database with SQL authentication, the user name and password of this installation account are asked for again.
6. Plan the kiosk screens. After the upgrade to 2.10, kiosk accounts may ask for a password change at the first sign-in. After the upgrade to 2.11, someone must sign in once on every kiosk screen. See Points to note when upgrading to this version.

Upgrading with Setup

1. On the same server, open the 2WinScada.Setup.<version>.x64.exe file of the new version with Run as administrator.
2. Setup detects the installed system. The Installation Mode page shows the installed version and the package version; if the versions differ, Upgrade is selected. Install cannot be selected on this page.
3. Continue with Next. Setup brings the installed settings into the wizard: components, installation directory, company name, IIS addresses and ports, SQL Server and database, SQL backup directory and QuestDB options. The installation directory cannot be changed during an upgrade. The installed MQTT broker and MCP settings are not shown in the wizard; the upgrade keeps them as they are.
4. Check the pages:
   • The existing component selections are kept. A new component can be added. A newly added MQTT Publisher starts with publishing off; the broker is entered in the web interface on the Settings > MQTT Publisher Settings page. See MQTT Publisher.
   • Passwords are not shown in the wizard. The SQL, QuestDB, MQTT and MCP details used by the application are taken from the installed settings files.
   • On the Database and recovery page, the SQL backup directory (required for upgrade and repair; path on SQL host) is required.
   • Do not select the Upgrade the local QuestDB engine (requires a data backup) option on the QuestDB performance and ports page in a normal upgrade. Upgrading the QuestDB engine is a separate operation that is done deliberately.
5. Check the Summary page and start the upgrade. Before continuing, Setup checks the settings on this computer; if a setting cannot be used, it stops without changing anything and lets you correct it with Back.

If Setup cannot read the installed settings safely, it stays on the Installation Mode page and shows the reason.

What Setup does

1. Runs the pre-checks; prepares the new files in a separate area.
2. Stops the 2WinScada services.
3. Backs up the application files, the settings and the SQL database.
4. Applies the database changes in order and puts the new files in place.
5. Starts the services and runs the health checks.

If a step fails, Setup automatically returns to the previous version. The message "Automatic recovery completed" does not mean that the upgrade was done; the system runs on the previous version. Fix the first error and start the upgrade again. If the rollback cannot complete either, Setup offers recovery when it is opened again; no new operation is started until recovery is complete. Do not delete the Setup logs or the backup folders by hand.

What is kept during an upgrade

• The existing settings files are merged with the settings of the new version; customer values are kept.
• License files are kept.
• IIS addresses, certificate bindings and internet settings are kept.
• The memory settings of the installed QuestDB are not changed.
• Changing ports or moving the database is not part of an upgrade.

2.10 database changes

The database schema is updated in 2.10; Setup applies the required changes automatically and in a way that can be run again. Saved pages need no conversion.

Points to note when upgrading to this version

2.11: session renewal cookie

With 2.11 the web interface keeps the session renewal key in a cookie that scripts cannot read instead of in browser storage. Details: Browser session.

• Sessions opened before the upgrade keep working the old way until the next sign-in. For the protection to apply on kiosk screens as well, sign in once on every kiosk screen after the upgrade. If several kiosks share one account, first give the kiosks separate accounts. See Session renewal and shared accounts.
• In a session opened by a sign-in after the upgrade, signing out also invalidates that browser's renewal key on the server. In sessions opened before the upgrade, the key stays in browser storage until the next sign-in, and signing out does not invalidate it on the server.
• The web interface and the API must be on the same site. In the setup that Setup installs, no extra setting is needed. In older installations where the web interface calls the API on another port, open the interface with the name and scheme of the API address.
• Use HTTPS; over HTTPS the cookie is sent only over an encrypted connection.
• The MCP server and API clients are not affected.

Required password change and kiosk screens

With 2.10, accounts whose password was set by an administrator and accounts that came with older installations and whose password has never been changed are first taken to the Change your password screen when they sign in; nothing else can be done until the password is changed.

Kiosk screens

Panel PCs and wall displays that stay on all the time wait on this screen when their session is refreshed after the upgrade to 2.10, if they use an account within this scope. Right after the upgrade, change the password of the account used on kiosk screens to a strong password; if a password is saved in the browser, update it as well. See Panel PC and Kiosk.

Writing by ID in event code

In 2.10, the setTag(<number>, ...) and writeTag({ Id: ... }) calls in page event code write to the tag by ID number. Before upgrading, identify the pages that contain these calls (with the read-only inventory query provided by the 2WinScada support team) and confirm that the writes are the intended behavior on site.

Recipe permissions

In 2.10, defining recipes and applying them were separated: in new installations, the Operators group only applies recipes, and the Recipe Managers group defines and changes them.

In upgraded installations, group and role assignments do not change: Operators keeps the recipe management role and the Recipe Managers group is not added. If you want to apply separation of duties:

1. On the User Groups screen, create a group for the people who will manage recipes (e.g. Recipe Managers) and give this group the Operate, Monitor, RecipeManagement and RecipeApplier roles.
2. Move the users who will manage recipes to this group.
3. Remove the RecipeManagement role from the Operators group; keep RecipeApplier.

Driver definitions and accounts

Before upgrading, list the following definitions and check them after the upgrade:

• Unsupported tag and device definitions: Modbus String tags or tags with Length > 1, Modbus/Siemens addresses that do not match the data type, Siemens LInt/ULInt/LWord tags and BACnet devices with IPv6 addresses are not deleted, but they stay at Bad quality. See Protocols – Support limits.
• OPC UA channels: After the upgrade, check that each channel's security mode, policy and identity type match an endpoint the server offers; channels that do not match or that are saved with an unsupported identity type (Certificate, IssuedToken) become Bad. Channels saved with the User identity and the None / None security setting connect to the unencrypted endpoint; for channels that connect with a user name and password, select SignAndEncrypt if the server supports it. Also review the priority and deadband settings on the devices. See OPC UA Client.
• Consumption totals: The counter consumption calculation was updated in 2.10; the totals can differ from 2.9 reports. See Counter rule.
• Log and advanced tag Median value: The Median (Mean) calculation was updated in 2.10; Median values written after 2.10 can differ from earlier records. See Log (Archive) Definitions.

Other changes

• Default accounts: The sample accounts created in new installations are not added to upgraded installations; existing accounts are kept. After the upgrade, change the passwords of shared accounts and remove the ones that are not used.
• SystemAdmin protection: 2.10 adds an additional integrity protection for administrator accounts. After the upgrade, check that there is no warning card on the System Information page; if there is a warning, contact your system integrator. See Protecting the administrator account. If SystemAdmin sign-in is rejected even with the correct password, or the SystemAdmin password is forgotten, see If the password is forgotten or sign-in is rejected.
• Database maintenance service: The retired 2WinScada.Db.Maintanence service is stopped during the upgrade and set to Disabled. Its tasks are carried out by the main API service.
• Helper services: External systems access the Notification and RecordDevice services through the main API. Move integrations that use the internal ports of these services to the main API.
• Licenses: Before upgrading, check with the 2WinScada support team that your license is compatible with 2.10. After the upgrade, review the license warnings in the setup log. See License.
• QuestDB logs: Setup limits the size and retention period of the QuestDB logs. The new setting takes effect the next time the QuestDB service restarts.
• QuestDB 2 GB profile: Systems installed with the old 2 GB profile keep this profile; moving them to the 4 GB profile is recommended.

WhatsApp notification

2.10.0 added WhatsApp as an additional channel for alarm notifications. Existing notification definitions keep WhatsApp off; the upgrade does not change their behavior. If WhatsApp will be used:

• Allow outbound HTTPS (TCP 443) to graph.facebook.com from the server where the notification service runs. See Outbound connections.
• Import your new license that includes the WhatsApp right only after the software has been upgraded to 2.10.0. See WhatsApp right.
• Prepare the Meta account, the approved template and the recipient consents. See WhatsApp Settings.

Manual upgrade

Always upgrade systems installed with Setup with Setup

Do not upgrade the database by hand on a system installed with Setup. A manual upgrade is only for systems that were not installed with Setup (that have no installation record); its steps are described in the help installed with the product.

Post-upgrade checks

• The deployment report shows that the upgrade completed (InstallationCompleted is true). The report is in the %ProgramData%\2WinScada\InstallerRuntime\deployment-result.json file.
• In the Windows Services list, the 2WinScada services and the local QuestDB service are running.
• You can sign in to the web interface; the System Information page shows the services as running and there is no warning card.
• The license badge in the footer is not shown, or shows the expected status.
• There is no SystemAdmin integrity warning on the System Information page.
• Kiosk screens are not waiting on the password change screen and have reloaded into the new version by themselves. Other screens that stayed open show the "A new version has been installed" notice; reload the page on those screens.
• After the upgrade to 2.11, someone has signed in once on every kiosk screen. After signing in, the session opens in a new browser tab without a sign-in.
• Live data, alarms, trends and consumption charts show the expected values; notifications and MQTT publishing (if used) work.
• If tags or channels remain at Bad quality, the driver definitions have been corrected according to the reason in the service log; OPC UA channels are connected.
• The %ProgramData%\2WinScada\Logs\setup.log file contains no errors.

Repair

Repair runs with a package of exactly the same version as the installed one. It reinstalls missing or damaged application files and the service configuration. It does not delete SQL Server and QuestDB data; it does not upgrade or downgrade the version. It is not a general tool for changing settings.

Repair is used in the following cases:

• if the application files or the service configuration are damaged,
• if the server's IP address has changed,
• if the internet profile will be turned on or off (see Internet and Network Access),
• to turn on HSTS after moving to a trusted certificate.

When the package of the installed version is run, Repair is selected on the Installation Mode page and Upgrade cannot be used.

• In a repair, the SQL backup directory (required for upgrade and repair; path on SQL host) on the Database and recovery page is also required; Setup first backs up the existing database to this folder.
• If MQTT Publisher is installed, the Recreate a missing MQTT settings file (publishing stays off until the broker is saved on the web) option appears below it on the Components page. The option is off by default; select it only if the MQTT Publisher settings file is missing. If the file exists or is damaged, the repair stops and the file is not overwritten. If the MQTT publisher settings were saved in the web interface earlier, publishing continues with these settings after the repair; if not, enter the broker details on the Settings > MQTT Publisher Settings page.

If the server's IP address has changed

1. Open Setup with the package of the installed version; Repair is selected.
2. On the IIS and SSL page, enter the server's new IP address exactly in the Domain or IP field. The Summary page shows the old and the new address.
3. Complete the repair and check HTTP and HTTPS access with the new address.

• The new IP must be assigned to the server's network adapter.
• If a PFX certificate is used, the new IP must be in the certificate.
• If the self-signed certificate is renewed, update the trust on the clients as well. See Self-signed certificate.
• If a DNS name (host header) different from the old address is registered in IIS, this name is kept.
• SQL Server and QuestDB data and the license are kept.

In a silent repair, the two settings are given together:

2WinScada.Setup.<version>.x64.exe /S /MODE=Repair /DOMAIN_OR_IP=<new IP> /UPDATE_PUBLIC_ADDRESS=1

Uninstalling

To uninstall 2WinScada, use Windows Settings > Apps > Installed apps > 2WinScada > Uninstall, or run the %ProgramData%\2WinScada\InstallerRuntime\Uninstall.exe file as administrator.

• Before confirmation, the uninstaller opens a plan that shows which resources will be removed and which will be kept. Review the plan carefully.
• The database that Setup created and the QuestDB data that it installed are deleted. The SQL Server Express instance that Setup installed is also removed if it holds no other database.
• Resources that Setup did not create, or that are shared or used by other systems, are not touched.
• The license information is kept in every case. See Uninstalling and reinstalling.
• Before uninstalling, back up the data and the configuration, copy the backup off the computer, and close License Manager.
• The result is written to the %ProgramData%\2WinScada\Logs\uninstall-result.json file.
• The uninstaller inspects the resources in SQL Server with the Windows account that runs the uninstall. If SQL Server cannot be reached or rejects this account, the uninstall stops; the message names the stage where it stopped and what the account needs. If the SQL Server Express installed by Setup is used, any local administrator of the computer can run the uninstall.

If the uninstall is interrupted, do not delete the installation record, the logs or the uninstaller; the uninstaller is left in a state where it can be run again.