Upgrades

This document covers how to roll forward (and back) between IdentityMesh releases without losing data or breaking running connectors.

What changes between releases

Pre-upgrade checklist

1. Take a SQL backup. See backup-and-restore.md. This is the only thing that lets you roll back if the upgrade goes sideways.
2. Snapshot the Connectors\ folder on every host (service + each relay) so you can roll a connector DLL back independently of the service version.
3. Note the running version by checking the file properties on the .exe files under %ProgramFiles%\IdentityMesh\engine and %ProgramFiles%\IdentityMesh\api, or the Admin UI’s About page.
4. Stop active sync runs. Either pause schedules in the Admin UI or wait for in-progress runs to complete. Any sync running when the service is stopped is marked Interrupted; the next service start reconciles the bookkeeping automatically.

Upgrade procedure

Same-version connector upgrade only

Drop replacement DLLs into the Connectors\ folder and restart the service (or relay agent). Connectors are loaded on startup.

Service / API version upgrade

1. Pre-upgrade checklist above.
2. Stop services:

   sc stop IdentityMeshEngine
   sc stop IdentityMeshAdmin

3. Run the new MSI. It upgrades binaries in-place and preserves appsettings.json — file-copy rules are documented in installer.md.
4. Database changes are applied automatically by the installer’s database step, which runs Deploy_All.sql against the configured database. The script only adds what is missing, so running it on an already-current database changes nothing. You do not need to run any SQL yourself. If your database is updated outside the installer, see Running the database step yourself.
5. Start services:

   sc start IdentityMeshAdmin
   sc start IdentityMeshEngine

6. Smoke test: dashboard loads, license shows valid, run history queryable, kick off one sync.

Running the database step yourself

Most installations never need this section. The MSI runs the database step on every install and upgrade and logs it to %TEMP%\IdentityMesh.DbSetup.log (a copy lands in the installed sql folder as dbsetup.log).

Run the step yourself only when the installer did not: your database team applies IdentityMesh database changes separately, or the database step failed during an upgrade. Always run the whole Deploy_All.sql. Do not pick individual scripts out of the folder; the master script runs every script in the right order and skips anything that already exists.

1. Stop both services:

   sc stop IdentityMeshEngine
   sc stop IdentityMeshAdmin

2. On the server where IdentityMesh is installed, open a command prompt as an account that can create tables in the IdentityMesh database. sqlcmd must be on the path (it ships with SQL Server Management Studio and with the SQL Server command-line tools).
3. Change to the installed sql folder and run the master script. The script must be started from that folder:

   cd "C:\Program Files\IdentityMesh\sql"
   sqlcmd -S <server\instance> -d IdentityMesh -E -i Deploy_All.sql

   Replace <server\instance> with your SQL Server, and IdentityMesh with your database name if you changed it during install. Use -U <user> -P <password> instead of -E for SQL authentication. The script prints each phase as it runs.
4. Start the services:

   sc start IdentityMeshAdmin
   sc start IdentityMeshEngine

Signs the step was skipped. After an upgrade, a page that depends on a new table shows its defaults and reports an error when you save, or the Sync Engine logs a startup error and runs no sync cycle. Run the steps above and restart the services. Each feature runbook names the symptom to look for.

Relay agent upgrade

Each relay agent is independently upgradeable. Order:

1. Upgrade the central API/service first (or at least confirm the API is at a version that still accepts the relay’s old protocol — see “Version skew” below).
2. For each relay host: stop the service, install the new MSI, start the service. The agent re-registers with the API on next connection.

Behaviour changes in this release

Most releases are drop-in. This one changes what several existing settings do, so read this section before you run the MSI and again before you re-enable schedules. Roll them out on a staging copy first if you can.

Act before the upgrade

• Upgrade relay agents first (or together). The Active Directory connector is now configured as a per-forest object-type list. The portal still writes the legacy ObjectType, Filter and AttributesToLoad keys, so an old relay agent keeps importing, but per-type export defaults (create enabled, default container, delete mode) need the new connector build on the agent. Ship the relay agent MSI with, or before, the engine.

• Know which rules can delete. Run the query in self-service-groups.md for projection rules with DeleteIfUnlinked = 1 and decide which of them should really remove objects from a target. The flag has been inert until now.

• Upgrade the Admin API and the Sync Engine together. Both hosts now read the secret provider from the database. An old engine beside a new API keeps reading Secrets:Provider from its own appsettings.json and will disagree with the database the moment the Secrets page changes anything. The relay agents are unaffected.

• Adopting a vault? Edit each host’s appsettings.json first. The Secrets page can only point a host at a vault endpoint that host’s own file sanctions: the same URI under Secrets:KeyVault:VaultUri or Secrets:HashiCorpVault:Address, or an entry in Secrets:AllowedEndpoints. Add it before you press Test. See secrets-keyvault.md and secrets-vault.md.

Act after the upgrade

• Grant the new ms.write permission where you need it. The database step seeds it to the Admin and Operator roles. It gates the new per-object Isolate, Release and Disconnect actions on connector objects (see isolate-disconnect.md). If you manage role permissions by hand, add it to any custom role that should intervene on a single object.

• Expect the management-space wipe to ask twice. Delete Management Space Data now refuses while the connector has isolated rows or open export holds until you type the connector’s name. Open holds survive a forced wipe and must be released separately.

• Re-tick DeleteIfUnlinked deliberately. The flag now exports a real Delete when a rule’s precondition stops holding for an object that exists in the target. The migration clears it on every existing operator rule (never the seeded templates), records the list under the system setting Export:DeleteIfUnlinkedReset, and the engine logs a startup warning for each rule still flagged. Re-enable only the rules you want, and check the Active Directory connector’s DeleteMode before you do. See projection-templates.md.

• Open every Active Directory connector once. Connectors created before this release without an AttributesToLoad key should be opened in the connector form and their per-type attribute cards checked before the next full import.

• AD DeleteMode = disable is now strictly non-destructive. It disables user-class objects and never removes anything; a group or contact under it fails its export loudly instead of being deleted. A new disable-or-delete mode disables what it can and deletes the rest (self-service groups need it). Any unrecognised value is read as disable.

• Run one full Active Directory import. Every AD user and group now carries the default attribute netbiosDomain (the domain’s NetBIOS name, read from the forest’s Partitions container). The upgrade seeds the schema row and an inbound netbiosDomain → netbiosDomain flow on each Active Directory connector; the attribute fills on the next full import. The Assign Role picker uses it to compose DOMAIN\username. See authentication.md.

• Run one full Workday import. Reference attributes (country, jobProfile, location, workerType, …) now import as readable IDs instead of Workday WIDs, and manager is always the manager’s WID. On tenants that send descriptors, payCurrency and compensationGrade now import as the descriptor text (“US Dollar”) rather than the ID. Flow rules or Composer criteria that matched a WID literal need updating. The connector form gains Discover attributes and xml: custom-field lines; the relay agent needs this release’s Workday plugin for Discover to answer; a Direct connector’s Discover runs on the engine instance instead, which ships with the service. See connector-workday.md.

• Test Connection and Discover attributes on Direct connectors. The sync engine registers on the relay hub as an agent. The installer’s database step adds the column it needs (IM_EngineInstances.ApiKeyHash); without that column the service’s heartbeat fails and no sync cycle runs, so a database updated outside the installer must have the database step run before the service starts. No operator step on the relay. See relay-agent.md.

• Vault accounts in no scope are refused by default. An account that no vault scope covers can no longer be requested by anyone. Add such accounts to a scope, or set Vault:UnscopedAccountsOpen = true to restore the previous open behaviour.

• New tables, columns and permission seeds. This release adds the IM_SecretsState, IM_ConnectorSourceCounts and IM_AppearanceSettings tables, the PrincipalType column on IM_UserRoles, the ApiKeyHash column on IM_EngineInstances, and permission seeds for Secrets, Mesh and Groups. The installer’s database step applies all of them; nothing has to be run by hand. A database updated outside the installer needs the database step run before the services start; see Running the database step yourself.

• mesh.write is seeded off for every role. The mesh-object set password route is gated on it and is unavailable, Admin included, until you grant it. Grant it in the seed, not only in the Roles page (see the next item).

• Permission seeds re-apply at every upgrade. The installer’s database step restores the shipped value of every seeded permission on the built-in roles, so a grant or revoke made only in the Roles page is reverted by the next upgrade. Keep deliberate changes to seeded permissions in a custom role, or re-apply them after each upgrade.

Expect to see

• Honest management-space counts. A connector’s MS Objects badge now reads live rows first, with the rows a confirming import marked deleted and any isolated rows beside them (“2359, 1205 deleted, 3 isolated”); before, it counted every row including the deleted ones, so it could sit far above what the last import read. The dashboard’s management-space total and the Operations Drift column count live rows the same way, so a connector whose scope once shrank stops showing permanent drift.

• A Held status in the export queue and new columns on the Mesh Objects and Operations pages. Held items belong to isolated or disconnected connector objects and return to Pending when released. The Connector Objects tab shows a State column, and Operations shows Isolated / Held counts whenever any connector has them. See isolate-disconnect.md.

• A new IdentityMesh log in Event Viewer. Warnings and errors now go to Applications and Services Logs → IdentityMesh, one Source per component. Events stop arriving in Application under the old source names (IdentityMesh, IdentityMesh.Admin.Api, IdentityMeshRelay). Old events stay where they are. Nothing to do by hand. See event-log.md. If a SIEM forwards the Application log with a source filter, repoint it at the IdentityMesh log; see siem-integration.md.

• A one-off spike in the import “Updated” counter. An object now counts as Updated when its Management Space row changed at all, even when nothing reached the mesh. The first import after the upgrade re-stamps rows and reports a large Updated count once; subsequent runs settle.

• Two connectors of the same type no longer share credentials. The export engine re-initialises the connector per queue item, so a connector can no longer export under another connector’s credentials. If a target was silently accepting writes from the wrong service account, those exports will now fail with that account’s real permissions.

• Export failures naming a phase. A new setting, IdentityMesh:Export:PerExportTimeoutSeconds (default 120, 0 disables), bounds connector initialisation plus export for one queue item. A timed-out item fails with a message saying which phase ran out. Raise it for slow targets.

• A 400 when saving a connector whose config is not a JSON object. The API now refuses such a config and names the faulty path; the portal validates the raw JSON box before Save.

• Workday in both installers. The Workday connector now ships as a default connector in the Sync Engine MSI and the Relay Agent MSI, so there is no longer a separate DLL to copy for relay-routed Workday connectors.

• A Secrets tab under Settings. It shows which provider each host is running and drives test, migrate, switch and purge. Nothing changes until you use it: the first start seeds the database from each host’s Secrets:Provider.

• Key Vault app credential on the Secrets page. Tenant ID, Application (client) ID and client secret can be entered once; every host receives the secret through the database, encrypted to its own key. Hosts mint that key on their first poll after the upgrade, so give them a minute before saving the secret. See secrets-keyvault.md.

• A held run instead of a silent service-account run. When the secret store cannot be read (vault outage, a provider the host cannot build), the engine now holds the run and names the error. Previously such a connector ran with no credentials, as the service account.

• Reports-to conditions in MeshComposer (direct, two levels, whole org), and a periodic full re-evaluation of rules that use them. See composer.md.

• Assign a role to a directory group on Settings → User Role Assignments. See authentication.md.

• An Appearance tab under Settings. Product name, logo, colours and navigation labels for the whole organization. Nothing changes until someone saves a theme. See appearance.md.

Version skew

The relay protocol is conservative — older relays against newer APIs generally work, and newer relays against older APIs generally work, as long as no hub method has been removed or changed in incompatible ways.

For deployments with many relays that can’t be upgraded simultaneously: a staged rollout (one canary relay first) catches incompatibilities cheaply during the upgrade window.

Connector DLL versioning

Connectors are loaded by name from the Connectors\ folder. IM_ConnectorSchedules references each connector by type name.

• Adding a new connector: drop the DLL in Connectors\, restart. The new type registers as soon as the agent re-registers.
• Updating an existing connector: replace the DLL in place; type names must remain stable. Restart picks up the new code.
• Renaming a connector type: do not. It breaks every existing schedule that referenced the old name. If unavoidable, the release notes will call out the SQL migration that updates the affected rows.

Rollback

Binary rollback

1. Stop services.
2. Run the previous version’s MSI:

   msiexec /i previous.msi REINSTALL=ALL REINSTALLMODE=vomus

3. Roll back the schema if the upgrade applied any. The release notes for each version document whether down-migration is supported and what data, if any, is lost in the down direction. Test rollbacks in a staging copy of production data first.
4. Start services.

Schema-only rollback (binary stays at new version)

Don’t. Migrations are designed to be applied in order. A binary that expects a column the schema doesn’t have will throw at runtime. If the new binary version is broken in a way that requires reverting just the schema, the right move is to roll back the binary too.

Data-only rollback (revert to backup)

See backup-and-restore.md.

Upgrade frequency considerations

• Schema migrations are additive whenever possible (new nullable columns, new tables) so the previous binary version still runs against the new schema. This makes rolling deployments and partial rollback safe.
• IdentityMesh does not rename columns or tables. A rename would make every upgrade pay a migration cost, so releases add new columns and deprecate old ones instead.

Related

• installer.md — MSI build and install procedure.
• backup-and-restore.md — what to back up before upgrading.
• secrets-and-dpapi.md — secret re-provisioning if the upgrade involves a host migration.