title: Upgrade Guide category: Administration tags: upgrade, migration, backup, update, version priority: Normal

Upgrade Guide

This guide walks you through safely upgrading IdentityCenter to a new version. The upgrade process is designed to be straightforward, with automatic database migrations handling schema changes.

Before You Upgrade

1. Check the Release Notes

Before upgrading, review the release notes for the new version:

• New features and improvements
• Breaking changes or deprecations
• Required minimum .NET version
• Required minimum SQL Server version
• Any special upgrade instructions

2. Backup Your Database

This is the most important step. Always create a full database backup before upgrading.

Using SQL Server Management Studio:

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

Or using T-SQL:

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

Important: Verify your backup is valid by checking the backup file exists and has a reasonable size. You should be able to restore from this backup if anything goes wrong.

3. Backup Your Configuration

Save a copy of your configuration files:

• appsettings.json — Contains your connection string and settings
• Any custom SMTP or notification settings

4. Note Your Current Version

Record your current IdentityCenter version before upgrading. You can find it on the About page or in the application footer.

Upgrade Process

Step 1: Stop the Application

If running as a Windows Service:

Stop-Service IdentityCenter

If running in IIS:

1. Open IIS Manager
2. Navigate to your IdentityCenter site
3. Click Stop in the Actions pane

Step 2: Replace Application Files

1. Download the new version
2. Extract the files to a temporary location
3. Copy the new files over the existing installation directory
4. Do not overwrite appsettings.json — your configuration should be preserved

Tip: Keep your appsettings.json configuration. The new version's default appsettings.json may have new settings, but your existing values should continue to work. You can merge any new settings later.

Step 3: Start the Application

If running as a Windows Service:

Start-Service IdentityCenter

If running in IIS:

1. Start the site in IIS Manager
2. Navigate to the site URL in your browser

Step 4: Automatic Database Migration

When IdentityCenter starts with a new version, it automatically:

1. Detects the current database schema version
2. Applies any new migration scripts in order
3. Updates indexes, constraints, and seed data as needed
4. Logs the migration results

This process is automatic — you don't need to run any manual migration commands.

Note: The first startup after an upgrade may take longer than usual while migrations run. For large databases, this could take a few minutes.

Step 5: Verify the Upgrade

After the application starts:

1. Log in to the web portal
2. Check the About page to confirm the new version
3. Navigate to Dashboard and verify data is intact
4. Run a test sync to confirm AD connectivity
5. Check Administration > Jobs to verify scheduled tasks are running

Rollback Procedure

If something goes wrong during the upgrade:

Step 1: Stop the Application

Stop-Service IdentityCenter

Step 2: Restore the Database

-- Close existing connections
ALTER DATABASE [IdentityCenter] SET SINGLE_USER WITH ROLLBACK IMMEDIATE;

-- Restore from backup
RESTORE DATABASE [IdentityCenter]
FROM DISK = 'C:\Backups\IdentityCenter_PreUpgrade.bak'
WITH REPLACE;

-- Return to multi-user mode
ALTER DATABASE [IdentityCenter] SET MULTI_USER;

Step 3: Restore Application Files

Replace the application files with the previous version.

Step 4: Restore Configuration

Copy your backed-up appsettings.json back to the application directory.

Step 5: Restart

Start the application and verify it's running on the previous version.

Upgrading .NET Runtime

Some IdentityCenter upgrades may require a newer version of the .NET Runtime:

1. Check the release notes for the required .NET version
2. Download the .NET Runtime from Microsoft's .NET download page
3. Install the new runtime (you can have multiple versions installed side-by-side)
4. Proceed with the IdentityCenter upgrade

Upgrading SQL Server

If a new IdentityCenter version requires a newer SQL Server version:

1. Backup your database first
2. Upgrade SQL Server following Microsoft's documentation
3. Verify the database is accessible after the SQL upgrade
4. Then proceed with the IdentityCenter upgrade

Tip: Always upgrade the infrastructure (OS, .NET, SQL) before upgrading IdentityCenter.

Post-Upgrade Tasks

After a successful upgrade:

1. Review new features — Check the release notes and explore new functionality
2. Update documentation — Note the new version in your internal records
3. Test key workflows — Run a sync, verify a policy, check an access review
4. Clean up — Delete old backup files once you've confirmed the upgrade is stable (keep at least one recent backup)

Troubleshooting

Application Won't Start After Upgrade

• Check the application logs for error messages
• Verify the .NET Runtime version is compatible
• Ensure the database is accessible
• Check that appsettings.json is valid JSON

Database Migration Fails

• Check the application logs for the specific migration error
• Verify the database account has db_owner permissions
• Ensure no other connections are holding locks on the database
• If the migration is stuck, restore from backup and contact support

Configuration Changes

If the new version introduces new configuration settings:

• The application will use default values for any missing settings
• Review the new version's appsettings.json template for new options
• Add any new settings you want to customize to your existing appsettings.json

Upgrade Checklist

• Read release notes for the new version
• Create full database backup
• Backup appsettings.json
• Note current version number
• Stop the application
• Replace application files (preserve appsettings.json)
• Start the application
• Verify version number updated
• Verify dashboard data is intact
• Run a test sync
• Verify scheduled jobs are running
• Test login/logout
• Review new features

Next Steps

• Installation & Setup — Fresh installation guide
• Security Hardening — Review security after upgrade
• Common Issues — Troubleshoot problems