Upgrading from a Previous Release

To upgrade the version of WSO2 Identity Server, the user store database should be upgraded. Note that there are no registry schema changes between versions. This topic provides instructions on how you can upgrade (the data and configurations) from WSO2 Identity Server 4.1.0 to WSO2 Identity Server 4.6.0.

If you want to migrate your Identity Server configurations from one instance to another (such as when promoting your instance from test to production) using the same Identity Server release, see Migrating the Identity Server.

Preparing to upgrade

The following are the specific prerequisites you must complete before you upgrade WSO2 Identity Server:

Before you upgrade to the latest version of WSO2 Identity Server, you create a staging database, which is essentially an empty database. Note that you should NOT connect a new version of WSO2 IS to an older database that has not been migrated.
Make backups of the database and the WSO2 product prior to upgrading the database. The backup can be taken by copying the home folder of the product.
Stop all the WSO2 products that are connected to the database.
If any files/folders are changing in the product pack to which you are upgrading, you need to make a backup of the relevant files/folders prior to changes.

Limitations

The following are the limitations of upgrading.

This upgrading process can only be done for the same database types. For example, if you are using MySQL currently and you wish to use Oracle in the new version of Identity Server, these scripts will not work.
You cannot roll back the upgrading process. It is impossible to restore a backup of the previous server and retry the upgrading progress.

Downtime

The downtime is limited to the time taken for switching databases when in the production environment.

Upgrading the database

Stop the current WSO2 Identity Server 4.1.0.
Select the relevant script for the upgrade from here on the production database. The script you use will depend on the type of database you are using, for instance, if your database is MySQL you need to run the execute mysql-migration.sql command in MySQL (you would use Oracle or MSSQL to run the script if that is the database you are using). Running this script will ensure that the database is upgraded with the additional tables and schemas which are required for IS 4.6.0.

There are three migration scripts available: migration-service-provider.sql, migration-identity.sql and migration.sql. However, for all Carbon products except WSO2 IS, only the migration.sql script is required to be executed. In the case of IS, all three scripts need to be run.
Once you run the migration script on the production database, copy your configurations to the staging database you created. This becomes the new database for your new version of IS.
Download WSO2 Identity Server 4.6.0 from http://wso2.com/products/identity-server/.
To connect the new product version to the upgraded database, configure the following files:
1. Configure <PRODUCT_HOME>/repository/conf/datasources/master-datasources.xml. See here for more information on how to do this for your database.
2. Go to the <PRODUCT _HOME>/repository/conf directory and update the datasource references in user-mgt.xml and registry.xml to match the updated configurations in the master-datasources.xml file which you made in the above step. The following are sample configurations if the datasource is jdbc/WSO2CarbonDB.
  registry.xml
```
<dbConfig name="wso2registry">
    <dataSource>jdbc/WSO2CarbonDB</dataSource>
</dbConfig> 
```
  user-mgt.xml
```
<UserManager>
  <Realm>
  <Configuration>
  ...
  <Property name="dataSource">jdbc/WSO2CarbonDB</Property>
  </Configuration>
  ...
  </Realm>
</UserManager>
```

Migrating XACML policies

The following steps are only required if XACML policies are used in the previous product version ( IS 4.1.0 and IS 4.0.0). This is because the default XACML policy store has changed since IS 4.5.0.

Log in to the new Identity Server and go to the entitlement management console. Note that the XACML policies are not visible in this screen.
To perform the migration of XACML policies, download this migration tool.
In the migration tool you downloaded, set up the configuration parameters using the config.properties file which can be found in the <ROOT>/resources directory.
Execute the following command to start the migration.
On Windows
```
migratePolicies.bat
```
On Linux
```
./migratePolicies.sh
```
OAuth applications, which were created in the tenants are also created inside the super admin space. This is because, IS 4.1.0 did not support tenant partitioning for OAuth applications. If there are OAuth apps available in the tenant space, you have to manually include them inside the tenant space once the migration process is done.

Recommended checkpoints

The databases should contain the newly added tables, which are namely as follows:

UM_DOMAIN
UM_SYSTEM_USER
UM_SYSTEM_ROLE
UM_SYSTEM_USER_ROLE
IDP_BASE_TABLE
UM_TENANT_IDP
UM_TENANT_IDP_ROLES
UM_TENANT_IDP_ROLE_MAPPINGS
IDN_THRIFT_SESSION
IDN_IDENTITY_USER_DATA
IDN_IDENTITY_META_DATA

Going into production

The following are recommended tests to run on the staging system.

Create multiple user stores and try adding users to different user stores.
Create multiple tenants and add different user stores to the different tenants. Thereafter, add users to the various user stores.

Once the above tests are run successfully, it is safe to consider that the upgrade is ready for production. However, it is advised to test any features that are being used in production.