This page walks you through the process of upgrading to WSO2 Enterprise Integrator (WSO2 EI) 6.1.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 should first upgrade to ESB 5.0.0 and then upgrade to WSO2 EI 6.1.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 profiles, see Default ports of WSO2 EI.
The distribution folder structure has changed from ESB 5.0.0 to WSO2 EI 6.1.0. The changes in the folder structure for directory locations are as follows:
Enterprise Service Bus 5.0.0 Enterprise Integrator 6.1.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
See the following topics for instructions:
Upgrading the database
In WSO2 EI 6.1.0, you can use the same databases that you used for WSO2 ESB 5.0.0. Therefore, you can simply restore the backup of the existing databases to use with WSO2 EI 6.1.0.
Migrating the configurations
Configurations should not be copied directly between servers.
Migrating configuration for the Integration profile
Follow the steps given below to migrate the configurations from WSO2 ESB 5.0.0 to the Integration profile of WSO2 EI 6.1.0.
- Copy the database connector JAR files stored in the
<ESB_HOME>/repository/components/lib
directory to the<EI_HOME>/lib
directory. - Copy the keystores and truststores used in WSO2 ESB 5.0.0 from the
<ESB_HOME>/repository/resources/security
directory to the<EI_HOME>/repository/resources/security
directory in WSO2 EI 6.1.0. - Update the configuration files:
- Update the configuration files with information of the migrated keystores and truststores. See Configuring Keystores in WSO2 products for more information.
- Go to the
<EI_HOME>/conf/datasources
directory and update the Carbon datasource configuration in themaster-
datasources.
xml file with the details of the Carbon database. Go to the
<EI_HOME>/conf
directory and update the datasource references in theuser-mgt.xml
andregistry.xml
files to match the updated configurations in themaster-datasources.xml
file.
- If you have secondary user stores created for WSO2 ESB 5.0.0, you need to copy the 'userstore' folder in the
<ESB_HOME>/repository/deployment/server/
directory to the<EI_HOME>/repository/deployment/server/
directory in WSO2 EI 6.1.0. - If there are any third-party libraries used with WSO2 ESB 5.0.0 that you want to migrate, copy them to WSO2 EI 6.1.0:
- If you have used JMS libraries, JDBC libraries, etc., copy the files from the
<ESB_HOME>/repository/components/lib
directory to the<EI_HOME>/lib
directory. - If you have used OSGi bundles such as SVN kit etc., copy the contents of the
<ESB_HOME>/repository/components/dropins
directory to the<EI_HOME>/dropins
directory.
- If you have used JMS libraries, JDBC libraries, etc., copy the files from the
Check for any other configurations that were done for WSO2 ESB 5.0.0 based on your solution, and update the configurations in WSO2 EI 6.1.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 WSO2 EI 6.1.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.1.0. You need to update the configuration files based on the usage.
Migrating configurations of ESB Analytics to WSO2 EI Analytics
Note that the following migration is necessary only if ESB Analytics was used in your previous installation.
Follow the steps given below.
- Copy the database connector JAR files stored in the
<ESB_ANALYTICS_HOME>/repository/components/lib
directory of WSO2 ESB Analytics 5.0.0 to the<EI_HOME>/wso2/analytics/repository/components/lib
directory of the Analytics profile in WSO2 EI 6.1.0. - Copy the keystores and truststores used in WSO2 ESB Analytics 5.0.0 from the
<ESB_ANALYTICS_HOME>/repository/resources/security
directory of WSO2 ESB Analytics 5.0.0 to the<EI_HOME>/wso2/analytics/repository/resources/security
directory in WSO2 EI 6.1.0. - Update the configuration files.
- Update the configuration files with information of the migrated keystores and truststores. See Configuring Keystores in WSO2 products for more information.
- Go to the
<EI_HOME>/wso2/analytics/conf/datasources
directory and update the Carbon datasource configuration in themaster-
datasources.
xml file with the details of the Carbon database. - Go to the
<EI_HOME>/wso2/analytics/conf/datasources
directory and update the datasource configuration in theanalytics-
datasources.
xml file with the details of the Analytics-specific databases. - Go to the
<EI_HOME>/wso2/analytics/conf
directory and update the datasource references in theuser-mgt.xml
andregistry.xml
files to match the updated configurations in themaster-datasources.xml
file. - Go to the
<EI_HOME>/wso2/analytics/conf/analytics/
directory and update therdbms-config.xml
file according to the configurations in the same file of your previous Analytics installation. - Go to the <
EI_HOME>/wso2/analytics/conf/data-bridge
directory in WSO2 EI 6.1.0 and update the configuration files according to the configurations in the previous installation. Go to the
<EI_HOME>/wso2/analytics/conf
directory and update theevent-processor.xml
file according to the configurations in the previous installation.If you enable the HA mode for ESB Analytics by setting the
<mode name="HA" enable="true">
property in theevent-processor.xml
file, state persistence is enabled by default. If there is no real-time use case that requires any state information after starting the cluster, you should disable event persistence by setting thepersistence
attributetofalse
in the same file as shown below.<persistence enable="false"> <persistenceIntervalInMinutes>15</persistenceIntervalInMinutes> <persisterSchedulerPoolSize>10</persisterSchedulerPoolSize> <persister class="org.wso2.carbon.event.processor.core.internal.persistence.FileSystemPersistenceStore"> <property key="persistenceLocation">cep_persistence</property> </persister> </persistence>
- If you have secondary user stores created for WSO2 ESB Analytics 5.0.0, you need to copy the 'userstore' folder in the
<ESB_ANALYTICS_HOME>/repository/deployment/server/
directory to the<EI_ANALYTICS_HOME>/wso2/analytics/repository/deployment/server/
directory in WSO2 EI 6.1.0. - Check for any other configurations that were done for WSO2 ESB Analytics 5.0.0 based on your solution and update the configurations in WSO2 EI 6.1.0 accordingly. For example, configurations related to external user stores, caching, mounting, transports etc.
Migrating artifacts
You should manually deploy the Composite Application Archive (CAR) files that you have in WSO2 ESB 5.0.0 to WSO2 EI 6.1.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 administration guide for further details.
- To migrate deployment artifacts including message flow configurations, copy the required Synapse artifacts from the
<ESB_HOME>/repository/deployment/server/synapse-configs/default
directory of WSO2 ESB 5.0.0 to WSO2 EI 6.1.0. - To migrate any connector artifacts:
- Create a folder named
synapse-libs
in the<PRODUCT_HOME>/repository/deployment/server/synapse-configs/default/
directory of WSO2 EI 6.1.0, and copy the JARs from the directory by the same name in WSO2 ESB 5.0.0. Note that this directory will not exist in your ESB distribution if no connectors are used. - Copy the JARs from the
<PRODUCT_HOME>/repository/deployment/server/synapse-configs/default/imports
directory in WSO2 ESB 5.0.0 to the same directory in WSO2 EI 6.1.0.
- Create a folder named
- If you have custom artifacts created in the
<ESB_HOME>/repository/deployment/server/
directory of WSO2 ESB 5.0.0, copy them to the same directory in WSO2 EI 6.1.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.1.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 multitenancy is used,
Copy the tenant artifacts of ESB from the
<ESB_HOME>/repository/tenants
directory to the<EI_HOME>/repository/tenants
directory of WSO2 EI 6.1.0.You may not be able to access the tenant domain after migrating to WSO2 EI 6.1.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>
- If you are migrating ESB Analytics to the Analytics profile of WSO2 EI, copy the
<ESB_ANALYTICS_HOME>/repository/tenants
directory to the<EI_HOME>/wso2/analytics/repository/tenants
directory of WSO2 EI 6.1.0.
Starting the profiles
Once you have completed the migration, you can start the Integration profile of WSO2 EI. For details see Running the Product.