The followings steps describe how you can upgrade data and configurations when upgrading from ESB 4.9.0 to ESB 5.0.0. For more information on release versions, see the Release Matrix.
You cannot roll back the upgrade process. However, it is possible to restore a backup of the previous database so that you can restart the upgrade progress.
Preparing to upgrade
The following prerequisites must be completed before upgrading:
The downtime is limited to the time taken for switching databases in the production environment.
Upgrading the database
It is not mandatory that you migrate the user management database when upgrading from ESB 4.9.0 to ESB 5.0.0.
If you choose to proceed without migrating:
Set the following property to true in the
<ESB_5.0.0_HOME>/repository/conf/user-mgt.xml file as shown below.
If you choose to migrate:
Download the WSO2 Identity Server Migration Client. This is used to migrate the user management database schemas that are used by WSO2 ESB. Unzip the downloaded file to the local file system, and you will have a directory named
wso2is-5.1.0-migration. Then do the following:
- Copy the
wso2is-5.1.0-migration/dbscripts/migration-5.0.0_to_5.1.0 directory to the
- Copy the
wso2is-5.1.0-migration/dbscripts/identity/migration-5.0.0SP1_to_5.1.0 directory and the
wso2is-5.1.0-migration/dbscripts/identity/migration-5.0.0_to_5.0.0SP1 directory to the
- Copy the
wso2is-5.1.0-migration/dropins/org.wso2.carbon.is.migrate.client-5.1.0.jar file to the
Start WSO2 ESB 5.0.0 using the command line with the options given below in the following order:
-Dmigrate -DmigrateUMDB -Dcomponent=identity
-Dmigrate -DmigrateUMData -Dcomponent=identity
This will carry out the migration of the user management database.
Migrating the configuration files
Configurations should not be copied directly between servers.
To connect ESB 5.0.0 to the upgraded database, configure the following files:
- Go to the
<ESB_HOME>/repository/conf/datasources directory and update the
master-datasources.xml file . See Configuring master-datasources.xml.
Go to the
<ESB_HOME>/repository/conf directory and update the datasource references in the
registry.xml files to match the updated configurations in the
master-datasources.xml file that you made in the above step. See Configuring user-mgt.xml and Configuring registry.xml.
Check for any other configurations that were done for ESB 4.9.0 based on your solution and update the configuration files in ESB 5.0.0 accordingly. For example, configurations related to external user stores, caching, mounting, transports, etc.
The following files have changed from ESB 4.9.0 to ESB 5.0.0:
- If there are any third-party libraries used with ESB 4.9.0 that you want to migrate, copy the contents of the following directories as applicable from ESB 4.9.0 to ESB 5.0.0:
- If you have used JMS libraries, JDBC libraries, etc., copy the contents of
- If you have used OSGi bundles such as SVN kit etc., copy the contents of
You should manually deploy Composite Application Archive (CAR) files that you have in ESB 4.9.0 to ESB 5.0.0. If you have a mediator packed in a CAR, all the artifacts using that mediator should also be included in the same CAR. See Deploying Composite Applications in the Server in the WSO2 Admin Guide for further details.
To migrate deployment artifacts including ESB message flow configurations:
Copy the required Synapse artifacts from the
<ESB_HOME>/repository/deployment/server directory of ESB 4.9.0 to ESB 5.0.0. If you do not have axis2 modules or axis2 services, you can copy the required Synapse artifacts from the
<ESB_HOME>/repository/deployment/server/synapse-configs/default directory of ESB 4.9.0 to ESB 5.0.0.
If you have used the Script mediator within your synapse configuration with the setProperty() method, you will need to modify the configuration as described here.
- If multi-tenancy is used, copy the
<ESB_HOME>/repository/tenants directory from ESB 4.9.0 to ESB 5.0.0.
Testing the upgrade
Verify that all the required scenarios are working as expected in ESB 5.0.0. This confirms that the upgrade is successful.