Versions Compared

Key

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

 DRAFT DOCUMENT

This page walks you through the process of upgrading to ESB 4.9.0 from a previous ESB version. Go to the required tab for step by step instructions based on the upgrade you need to perform.

Localtabgroup
Migrating Secured ServicesWith the removal of QoS features from ESB management console, enabling security for services hosted in ESB has changed from ESB 4.9.0
Localtab
titleUpgrading from ESB 4.6.0 to ESB 4.9.0

The followings steps describe how you can upgrade data and configurations from ESB 4.6.0 to ESB 4.9.0. 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 4.6.0 database for use in ESB 4.9.0.

  1. Before you upgrade to ESB 4.9.0, create a new database and restore the backup of the ESB 4.6.0 database in this new database.

    Info
    titleNote

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

  2. Select the relevant 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 4.9.0

    Info
    titleNote

    There are three migration scripts available:  migration-service-provider.sql , migration-identity.sql and  migration.sql. However, only the  migration.sql script is required to be executed for the ESB database upgrade.

Once you run the migration scripts on the new database, it becomes the upgraded database for ESB 4.9.0.

Migrating the configurations

Once you have completed the database upgrade, You can proceed with the configuration changes as explained below. The configurations can be directly migrated from ESB 4.6.0 to ESB 4.9.0.

Note
titleNote

 Configurations should not be copied directly between servers.

To connect ESB 4.9.0 to the upgraded database, configure the following files:

  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.6.0 based on your solution and update the configuration files in ESB 4.9.0 accordingly. For example, configurations related to external user stores, caching, mounting, transports etc.

    Info
    titleNote

    The following files have changed from ESB 4.6.0 to ESB 4.9.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.6.0 that you want to migrate, copy the following directories as applicable from ESB 4.6.0 to ESB 4.9.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 4.9.0 server.

Migrating artifacts

You should manually deploy Composite Application Archive (CAR) files that you have in ESB 4.6.0 to ESB 4.9.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 Creating and 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.6.0 to ESB 4.9.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.6.0 to ESB 4.9.0.
  • If multi-tenancy is used, copy the <ESB_HOME>/repository/tenants directory from ESB 4.6.0 to ESB 4.9.0.
Note

Prior to copying the above folders remove all secured services from the folder. For instructions on migrating these services, see Migrating Secured Services.

Anchor
MigratingSecuredServicesMigratingSecuredServices

The org.wso2.caching.digest.REQUESTHASHGenerator interface, which is supported by WSO2 ESB 4.8.1 is not supported by later versions. Therefore, change the artifacts to use the org.wso2.carbon.mediator.cache.digest.DOMHASHGenerator as the hash generator when migrating artifacts related to the Cache mediator from WSO2 ESB 4.8.1 to a later version.

Note

Prior to copying the above folders remove all secured services from the folder.

With the removal of QoS features from ESB management console, enabling security for services hosted in ESB has changed from ESB 4.9.0 onwards. You now need to secure your services using WSO2 Developer Studio

based

before you can migrate them to ESB 4.9.0.

See, Applying Security to a Proxy Service for instructions on how

to create secured

tocreatesecured services and deploy them in ESB.

Testing the upgrade

  1. When the database upgrade scripts are executed, the following are some of the new tables that will be created in the database:
    • UM_DOMAIN
    • UM_SYSTEM_USER
    • UM_SYSTEM_ROLE
    • UM_SYSTEM_USER_ROLE
  2. Verify that all the required scenarios are working as expected. This confirms that the upgrade is successful.
Migrating Secured Services
Localtab
titleUpgrading from ESB 4.8.0 to ESB 4.9.0

The followings steps describe how you can upgrade data and configurations from ESB 4.8.0 to ESB 4.9.0. 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 4.8.0 database for use in ESB 4.9.0.

  1. Before you upgrade to ESB 4.9.0, create a new database and restore the backup of the ESB 4.8.0 database in this new database.

    Info
    titleNote

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

  2. 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 4.9.0

Once you run the migration scripts on the new database, it becomes the upgraded database for ESB 4.9.0.

Migrating the configurations

Once you have completed the database upgrade, You can proceed with the configuration changes as explained below. The configurations can be directly migrated from ESB 4.8.0 to ESB 4.9.0.

Note
titleNote

 Configurations should not be copied directly between servers.

To connect ESB 4.9.0 to the upgraded database, configure the following files:

  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.8.0 based on your solution and update the configuration files in ESB 4.9.0 accordingly. For example, configurations related to external user stores, caching, mounting, transports etc.

    Info
    titleNote

    The following files have changed from ESB 4.8.0 to ESB 4.9.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.8.0 that you want to migrate, copy the following directories as applicable from libraries used with ESB 4.8.0 that you want to migrate, copy the following directories as applicable from ESB 4.8.0 to ESB 4.9.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 4.8.1 server.

Migrating artifacts

You should manually deploy Composite Application Archive (CAR) files that you have in ESB 4.8.0 to ESB 4.9.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 Creating and 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.8.0 to ESB 4.9.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
    • .  If you do not have axis2 modules or axis2 services, you can copy the required synapse artifacts from the <ESB_HOME>/repository/
    components/dropins
  • Start the ESB 4.8.1 server.
  • Migrating artifacts

    You should manually deploy Composite Application Archive (CAR) files that you have in
    • deployment/server/synapse-configs/default directory of ESB 4.8.0 to ESB 4.9
    .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 Creating and 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 .0.
    • If multi-tenancy is used, copy the <ESB_HOME>/repository/deployment/servertenants directory of from ESB 4.8.0 to ESB 4.9.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.8.0 to ESB 4.9.0.If multi-tenancy is used, copy the <ESB_HOME>/repository/tenants directory from .9.0.
    Note

    The org.wso2.caching.digest.REQUESTHASHGenerator interface, which is supported by WSO2 ESB 4.8.1 is not supported by later versions. Therefore, change the artifacts to use the org.wso2.carbon.mediator.cache.digest.DOMHASHGenerator as the hash generator when migrating artifacts related to the Cache mediator from WSO2 ESB 4.8.

    0 to ESB 4.9.0.

    1 to a later version.

    Note

    Prior to copying the above folders remove all secured services from the folder. For instructions on migrating these services, see Migrating Secured Services.

    Anchor
    MigratingSecuredServicesMigratingSecuredServices

    With the removal of QoS features from ESB management console, enabling security for services hosted in ESB has changed from ESB 4.9.0 onwards. You now need to secure your services using WSO2 Developer Studio

    based

    before you can migrate them to ESB 4.9.0.

    See, Applying Security to a Proxy Service for instructions on how to create secured services and deploy them in ESB.

    Testing the upgrade

    1. When the database upgrade scripts are executed, the following are some of the new tables that will be created in the database:
      • UM_DOMAIN
      • UM_SYSTEM_USER
      • UM_SYSTEM_ROLE
      • UM_SYSTEM_USER_ROLE
    2. Verify that all the required scenarios are working as expected. This confirms that the upgrade is successful.
    MigratingSecuredServices
    Localtab
    titleUpgrading from ESB 4.8.1 to ESB 4.9.0

    The followings steps describe how you can upgrade data and configurations from ESB 4.8.1 to ESB 4.9.0. 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 4.8.1 database for use in ESB 4.9.0.

    1. Before you upgrade to ESB 4.9.0, create a new database and restore the backup of the ESB 4.8.1 database in this new database.

      Info
      titleNote

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

    2. 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 4.9.0

    Once you run the migration scripts on the new database, it becomes the upgraded database for ESB 4.9.0.

    Migrating the configurations

    Once you have completed the database upgrade, You can proceed with the configuration changes as explained below. The configurations can be directly migrated from ESB 4.8.1 to ESB 4.9.0.

    Note
    titleNote

     Configurations should not be copied directly between servers.

    To connect ESB 4.9.0 to the upgraded database, configure the following files:

    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.8.1 based on your solution and update the configuration files in ESB 4.9.0 accordingly. For example, configurations related to external user stores, caching, mounting, transports etc.

      Info
      titleNote

      The following files have changed from ESB 4.8.1 to ESB 4.9.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.8.1 that you want to migrate, copy the following directories as applicable from ESB 4.8.1 to ESB 4.9.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 4.9.0 server.

    Migrating artifacts

    You should manually deploy Composite Application Archive (CAR) files that you have in ESB 4.8.1 to ESB 4.9.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 Creating and 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.8.1 to ESB 4.9.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 /synapse-configs/default directory of ESB 4.8.1 to ESB 4.9.0.
    • If multi-tenancy is used, copy the <ESB_HOME>/repository/tenants directory from ESB 4.8.1 to ESB 4.9.0.
    • If you have a security-enabled service in WSO2 ESB 4.8.1, you need to secure it via WSO2 Developer Studio before deploying it in WSO2 ESB 4.9.0. If multi-tenancy is used, copy the <ESB_HOME>/repository/tenants directory from For instructions, see Applying Security to a Proxy Service.
    Note

    The org.wso2.caching.digest.REQUESTHASHGenerator interface, which is supported by WSO2 ESB 4.8.1

    to ESB 4.9.0.If you have a security-enabled service in

    is not supported by later versions. Therefore, change the artifacts to use the org.wso2.carbon.mediator.cache.digest.DOMHASHGenerator as the hash generator when migrating artifacts related to the Cache mediator from WSO2 ESB 4.8.1

    , you need

    to

    secure it via WSO2 Developer Studio before deploying it in WSO2 ESB 4.9.0. For instructions, see Applying Security to a Proxy Service.
     

    a later version.

    Note

    Prior to copying the above folders remove all secured services from the folder. For instructions on migrating these services, see Migrating Secured Services.

    Anchor

    MigratingSecuredServicesMigrating Secured Services

    With the removal of QoS features from ESB management console, enabling security for services hosted in ESB has changed from ESB 4.9.0 onwards. You now need to secure your services using WSO2 Developer Studio

    based

    before you can migrate them to ESB 4.9.0. 

    See, Applying Security to a Proxy Service for instructions on how to create secured services and deploy them in ESB.

    Testing the upgrade

    1. When the database upgrade scripts are executed, following are some of the new tables that will be created in the database:
      • UM_DOMAIN
      • UM_SYSTEM_USER
      • UM_SYSTEM_ROLE
      • UM_SYSTEM_USER_ROLE
    2. Verify that all the required scenarios are working as expected. This confirms that the upgrade is successful.