This documentation is for WSO2 Enterprise Service Bus version 5.0.0. For the latest ESB, view the latest WSO2 Enterprise Integrator documentation.

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The followings steps describe how you can upgrade data and configurations from ESB 4.9.0 to ESB 5.0.0 from a previous release. For more information on release versions, see the Release Matrix.

Note

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:

Info
titleNote

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

Upgrading the database

The instructions in this section describe how you can perform a data migration to upgrade the Since there are no database changes between ESB 4.9.0 database for use in and ESB 5.0.0.

...

, you are only required to migrate the configurations and settings from the previous version as explained below.

Note

When upgrading from ESB 4.8.1 or older to ESB 5.0.0,

...

Info
titleNote

You should NOT connect a new version of WSO2 ESB to an older database that has not been upgraded.

...

select the mysql.sql script for the upgrade from here and run it on the new database. Running this script will ensure that the new database is upgraded to have the additional tables and schemas that are required for

...

ESB 5.0.0

...

Migrating

...

the configuration files

Note
titleNote

 Configurations should not be copied directly between servers.

...

  1. Go to the <ESB_HOME>/repository/conf/datasources directory and update the master-datasources.xml file . See Configuring master-datasources.xml.
  2. Go to the <ESB_HOME>/repository/conf directory and update the datasource references in the user-mgt.xml and 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.

  3. 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.

    Info
    titleNote

    The following files have changed from ESB 4.9.0 to ESB 5.0.0

    • axis2.xml
    • axis2_nhttp.xml
    • axis2_pt.xml
    • tenant-axis2.xml
    • cache.xml
    • config-validation.xml
    • logging-bridge.properties
    • osgi-debug.option
    • cloud-services-desc.xml
    • authenticators.xml
    • ciper-tool.properties
    • catalina-server.xml
    • carbon.xml
    • identity.xml
    • nhttp.properties
    • passthru-http.properties
    • synapse.properties
    • user-mgt.xml
  4. If there are any third party libraries used with ESB 4.9.0 that you want to migrate, copy 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 <ESB_HOME>/repository/components/lib
    • If you have used OSGi bundles such as SVN kit etc, copy <ESB_HOME>/repository/components/dropins
  5. Start the ESB 5.0.0 server.

Migrating Artifacts

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 a Carbon Application for further details.

Info
titleNote

 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 multi-tenancy is used, copy the <ESB_HOME>/repository/tenants directory from ESB 4.9.0 to ESB 5.0.0.

Testing the upgrade

...

  • UM_DOMAIN
  • UM_SYSTEM_USER
  • UM_SYSTEM_ROLE
  • UM_SYSTEM_USER_ROLE

Verify that all the required scenarios are working as expected in ESB 5.0.0. This confirms that the upgrade is successful.