Zoomed Image
USA
800 691 9120
UK
01225 704844

Upgrading

xAssets Configuration Guide
Deployment and Administration

Upgrading

This page describes the process for upgrading xAssets to a new version. xAssets is designed to make upgrades straightforward -- your configuration customisations are preserved automatically, and the database schema is upgraded in place.

Upgrade Process Overview

An xAssets upgrade consists of three phases:

  1. Application file update -- the web application files, batch service, and related binaries are replaced with the new version.
  2. Database auto-upgrade -- when the updated application connects to the database for the first time, it detects the version mismatch and automatically upgrades the database schema.
  3. Verification -- confirm that the application is running correctly on the new version.

Your configuration (forms, queries, menus, dashboards, transformations, user groups, and settings) is stored as data in the database and is never overwritten by an upgrade. See Upgradeability for details on how this works.

Pre-Upgrade Checklist

Complete these steps before starting the upgrade:

  1. Back up the database. Take a full database backup immediately before the upgrade. See Backup and Recovery for instructions. This is your safety net if anything goes wrong.

  2. Back up the CustomerData and CustomerDataPrivate folders. These contain your XDML configuration files, scripts, and credential packs.

  3. Check for running batch jobs. Navigate to Admin > Batch > Batch Jobs and ensure no jobs are currently running. If a batch job is in progress, wait for it to complete or abort it before proceeding.

  4. Notify users. Inform users that the system will be unavailable during the upgrade. The file update takes a few minutes; the database auto-upgrade duration depends on database size and may range from a few minutes to an hour for very large databases.

  5. Review the release notes. Check the release notes for the new version for any special instructions, breaking changes, or new features that may affect your configuration.

  6. Verify system requirements. Ensure the server meets the System Requirements for the new version. Newer versions may require updated versions of .NET Framework, IIS, or SQL Server.

Performing the Upgrade

Step 1: Stop the Application

  1. Open IIS Manager on the application server.
  2. Stop the xAssets application pool to prevent user access and ensure no active sessions interfere with the file update.
  3. Stop the xAssets Batch Service in Windows Services to prevent scheduled jobs from starting.

Step 2: Update Application Files

  1. Run the xAssets installer for the new version. The installer replaces the web application files, batch service binaries, and related components.
  2. Follow the on-screen prompts to select the installation directory and components. Accept the defaults unless your environment requires a custom configuration.

Tip: The installer does not modify your CustomerData or CustomerDataPrivate folders. Your configuration files, scripts, and credential packs are preserved.

Step 3: Database Auto-Upgrade

  1. Start the xAssets application pool in IIS.
  2. Open xAssets in a browser. The application detects the version mismatch between the application files and the database schema.
  3. The database auto-upgrade runs automatically. This process:
    • Creates new tables and columns required by the new version
    • Updates stored procedures, views, and functions
    • Migrates data where necessary
    • Updates the version number in the database
  4. The upgrade progress is displayed on screen. Do not close the browser or stop the application pool during this process.

Warning: The database auto-upgrade requires exclusive access. Ensure no other users or processes are connected to the database during this step. If other connections are active, the upgrade may fail or produce errors.

Step 4: Restart the Batch Service

  1. Start the xAssets Batch Service in Windows Services.
  2. Verify it starts without errors by checking the Windows Event Log.

Post-Upgrade Verification

After the upgrade completes, verify the system is functioning correctly:

  1. Log in -- confirm you can log in with your administrator account.
  2. Check the version number -- navigate to Admin > About (or check the page footer) to confirm the version matches the expected new version.
  3. Test key functions:
    • Open several forms and verify fields display correctly.
    • Run a query to confirm data retrieval works.
    • Check the dashboard for any visual issues.
    • If you use discovery, verify that the batch service is processing discovery data.
    • If you use email notifications, send a test notification.
  4. Review batch jobs -- navigate to Admin > Batch > Batch Jobs and confirm that any scheduled transformations are running on their expected schedule.
  5. Check the event log -- review the Windows Application Event Log for any errors or warnings from the xAssets application.

Rollback

If the upgrade causes critical issues:

  1. Stop the IIS application pool and the Batch Service.
  2. Restore the database from the pre-upgrade backup (see Backup and Recovery).
  3. Restore the application files from backup or reinstall the previous version.
  4. Restore the CustomerData and CustomerDataPrivate folders if they were modified.
  5. Restart the application pool and Batch Service.
  6. Verify the system is running on the previous version.

Warning: Rolling back after a database auto-upgrade requires restoring the entire database from backup. The auto-upgrade modifies the schema in place and cannot be undone incrementally.

Upgrading with Failover

If you have a failover server configured (see Failover), coordinate the upgrade carefully:

  1. Upgrade the primary server first.
  2. After the primary is verified, the failover server will receive the upgraded database through the normal backup shipping process.
  3. Update the application files on the failover server to match the primary.
  4. The failover server's restore process will apply the shipped backups containing the upgraded database schema.