This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Upgrading from WSO2 Enterprise Service Bus

This page walks you through the process of upgrading to WSO2 Enterprise Integrator (WSO2 EI) 6.0.0 from WSO2 Enterprise Service Bus (WSO2 ESB) 5.0.0.

If you are upgrading from a version older than ESB 5.0.0, you will need to first upgrade to ESB 5.0.0 and then upgrade to WSO2 EI 6.0.0.

From WSO2 ESB 5.0.0 onwards, it does not support processing any mediators added after the send mediator in a given sequence because it may lead to erroneous behaviors when the message stream is consumed by the send mediator in passthrough scenarios. Therefore, if you have sequences with mediators after the send mediator, you need to change those sequences to have the send mediator inside a clone mediator, thereby, it will clone the message and process it separately. For example, see below.

<clone sequential="true">
    <target>
         <sequence>
              <send>
                   <endpoint key="ABC"/>
               </send>
         </sequence>
     </target>
     <target>
         <sequence>
             <switch xmlns:ns="http://org.apache.synapse/xsd" source="get-property('XYZ')">
                  <case regex="CASE1 ">
                       <log level="custom">
                           <property name="#### CASE ####" value="IN CASE1"/>
                       </log>
                       <sequence key="TEST.PQR "/>
                        <drop/>
                     </case>
                     <default>
                        <log level="custom">
                           <property name="#### DEFAULT ####" value="IN DEFAULT"/>
                        </log>
                        <drop/>
                     </default>
                  </switch>
           </sequence>
     </target>
</clone>
  • For information on the default ports in WSO2 EI runtimes, see Default ports of WSO2 EI.
  • The distribution folder structure has changed from ESB 5.0.0 to WSO2 EI 6.0.0. The changes in the folder structure for directory locations of the configuration related files are as follows:
Enterprise Service Bus 5.0.0Enterprise Integrator 6.0.0
<ESB_HOME>/repository/conf<EI_HOME>/conf
<ESB_HOME>/repository/conf/axis2<EI_HOME>/conf/axis2
<ESB_HOME>/repository/conf/datasources<EI_HOME>/conf/datasources
<ESB_HOME>/repository/components/dropins<EI_HOME>/dropins
<ESB_HOME>/repository/components/extensions<EI_HOME>/extensions
<ESB_HOME>/repository/components/lib<EI_HOME>/lib
<ESB_HOME>/repository/component/patches<EI_HOME>/patches
<ESB_HOME>/repository/components/plugins<EI_HOME>/wso2/components/plugins

Migrating the configuration files

  1. In WSO2 EI 6.0.0 you can use the same database that you used in ESB 5.0.0. Configure WSO2 EI 6.0.0 to use the existing database as follows:

    1. Copy the database drivers from <ESB_HOME>/repository/components/lib directory to <EI_HOME>/lib directory. 
    2. Copy <ESB_HOME>/repository/conf/datasources/master-datasources.xml file to <EI_HOME>/conf/datasources directory. This will update the datasource configuration in WSO2 EI.
    3. Go to the <EI_HOME>/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. 
  2. If there are any third-party libraries used with ESB 5.0.0 that you want to migrate, copy the contents of the following directories as applicable from ESB 5.0.0 to EI 6.0.0: 
    • If you have used JMS libraries, JDBC libraries, etc., copy the files from <ESB_HOME>/repository/components/lib directory to <EI_HOME>/lib directory.
    • If you have used OSGi bundles such as SVN kit etc., copy the contents of <ESB_HOME>/repository/components/dropins directory to <EI_HOME>/dropins directory.
  3. Check for any other configurations that were done for ESB 5.0.0 based on your solution and update the configuration files in EI 6.0.0 accordingly. For example, configurations related to external user stores, caching, mounting, transports, etc.

    Note

    The following files have changed from ESB 5.0.0 to EI 6.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
    • synapse-handlers.xml
    • user-mgt.xml
    • jndi.properties

    Do not copy and paste the configuration files as there are some changes from ESB 5.0.0 to EI 6.0.0. You need to update the configuration files based on the usage.

Migrating artifacts

You should manually deploy Composite Application Archive (CAR) files that you have in ESB 5.0.0 to EI 6.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 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/synapse-configs/default directory of ESB 5.0.0 to EI 6.0.0.

If you have created a messages store in your configuration and configured the provider path as repository/conf/jndi.properties in your ESB 5.0.0 instance, this needs to be updated with the jndi.properties file path in EI 6.0.0. To do this, edit the message store artifact so that the provider path is configured as conf/jndi.properties.

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.

Migrating tenant artifacts

If multi-tenancy is used, copy the tenant artifacts from <ESB_HOME>/repository/tenants directory from ESB 5.0.0 to EI 6.0.0.

You may not be able to access the tenant domain after migrating to EI 6.0.0. To fix this issue, change the tenant’s main sequence located in <EI_HOME>/repository/tenants/1/synapse-configs/default/sequences/main.xml as below:

<sequence xmlns="http://ws.apache.org/ns/synapse" name="main">
   <in>
      <log/>
   </in>
   <out>
      <send/>
   </out>
</sequence>