title: Upgrading from Previous Versions category: Getting Started tags: upgrade, migration, version, database, compatibility priority: Normal

Upgrading from Previous Versions

This guide covers the process of upgrading an existing IdentityCenter installation to a newer version. IdentityCenter is designed for straightforward upgrades with automatic database migrations, but proper planning and backups are essential.

Pre-Upgrade Checklist

Before starting any upgrade, complete every item on this checklist:

• Back up the database -- Take a full SQL Server backup of the IdentityCenter database
• Back up configuration files -- Copy appsettings.json, appsettings.Production.json, and any custom configuration
• Back up the application directory -- Copy the entire application folder as a rollback point
• Review the release notes -- Check for breaking changes, deprecated features, and new requirements
• Verify .NET runtime compatibility -- Confirm the target version's required .NET runtime is installed
• Verify SQL Server version -- Ensure your SQL Server meets the minimum version for the new release
• Check disk space -- Ensure sufficient disk space for the new application files and any database growth
• Notify stakeholders -- Inform your team about the maintenance window
• Stop scheduled sync jobs -- Disable or pause active sync schedules to prevent mid-upgrade conflicts

Tip: Always test the upgrade on a staging environment before applying it to production. Clone your production database to a test SQL Server instance and run the full upgrade there first.

Database Backup

The most critical pre-upgrade step is backing up your database. Use one of these methods:

SQL Server Management Studio:

1. Right-click the IdentityCenter database
2. Select Tasks > Back Up
3. Choose Full backup type
4. Save to a secure location

T-SQL:

BACKUP DATABASE [IdentityCenter]
TO DISK = N'C:\Backups\IdentityCenter_PreUpgrade.bak'
WITH FORMAT, COMPRESSION, STATS = 10;

Verify the backup is complete and restorable before proceeding.

Upgrade Process

Step 1: Stop the IdentityCenter Service

If running as a Windows Service:

Stop-Service -Name "IdentityCenter"

If running under IIS:

Stop-WebAppPool -Name "IdentityCenterAppPool"

If running as a systemd service on Linux:

sudo systemctl stop identitycenter

Step 2: Replace Application Files

1. Extract the new release package to a temporary directory
2. Copy the new files over the existing application directory
3. Preserve your existing configuration files (appsettings.json, appsettings.Production.json)
4. If the release notes mention new configuration settings, merge them into your existing files

Important: Do not delete your existing appsettings.Production.json. New releases may add default settings to appsettings.json, but your production overrides should remain intact.

Step 3: Start the Service

Start the IdentityCenter service. On startup, the application will automatically run any pending database migrations.

Start-Service -Name "IdentityCenter"

Step 4: Monitor Startup

Watch the application logs during the first startup after an upgrade:

• Database migrations will run automatically via DatabaseMigrationService
• Each migration script (V001, V002, etc.) is idempotent and checks for existing schema before making changes
• The SchemaVerificationService validates the database schema after migrations complete
• Startup logs will report which migrations were applied and whether verification passed

Step 5: Verify the Upgrade

After the service starts successfully:

1. Open the web portal and confirm you can log in
2. Check System Center for any errors or warnings
3. Review the About page to confirm the version number
4. Run a test sync on a small sync project to verify synchronization works
5. Verify policies still evaluate correctly by checking the Policies dashboard
6. Test email delivery by sending a test notification
7. Check the Processing Center to confirm scheduled jobs are running

Database Migration System

IdentityCenter uses an embedded migration system instead of Entity Framework migrations at runtime. Understanding how it works helps during upgrades.

How Migrations Work

Migration Script Conventions

Each migration script:

• Checks whether its changes have already been applied before executing
• Uses IF NOT EXISTS guards for table and index creation
• Is safe to re-run without causing errors or data loss
• Executes within a transaction where possible

Fresh vs. Existing Databases

On a fresh installation, all migration scripts run in sequence to build the complete schema. On an existing installation, only new scripts (those not yet recorded in the migration history) are executed. The result is the same final schema regardless of the starting point.

Version Compatibility Matrix

Note: Always consult the release notes for the specific version you are upgrading to. The table above is a general reference.

Rollback Procedures

If the upgrade fails or introduces unexpected issues, you can roll back:

Step 1: Stop the Service

Stop-Service -Name "IdentityCenter"

Step 2: Restore Application Files

Replace the application directory with the backup you created before the upgrade.

Step 3: Restore the Database

USE [master];
ALTER DATABASE [IdentityCenter] SET SINGLE_USER WITH ROLLBACK IMMEDIATE;
RESTORE DATABASE [IdentityCenter]
FROM DISK = N'C:\Backups\IdentityCenter_PreUpgrade.bak'
WITH REPLACE;
ALTER DATABASE [IdentityCenter] SET MULTI_USER;

Step 4: Start the Previous Version

Start-Service -Name "IdentityCenter"

Verify the rollback by checking the version number and running a test sync.

Breaking Changes to Watch For

When reviewing release notes, pay special attention to:

Best Practices

1. Always test in staging first -- Clone your production database and run the upgrade in a staging environment before touching production.
2. Upgrade during a maintenance window -- Schedule upgrades outside business hours to minimize impact on sync schedules and user access.
3. Have a rollback plan ready -- Verify your database backup is restorable before starting the upgrade.
4. Upgrade incrementally -- If you are multiple versions behind, consider upgrading one major version at a time rather than jumping directly to the latest.
5. Review sync results after upgrade -- Run full syncs on all projects after upgrading and verify object counts match expectations.
6. Keep audit logs -- Do not truncate audit log tables before upgrading. They may be needed for post-upgrade verification.

Next Steps

• System Requirements -- Verify your environment meets requirements for the new version
• Quick Config Wizard -- Re-run the wizard if new setup steps were added
• Sync Troubleshooting -- Resolve any sync issues after upgrading
• Connection Troubleshooting -- Verify connections are healthy post-upgrade