Deployment Notes 2.7
Introduction
Artifacts can be downloaded from the download page.
Here's an upgrade checklist to assist: Hopp.2.7.Upgrade.xlsx
We are always doing our utmost to ensure the quality of Hopp.
To the extent that our customers have custom implementations using external extension APIs or write queries against the internal databases of Hopp, we do expect our customers to perform rigorous testing of their own implementations.
Internal Database Objects:
Our internal staging and migration databases are designed to support our data processing workflows and are not intended to function as stable, external APIs.
While we aim to maintain consistency across releases, we do not guarantee backward compatibility or structural stability of these databases.
Clients who choose to access these databases directly are responsible for validating that their integrations continue to function as expected after any updates or releases.
Extension APIs:
Our API for extensions is provided to enable advanced integrations and custom functionality. However, this API may evolve over time, and changes may occur between releases.
We advise all customers using the Extension API to validate their custom extensions and integrations against each new version of the platform. Proper testing will help identify and resolve any issues arising from API modifications.
The following sections outline the deployment actions for this release.
Check external sign-in settings before upgrading the Portal
Applies to installations with Authentication IdentityProvider set to External.
- Roles that are not in RoleMapping no longer count once RoleMapping has an entry. If you use RoleMapping and your identity provider also sends roles or groups named exactly like Portal roles (administrator, operator, manager, team, external), those are now ignored. Add them to RoleMapping, or users who relied on them are refused at sign-in. Without any RoleMapping entry, role names from the provider are still used as Portal roles, matched exactly.
- The role claim is read from roles. With UserManagement External, the Portal reads roles from the roles claim only. If your provider sends them in a claim called role (singular), users are refused at sign-in with a message that no role was found; set RoleClaimType to role.
- Unverified email addresses are refused. The Portal identifies users by their email address. If the provider reports that a user's address is not verified, sign-in is refused. Providers that do not report verification, such as Microsoft Entra ID, are not affected; make sure users cannot change their own email address there. The check applies only when EmailClaimType is email.
No configuration change is needed if you do not use RoleMapping, or map every role you use, and your provider sends roles in the roles claim.
Database Migration
-
Bring the installation to 2.6.16 first: install the 2.6.16 release, then bring every database to 2.6.16. 2.7 upgrades from 2.6.16 only. A database older than 2.6 first takes the database steps in the 2.6 deployment notes; then every database takes the database steps of each 2.6 hotfix it does not have yet, in order, up to and including 2.6.16. The 2.6.16 notes alone do not bring an older database to 2.6.16.
-
Upgrade the databases to 2.7 with the 2.7
dbscripts.zipdownload, as described in Upgrading the Databases, working through its sections in order: Before You Start, Upgrade an Installation (including checking the result), Databases the Command Does Not Find and The Portal, Item Manager and Test Databases. If your DBA runs the SQL rather than the upgrade command, follow If Your DBA Runs the SQL in place of the upgrade command (step 2 of Upgrade an Installation), then continue with the rest of these sections.Pass as
-RuntimeAgentUserthe account the Runtime Agent service logs on as (on a 2.6 Execution Server, the Log On account shown for the service in Services; if it shows a built-in account such as Local Service, choose a Windows account for the Agent now, since the Agent installer asks for one), and as-PortalUserthe Windows account the 2.7 Portal service will run as. A 2.6 Portal ran under its IIS application pool, so choose that account now: the Portal installer asks for the same one. The two may be one shared account. Pass your databases' existing names as well (-MasterDatabase,-RepositoryDb,-UtilityDb); an upgrade keeps them.The database scripts grant only on the databases they manage, so after the database step make the other grants for any account that is new to them (see Granting db_owner by hand): the Portal account needs
db_owneron the Portal database, and on the Item Manager and Planning databases if you use those modules. On every track's Staging database, the Runtime Agent account needsdb_ownerand a separate Portal accountdb_datareader(an account shared by both needsdb_owner). Both also need the folder rights listed under Accounts.With SQL Server authentication this differs; see Accounts.
Please back up all databases before upgrading.
Redeploy Portal
In 2.6 the Portal runs in IIS and reads its settings from appsettings.json. From 2.7 it runs as the
Hopp Portal Windows service, is installed with Hopp.Portal.exe, and is configured through its configuration
wizard. The installer does not read the 2.6 settings, so upgrading the Portal from 2.6 is a first install of the
2.7 Portal, followed by the wizard. Your users, projects and client applications are in the Portal database and are
kept. Do this before you reinstall the Runtime Agents: each Agent needs a client application from step 7.
Have these ready: the 2.6 Portal's appsettings.json, the HTTPS certificate the IIS site uses, and a Windows
account for the Portal service (with its password, unless it is a Managed Service Account).
-
Use the Portal service account from the database step. The 2.6 Portal ran as its IIS application pool's identity; the 2.7 Portal runs as the Windows account you passed as
-PortalUserin the database step above, which granted itdb_owneron the databasesupdate-installation.ps1upgrades. It also needsdb_owneronMigFx_Portal, and onMigFx_ItemMgrandMigFx_Planningif you use those modules, anddb_datareaderon every track's Staging database (db_ownerif it is also the Runtime Agent's account): the database scripts do not grant these, so grant them yourself (or ask your DBA; see Granting db_owner by hand). The account also needs full access to theFileStoragefolder, and read access to the custom theme folder, the custom extensions folder and the HTTPS certificate's private key. Accounts lists these rights, and how they differ with SQL Server authentication. -
Keep a copy of the 2.6 settings. Copy the 2.6 Portal's
appsettings.jsonsomewhere safe, together with theappsettings.jsonof the Item Manager and Planning modules in itsExtensionsfolder if they have their own. You read values from them in step 6. ItsFileStoragepath and custom theme folder may be relative to the IIS site's folder: note them as full paths. -
Move custom Portal extensions, if you have any (extensions developed outside Hopp). They now use a fixed folder layout: move each one into its own folder with separate
ClientandServersubfolders,<root folder>\<extension name>\Clientand<root folder>\<extension name>\Server. Place the root folder outside the Portal install folder so it survives reinstalls and upgrades. The shipped modules (Migration, Item Manager, Planning) are not affected. -
Free the Portal's address. Stop the Portal's IIS site, or remove it, so the address and port it used are free for the Portal service. If other IIS sites share the same HTTPS binding, the port stays in use until those move too. If the Portal ran in an IIS sub-folder, see the HTTPS & reverse proxy row in step 6 before you remove anything. The Portal service now receives the traffic itself, and the installer adds no firewall rule: if the Master Server's firewall only allowed IIS, allow inbound connections on the Portal URL's port to the Portal service, or browsers and Runtime Agents on other servers cannot reach it.
-
Install the Portal with
Hopp.Portal.exefrom the download page, as described in Install the Portal. Because no 2.7 Portal is installed yet, the installer asks for everything a first install needs:- The service account from step 1.
- A bootstrap token of your choice. Keep it: the wizard asks for it in the next step.
- The optional modules: tick Item Manager and Test (the Planning Module; the 2.7.0 installer's label) if you use them.
-
Walk the configuration wizard at
http://localhost:5000on the Master Server, as described in Walk the Configuration Wizard, with the values you kept:Wizard page Value from 2.6 Connectivity ConnectionStrings:MigFxPortalandConnectionStrings:MigFxMigration(theMigFx_PortalandMigFx_Masterdatabases), andAuthentication:PortalUrl. The Portal hands theMigFx_Masterconnection string unchanged to every Runtime Agent, so it must name the SQL Server the way the Execution Servers reach it: a 2.6 value such asServer=.orlocalhostworked for IIS on the database server but fails on every Agent on another server.Storage FileStorage, andCustomThemeConfiguration:SourcePathif you white-label the Portal, as full paths.Authentication Authentication:IdentityProvider, and for an external provider theAuthentication:OpenIdConnectsettings (see Setting up External Authentication). Leave the seed administrator empty: your users and administrators are already in the database.Extensions The root folder of your custom extensions from step 3, if any. HTTPS & reverse proxy If the Portal ran in an IIS sub-folder: the Portal serves a sub-path only behind a reverse proxy that routes that path to it, for instance the IIS site itself with Application Request Routing (keep that site in that case). Choose Yes, reverse proxy, enter the internal HTTP port the Portal listens on, the proxy's IP address under Known proxies (required), and the path as Sub-path, and end the Portal URL with that path; the certificate stays on the proxy. Otherwise, the certificate the IIS site used (from the Windows certificate store or a PFX file). Item Manager ConnectionStrings:MigFxItemMgr, if you use the module.Test (Planning Module) ConnectionStrings:MigFxPlanning, if you use the module.Click Apply on the Review page, restart the
Hopp Portalservice, and sign in at the Portal URL. Settings the wizard does not cover keep their defaults: if 2.6 changed one, for instanceAttachmentConfiguration:MaximumSizeInMegaBytes, set it again inappsettings.portal.json, and if you raised IIS's upload limit for the 2.6 Portal above 100 MB, set the same on the Request limits page. -
Check the client applications. In 2.6 the Portal copied every application listed in
Authentication:ClientCredentialsAppsinto its database, and 2.7 keeps them with their secrets: open Configuration > System > Client Applications and check they are listed. The old list inappsettings.jsonis no longer read. Rotate a secret there only if you need a new one. Create a new client application for each program that had none, in particular one for each Execution Server's Runtime Agent: the 2.6 Agent did not use one. The Portal shows a new secret only once, so copy it. -
Set up email. The mail server from
NotificationConfiguration:EmailSettingsis now entered in the Portal under Configuration > System > Notifications, on the SMTP Relay tab, and is not carried over. The Portal starts with the default notification templates: if you had changed any, make the same changes on the same page. See Setting up Notification and Email.
If the 2.6 appsettings.json set your own SigningCertificate, set it again in appsettings.portal.json in its 2.7
form, which names a Source (store reads only LocalMachine\My); see
Advanced: Manual configuration.
From 2.7 on, a Portal upgrade keeps its configuration, bootstrap token and modules: later releases need the installer and the service account's password (none for a Managed Service Account). To upgrade from 2.6 to a later 2.7 release, follow these steps rather than that release's.
Ask users to refresh the Portal once after upgrading
After upgrading from 2.6, ask users to hard-refresh the Portal once (Ctrl+F5, or Ctrl+Shift+R), including any Portal tab left open during the upgrade. Until they do, a browser may keep showing the 2.6 page, which stops at "Portal is loading".
Upload the new Runtime Libraries to the Portal
- Download
Hopp.Runtime.Libraries.zipfrom the download page - Upload it to the Portal (Configuration → Operations → Runtime → Runtime Libraries)
- Set the new Runtime Libraries version active
Execution Servers
Reinstall the Runtime Agent
In 2.6 the Agent reads its settings from MigFx.Agent.dll.config. From 2.7 it is installed with
Hopp.Runtime.Agent.exe and fetches its configuration, including the MigFx_Master connection string, from the
Portal. The 2.7 installer replaces the 2.6 Agent on its own, so do not uninstall it first, but it carries none of the
2.6 settings over: only the install folder is filled in. Do this on each Execution Server, after the Portal is
upgraded.
Have these ready for each Execution Server: the Portal URL, and the Client ID and secret of the Agent's client application (see the Portal step above: create one for each Agent, unless you mean to share an existing one).
- Note the 2.6 settings. The 2.7 Agent runs as the account you passed as
-RuntimeAgentUserin the database step above: the 2.6 service's Log On account, which the Services snap-in shows (note it now, since the installer removes the 2.6 service). If it shows a built-in account such as Local Service (the 2.6 installer's default), use the Windows account you passed instead: the 2.7 installer needs aDOMAIN\Useraccount and its password, except for a Managed Service Account (a name ending in$). Also copyMigFx.Agent.dll.configfrom the Agent's install folder (normallyC:\Program Files\HoppTech\migFx\Agent) for itsStartupandShutdownvalues. ARuntimePathvalue there (a local Runtime Libraries folder) has no counterpart in the installer: the 2.7 Agent loads the Runtime Libraries uploaded through the Portal. - Run
Hopp.Runtime.Agent.exefrom the download page, as described in Install the Runtime Agent. - Fill in every page:
- Service account: the account you noted in step 1; see Service account for what it needs.
- Portal connection: the Portal URL, and the Client ID and client secret of this Agent's client application. The secret is required: there is no stored secret to keep yet.
- Startup and shutdown commands: the
StartupandShutdownvalues from the 2.6MigFx.Agent.dll.config, if it set any. Each is a full path to an executable or script, without arguments; the Agent skips a value it cannot find as a file, as 2.6 did. Leave the fields empty otherwise.
- On the final screen, leave Start the Hopp Runtime Agent service now ticked and click Finish. The Agent contacts
the Portal and fetches its configuration.
MigFx.Agent.dll.configis no longer used.
From 2.7 on, an Agent upgrade keeps its Portal URL, Client ID, secret and commands, so later releases need only the installer and the service account's password (none for a Managed Service Account). To upgrade from 2.6 to a later 2.7 release, follow these steps rather than that release's.
Reinstall the Runtime Connectors and the Hopp Utility
If installed, reinstall the 2.7 Runtime Connectors (the installers upgrade the existing ones):
- Hopp Sql Server Runtime Connector (
Hopp.Connectors.SqlServer.msi) - Hopp Oracle Runtime Connectors (
Hopp.Connectors.Oracle.msi) - Hopp DB2 Runtime Connectors (
Hopp.Connectors.Db2.msi)
If you use the Hopp Utility for Translation Valueset export and import, reinstall it (Hopp.Utility.msi). It needs the .NET Runtime
10 and the ASP.NET Core Runtime 10 (x64). On an Execution Server the Runtime Agent installer installs only the .NET Runtime, so
install the ASP.NET Core Runtime there yourself.
Workstations
Reinstall Hopp Studio
- Download the Hopp Studio installer (
Hopp.Studio.exe) from the download page - Install the new version of Hopp Studio. The installer installs any missing prerequisites first; see Setting up a Workstation.
Reinstall the DataServices extensions
Reinstall any DataServices extensions (if installed):
Hopp.DataServices.SqlServer.msiHopp.DataServices.DB2.msiHopp.DataServices.Oracle.msi
Visual Studio and the Visual Studio Extension
Hopp 2.7 engine projects target .NET 10, which Visual Studio 2022 cannot build. Install Visual Studio 2026 (version 18.0 or later) with the .NET desktop development workload; it also installs the .NET 10 SDK.
- Install Visual Studio 2026 (version 18.0 or later) with the .NET desktop development workload, if it is not installed yet
- In each Visual Studio that has the
Hopp Migrationextension, open Extensions → Manage Extensions and mark it for un-install - Close Visual Studio. The Microsoft Visual Studio extension installer will launch to uninstall the previous version. Follow the guidance in the installer
- Install the new Hopp Visual Studio extension into Visual Studio 2026 (double-click
Hopp.VsExtension.2022.vsix) - Follow the guidance in the installer
- When installed, open Visual Studio and check the options in Tools → Options → Hopp; see Visual Studio Extension Installation
Update Engine Generator
-
If using NuGet
- Update the Hopp generator tool (it needs the .NET 10 SDK, which Visual Studio 2026 installs):
dotnet tool update Hopp.Tools.EngineGenerator --global
- Update the Hopp generator tool (it needs the .NET 10 SDK, which Visual Studio 2026 installs):
-
If using local libraries
- Reinstall
Hopp.EngineFramework.msifrom the download page
- Reinstall
Update Visual Studio Engine Projects
The project changes below only need to be done by the administrator and committed to version control
Hopp 2.7 engine projects target .NET 10. Engine projects created with 2.6 (.NET 8) still run in the 2.7 Runtime, but .NET 8 support ends in November 2026, so we recommend retargeting them.
-
In all *.SourceEngineGenerated.csproj, *.SourceEngineCustom.csproj and *.TargetEngine.csproj files (not in custom library projects implementing Hopp extensions: Hopp Studio loads those, so they keep their target framework)
- Change the target framework to .NET 10
<TargetFramework>net10.0</TargetFramework> - Update any Microsoft.EntityFrameworkCore.SqlServer package reference to 10.0.13 (the *.SourceEngineGenerated.csproj
and *.TargetEngine.csproj templates have one)
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="10.0.13" />
- Change the target framework to .NET 10
-
In all *.SourceEngineGenerated.csproj files (required even if you keep .NET 8)
- Update the Microsoft.Data.SqlClient package reference to 6.1.7
<PackageReference Include="Microsoft.Data.SqlClient" Version="6.1.7" />
- Update the Microsoft.Data.SqlClient package reference to 6.1.7
-
In all custom library projects implementing Hopp extensions
- Update any Hopp.* NuGet package references to 2.7.*
-
If using NuGet
- Update Hopp.SourceEngine package reference to 2.7.* in all *.SourceEngineGenerated.csproj files
<PackageReference Include="Hopp.SourceEngine" Version="2.7.*"/> - Update Hopp.TargetEngine package reference to 2.7.* in all *.TargetEngine.csproj files
<PackageReference Include="Hopp.TargetEngine" Version="2.7.*"/>
- Update Hopp.SourceEngine package reference to 2.7.* in all *.SourceEngineGenerated.csproj files
If using local libraries, reinstall Hopp.Libraries.msi from the download page on every workstation.
PowerShell Automation
Reinstall the PowerShell Automation module (Hopp.Automation) on relevant workstations and servers: download the 2.7
version from the download page and replace the module folder, as described in
PowerShell Installation.
The module has changed in 2.7.
This is optional and only if the PowerShell Automation scripts are used