Upgrade Overview

On this page

An upgrade includes updating the database and installing the new components. The Database Management wizard runs scripts to update the database to its own version. When they connect, the components below compare the database version with their own and refuse the connection if the versions differ:

Component On a version mismatch
Settings App, Automation Server Manager Shows an error dialog naming both versions; the connection is not opened
Import Wizard Shows an error dialog; on a command-line run, stops without one
Automation Server service Logs a fatal entry once, closes the connection, and retries on its connect interval; it does not exit
Command-line tools Raises an error before doing any work
Web App, Self Service Portal, API module Raises an error; there is no dialog

Because each component checks the version on its own and none of them checks another, the product does not enforce an order in which you upgrade the components. When the One-Click Installer is set to start the Database Management wizard, it starts the wizard it has just installed, so on that route the new components are in place before the database is upgraded.

In the Settings App, the Automation Server Manager, the Import Wizard, the Web App, the Self Service Portal, and the API module, the error text tells you which side is out of date:

  • A message that begins with "Your database needs to be updated to be compatible with this version of Alloy Navigator." means that the database's version is lower than the component's.
  • A message that begins with "Your Alloy Navigator installation needs to be updated for compatibility with this database." means that the database's version is higher: the component is out of date, not the database.
  • While a database is marked as being upgraded, the check reports the upgrade error the wizard recorded, such as "The database '...' has been corrupted due to an upgrade failure.", or, when no error was recorded, a message that begins with "The database you are connecting to is under upgrade."

The same check also refuses a database that is not an Alloy Navigator database, a database that is still marked as being created, and a database that stores no version.

An upgrade updates the database and its configuration.

Supported paths

The Database Management wizard offers these paths against an existing database:

Path Wizard choice Source database Lowest source version Target
In-place upgrade Production Upgrade Alloy Navigator 8.0.0 The same database
Migration (initial) Create Pilot Database Alloy Navigator 6.0 A new database created by the wizard
Migration (incremental) Update Pilot Data or Switch to Production Alloy Navigator 6.0 An existing pilot database
Migration from Alloy Navigator Express The same three pilot steps, off Azure SQL Alloy Navigator Express 6.2.0 Express A new Alloy Navigator database

The wizard's Upgrade Scenario page offers Production Upgrade (preselected), described as "Upgrade your database to the latest version and go live immediately.", and Pilot Upgrade, described as "Test-drive the new version in a pilot environment and switch to production when ready." The three pilot steps are the choices of the pilot page. Off Azure SQL, when the in-place upgrade does not accept the source database, the pilot page appears in place of the Upgrade Scenario page for a source that the migration paths accept. The pilot page is titled Pilot Testing when the source is already at the wizard's version. The paths differ in these ways:

  • The in-place upgrade refuses a source below 8.0.0 with an invalid-version error, so a database at version 7 or earlier reaches the current version only through the migration paths.
  • The migration paths refuse a source below 6.0 with an invalid-version error.
  • The in-place upgrade refuses a database that takes part in SQL Server replication. Remove the database from its replication topology first. The migration paths run no such check.
  • Every pilot step backs up the production database to a file named on its Backup Location page. The file is created on the computer where SQL Server runs, and this backup cannot be turned off.
  • Create Pilot Database leaves the source database as it was and creates the pilot on the SQL Server instance that hosts the source database. It turns off every job of the pilot except the business rules (Trigger On Condition jobs); the jobs keep production's other settings, and the wizard turns none of them on again. A pilot created from an Alloy Navigator database keeps the license restored with the production backup. If a database of the name you enter on the Target Database page already exists, the wizard asks "The database '<name>' already exists. Delete the database?" and deletes it only when you click Yes.
  • Only Create Pilot Database from an Alloy Navigator database shows the Workflow Upgrade page, where Keep Existing Workflow is preselected and you can choose Install Default Workflow instead. For what that choice does, see Upgrade Considerations.
  • An in-place upgrade keeps your existing workflow and applies selected updates. It does not install the complete Default Workflow of the new version. Some updates can replace customized components; see Upgrade Considerations. To replace your workflow with the complete Default Workflow, prepare a pilot with Install Default Workflow, then move the result to production by switching the pilot to production or exporting and importing its workflow. Install Default Workflow replaces configuration in the pilot, including customizations. See How to Update the Default Workflow.
  • Only Create Pilot Database from an Alloy Navigator database shows the New Permissions page, and only when permissions were introduced after the source version. The page lists Existing Roles: against New Permissions:, and there you grant each new permission to roles with its check box. Five permissions are never on that list, and the wizard neither grants nor denies them. The in-place upgrade and the other pilot steps never show this page.
  • Only the in-place upgrade shows the Backward-Incompatible Changes page; no pilot step shows it. For what the page lists, see Upgrade Considerations.
  • Update Pilot Data and Switch to Production are refused unless the pilot database is already at the wizard's version. Both first back up the pilot database while Enable backup on the Target Database page stays selected; the check box is preselected, and you can clear it. Both then copy the production data onto the pilot again and put the pilot's own configuration back, including its jobs, so configuration changed in production after the pilot was created is not carried over, and Update Pilot Data can be repeated. The Workflow Log entries that come with the production data are deleted. Copying the data disconnects everyone who is working in the pilot.
  • Only Switch to Production with the Switch and Flip option (preselected) renames the source database and gives the pilot its name. It disconnects open sessions of the source database and rolls back their open transactions rather than waiting for them, renames it with a _SAVE suffix (_SAVE_2, _SAVE_3, and so on while the name is taken), creates a Database Access Key for the renamed pilot, and takes the source database offline. With Switch, both databases stay online under their own names.
  • Every pilot step except Switch to Production with Switch and Flip pauses sending from the pilot's notification queue; Switch and Flip turns sending back on. While sending is paused, notifications are queued but not sent until you resume sending, and the test notifications that accumulated in the paused queue can be deleted. You do both in the Settings App; see Notification Queue.
  • With Switch and Flip, a web instance's stored connection reaches the new database without change. With Switch, every web instance still addresses the previous database; re-point an instance with Configure > Database on its context menu in the Web Configuration tool; when that command applies its settings, it restarts the web application. After either option, the link macros Web Portal Link, Self Service Portal Link, and API Link hold what the pilot database held, and reconfiguring an existing instance does not correct a macro that already has a value. Correct them in the Links group of the Settings App.
  • After a switchover, the wizard does not remove the previous database, the backup files it wrote, or any SQL Server login. Removing them is up to you.
  • On Azure SQL, the wizard shows the Upgrade Scenario page for any source database, an Alloy Navigator Express database included. There it hides Pilot Upgrade, selects Production Upgrade, and does not offer the pilot steps.

On the pilot route, production stays in use while you test: Create Pilot Database leaves the production database as it was, and the pilot runs with its jobs off, except the business rules, and its notification queue paused. The production system is taken down only when the switchover begins: stop the production Automation Server and Inventory Server, force the users to log off with the User Sessions manager of the Settings App, and stop the Automation Server and Inventory Server that ran against the pilot. These are your steps; the wizard performs none of them, and the product enforces no order.

The pilot upgrade runs in four stages:

  1. Install: install the Alloy Navigator server components, create the pilot database with Create Pilot Database, and install and configure the web applications.
  2. Test: start the Automation Server and Inventory Server for the pilot, test the pilot database, and, optionally, run Update Pilot Data.
  3. Switch to production: take the production system down as described above. Upgrade the Alloy Navigator server components, run Switch to Production, and upgrade the web applications. Reconfigure the web applications, point Alloy Discovery Synchronization at the production Alloy Discovery database and the Mail Connector at the support mailbox, delete the test notifications, resume the notification queue (after Switch and Flip, sending is already on), start the production Automation Server and Inventory Server, and upgrade the client components.
  4. Additional steps: optionally, update the archive databases, uninstall the previous version, and remove the SQL Server accounts you no longer need. An unattended run of the Alloy Navigator setup program uninstalls an installed Alloy Navigator 6 or 7 by itself unless OLD_PRODUCT=Keep is also passed; see Unattended Installation.

For the steps of the pilot route, see Upgrade Through a Pilot Database.

Every path requires a SQL Server login that is a member of the sysadmin fixed server role. Otherwise the wizard stops with "You must be a member of the sysadmin role on the specified SQL Server instance. Please contact your system administrator."

For what to plan for before you upgrade and the version-specific changes it brings, see Upgrade Considerations. For the steps of an upgrade, see Upgrade a Production Installation.

Upgrade version checks

The wizard stops the upgrade in these cases:

  • An in-place upgrade of a database that is already at the wizard's version is refused with "Your database is already compatible with this version of Alloy Navigator, no update is required."
  • If the wizard cannot find an upgrade path for the database's version, it displays a message that names both versions and directs you to support.

What an in-place upgrade does

For an interactive in-place upgrade, Enable backup is selected by default on the Backup Location page. The wizard does not create a backup on Azure SQL. An unattended database upgrade also runs without a backup.

The wizard re-creates the database's functions, views, procedures, foreign-key indexes, and triggers from the files supplied with the product. It also raises the database compatibility level to 130.

The wizard does not log users off before an in-place upgrade and does not check whether they are logged off.

Changes for older databases

Older databases receive one-time conversions. Because an in-place upgrade starts at 8.0.0, databases below 8.0.0 receive these conversions through a migration path.

A database below version 8.2.0, upgraded in place or migrated:

  • Every validation rule is converted into a trigger that runs when the object is created or changed. Its function shows the old rule's message and then aborts. The trigger runs for any role, after the object's existing create and change triggers.
  • Each knowledge base article and library item that lists sharing organizations gets a service named Availability Service [n] and an SLA named Availability SLA [n] whose receivers are those organizations; an SLA that the conversion has already created for exactly the same organizations is reused. An item that lists no organizations gets neither.

A database below version 8.0.0:

  • The person's Pager field is copied into a new user-defined field, and the macros and update-field definitions that referred to it are rewritten. References to the user macros Web Portal Link and Self Service Portal Link are replaced with references to the system macros of the same names.
  • Every Active Directory Import and Alloy Discovery Connector job is disabled, and their Create Organizations and Create Locations options are turned on. The Active Directory and Alloy Discovery create actions of the Location and Organization objects are deleted.
  • Create Pilot Database points the person create and update actions of each Active Directory Import job, where the job names them, and the Self Service Portal's person-creation action setting, at New Person (Active Directory Sync) (New 8.0.0) and Update Person (Active Directory Sync) (New 8.0.0). It deletes every other Active Directory create and update action, and the Workflow Log entries of those actions with them.
  • When Create Pilot Database installs the Default Workflow, which it does with Install Default Workflow and always from an Alloy Navigator Express database, it also points the Alloy Discovery Connector jobs at New Person (Alloy Discovery Connector) (New 8.0.0), New Computer (Alloy Discovery Connector) (New 8.0.0), Update Computer (Alloy Discovery Connector) (New 8.0.0), and two Chromebook actions. It deletes the other Alloy Discovery Connector create and update actions, apart from New Hardware (Alloy Discovery Connector), Update Hardware (Alloy Discovery Connector), and those that a job's hardware options name, and every other Chromebook action. Neither step changes a job's inventory database connection.

A database of version 6.5.1 or earlier:

  • Every top-level report category is filed under a new category named Legacy Reports (Alloy Navigator 6).
  • Each dashboard panel becomes a dashboard widget named widget name (dashboard name). A panel that was on two dashboards becomes two widgets.
  • Every existing detail report is hidden, so only the new detail reports are offered for printing until a technician unhides the old ones.
  • Each Mail Connector job's ticket creation and update become two operations of the job: create a ticket of the job's ticket class, and update the object that the message's reference identifies, a text in the subject or content that begins with MessageID: and ends with #.
  • The Alloy Navigator 6 approval logic of change requests does not survive: a database migrated to 2026.1 keeps neither that logic nor a setting to select it.

A migration from a version below 7.0.0 that keeps its existing workflow, that is, Create Pilot Database without Install Default Workflow:

  • The security roles Administrator, Administrator (Workflow), Administrator (Security), Administrator (Services), and Administrator (Views/Dashboards) are added with their permissions and shared views and with no members. A role that already has the ID of the built-in administrator role is renamed Administrator.
  • The user macros Activity List Published, Links All, Assignee Group E-mail List, Activity List All, and PO Items All are added. Activity List All, Activity List Published, and PO Items All still resolve as system macros, and no step rewrites a reference to them, so an existing system-macro reference keeps using the built-in value.
  • From a version below 6.5.0, every function that was set to publish its activity gets a first operation that sets the activity's Published field to 1, and the setting is removed.

A migration from version 6 or 7 keeps the entries and settings of every log, the Error Log's alerts, and the idle-session limit, with these exceptions: Create Pilot Database with Install Default Workflow, and every Create Pilot Database from an Alloy Navigator Express database, empties the Workflow Log; Update Pilot Data and Switch to Production delete the Workflow Log entries that come with the production data; the Active Directory create and update actions that Create Pilot Database deletes from a database below version 8.0.0 take their Workflow Log entries with them; and the conversion for version 6.5.1 deletes one Error Log category with its alerts and entries.