This page walks you through the process of upgrading to WSO2 Enterprise Integrator (EI) 6.6.0 from WSO2 EI 6.4.0. This covers the steps for upgrading all of the following profiles in WSO2 EI:
- For information on what is new in this release and why you should upgrade, see About this Release.
- For more information on ports, see Default Ports of WSO2 Enterprise Integrator.
- ESB profile
- Message Broker profile
- Business Process profile
- Analytics profile
See the following topics for details:
Preparing to upgrade
The following prerequisites must be completed before upgrading:
- Create a backup of the databases in your WSO2 EI 6.4.0 instance.
- Copy the
<EI_6.4.0_HOME>
directory to back up the product configurations. - Go to the WSO2 Integration website and download WSO2 EI 6.6.0.
- Install WSO2 EI 6.6.0.
The downtime is limited to the time taken for switching databases in the production environment.
ESB profile
Follow the instructions given below to upgrade the ESB profile from EI 6.4.0 to EI 6.6.0.
Upgrading the databases
You can use the same databases that you used for the ESB profile of EI 6.4.0 with EI 6.6.0. However, you need to apply the following updates.
Update the database structure
There may be changes in the database structure (schema) that is used in EI 6.6.0. To update the database schema:
- Download the database migration scripts.
- Unzip the downloaded file and select the script relevant to your database type.
- Connect to the database and run the script.
Your database schema is now updated for EI 6.6.0.
Update the data
You need to remove any instances of Message Processor Tasks that were stored in the registry database by EI 6.4.0.
EI 6.6.0 requires Message Processor Tasks to be stored in the registry using a new naming convention. The naming convention has changed from
TASK_PREFIX + messageProcessorName + taskNumber
(in EI 6.4.0) to TASK_PREFIX + messageProcessorName + SYMBOL_UNDERSCORE + taskNumber
(in EI 6.6.0).
When you run the migration client, the existing Task references in the registry will be removed. Later in this migration guide, when you migrate the integration artifacts from your EI 6.4.0 instance to EI 6.6.0, new records will be created in the registry with the new naming convention.
Step 1: Set up the WSO2 EI 6.6.0 server
Apply the following updates to your EI 6.6.0 server.
Connect the ESB profile of EI 6.6.0 to your existing databases (which are used for registry data and user management data):
Step 3: Run the migration client
Now, let's run the migration client from EI 6.6.0. This client changes any message processor data according to the new naming convention.
Create a folder named '
migration'
inside<EI_6.6.0_HOME>
.Copy the
migration-conf.properties
file to the<EI_6.6.0_HOME>/migration
folder and update the following properties:admin.user.name The user name of the system administrator. Note that you do not need to update the keystore-related properties given in the file.
- Download the migration JAR file and copy it to the
<EI_6.6.0_HOME>/dropins/
directory Open a terminal and navigate to the
<EI_6.6.0_HOME>/bin/
directory.Execute the product startup script with the '-Dmigrate.from.product.version=ei640' command as shown below.
Open a terminal and execute the following command:
sh integrator.sh -Dmigrate.from.product.version=ei640
Open a terminal and execute the following command:
integrator.bat -Dmigrate.from.product.version=ei640
- Once the migration is successful, stop the server and delete the migration JAR (
org.wso2.carbon.ei.migration-6.6.0.jar)
from the<EI_6.6.0_HOME>/dropins/
directory.
You can now migrate the configurations and artifacts for the ESB profile as explained below and start the ESB profile.
Migrating configurations of the ESB profile
Do not copy configuration files directly between servers. Instead, update the files manually.
To migrate all the required folders, files, libraries, etc. from EI 6.4.0 to EI 6.6.0:
- Copy the database connector JAR files stored in the
<EI_6.4.0_HOME>/lib
directory to the same directory in EI 6.6.0. Copy the keystores and truststores used in the ESB profile of WSO2 EI 6.4.0 from the
<EI_6.4.0_HOME>/repository/resources/security
directory to the same directory in WSO2 EI 6.6.0.- If you have secondary user stores created for the ESB profile of EI 6.4.0, you need to copy the 'userstore' folder in the
<EI_6.4.0_HOME>/repository/deployment/server/
directory to the same directory in EI 6.6.0. - If there are any third-party libraries used with EI 6.4.0 that you want to migrate, copy the relevant libraries from EI 6.4.0 to EI 6.6.0:
- If you have used JMS libraries, JDBC libraries, etc., copy the contents from the
<EI_6.4.0_HOME>/lib
directory to the same directory in EI 6.6.0. - If you have used OSGi bundles such as SVN kit etc., copy the contents from the
<EI_6.4.0_HOME>/dropins
directory to the same directory in EI 6.6.0.
- If you have used JMS libraries, JDBC libraries, etc., copy the contents from the
To migrate the configurations from EI 6.4.0 to EI 6.6.0:
- Go to the
<EI_6.6.0_HOME>/conf/datasources
directory and update the Carbon datasource configuration in themaster-
datasources.
xml file. The instructions are available in Changing the Carbon Database . Go to the
<EI_6.6.0_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. The instructions are available in Changing the Carbon Database .Check for any other configurations that were done for EI 6.4.0 based on your solution, and update the configuration files in EI 6.6.0 accordingly. For example, check the configurations related to external user stores, caching, mounting, transports, etc.
- See the instructions on migrating log4j configurations for the ESB profile.
WSO2 EI no longer packs the smb provider by default. If you need to use the VFS SMB feature, you can download the jcifs-1.3.17.jar from here and then place it in <EI_6.6.0_HOME/lib directory. Please note that (since the above library is licensed under LGPL version 2.1) by downloading and installing the library you have to comply with the terms of LGPL version 2.1 and its restrictions as found in this page.
Migrating artifacts of the ESB profile
You should manually deploy the Composite Application Archive (C-APP) files that you have in EI 6.4.0 to EI 6.6.0.
If you have a class mediator packed in a CAR, all the artifacts using that mediator should also be included in the same CAR.
- To migrate mediation artifacts including message flow configurations, copy the required Synapse artifacts from the
<EI_6.4.0_HOME>/repository/deployment/server/synapse-configs/default
directory to the same directory in EI 6.6.0. - To migrate connector artifacts:
- Create a folder named
synapse-libs
in the<EI_6.6.0_HOME>/repository/deployment/server/synapse-configs/default/
directory of EI 6.6.0, and copy the JARs from the directory by the same name in EI 6.4.0. Note that this directory will not exist in your EI 6.4.0 distribution if no connectors are used. - Copy the JARs from the
<EI_6.4.0_HOME>/repository/deployment/server/synapse-configs/default/imports
directory to the same directory in EI 6.6.0.
- Create a folder named
- To migrate the data service artifacts, copy the
<EI_6.4.0_HOME>/repository/deployment/server/dataservices
directory to the same directory in EI 6.6.0. - If you have custom artifacts created in the
<EI_6.4.0_HOME>/repository/deployment/server/
directory, copy them to the same directory in EI 6.6.0. - If multitenancy is used, copy the tenant artifacts from the
<EI_6.4.0_HOME>/repository/tenants
directory to the same directory in EI 6.6.0.
Analytics profile
If you have configured EI 6.4.0 to publish ESB data to the Analytics profile, you need to enable the same in EI 6.4.0. To do this, follow the instructions in Publishing ESB Data to Analytics.
Note that from EI 6.6.0 onwards, you need to configure the <EI_6.6.0_HOME>/conf/carbon.xml
file to enable the ESB server to publish statistics to the Analytics profile, whereas in the EI 6.4.0 and older versions you need to configure the<EI_HOME>/repository/deployment/server/eventpublishers/MessageFlowConfigurationPublisher.xml
and <EI_HOME>/repository/deployment/server/eventpublishers/MessageFlowStatisticsPublisher.xml
files instead.
Message Broker profile
Follow the instructions given below to upgrade the Message Broker profile from EI 6.4.0 to EI 6.6.0.
Migrating configurations of the Message Broker profile
Do not copy configuration files directly between servers. Instead, update the files manually.
To migrate all the required folders, files, libraries, etc. from EI 6.4.0 to EI 6.6.0:
- Copy the database connector JAR files stored in the
<EI_6.4.0_HOME>/lib
directory to the same directory EI 6.6.0. - Copy the keystores and truststores used in the Message Broker profile of EI 6.4.0 from the
<EI_6.4.0_HOME>/wso2/broker/repository/resources/security
directory to the same directory in EI 6.6.0. - If you have secondary user stores created for the Message Broker profile of EI 6.4.0, you need to copy the 'userstore' folder in the
<EI_6.4.0_HOME>/wso2/broker/repository/deployment/server/
directory to the same directory in EI 6.6.0.
To migrate the configurations from EI 6.4.0 to EI 6.6.0:
Update the configuration files with information of the migrated keystores and truststores. For instructions, see Configuring Keystores in WSO2 Products.
Go to the
<EI_6.6.0_HOME>/wso2/broker/conf/datasources
directory and update the Carbon datasource configuration in themaster-
datasources.
xml file. The instructions are available in Changing the Carbon Database .Update the configurations related to the broker-specific database in the
master-datasources.xml
file and other related configurations files. See Changing the Default Broker Database for instructions.- Go to the
<EI_6.6.0_HOME>/wso2/broker/conf
directory and update the datasource references in theuser-mgt.xml
andregistry.xml
files to match the updated configurations in themaster-datasources.xml
file. The instructions are available in Changing the Carbon Database . Check for any further configurations that were done for the Message Broker profile in EI 6.4.0 based on your solution. For example, check and update the following configurations in the Message Broker profile of EI 6.6.0:
broker.xml
metrics.xml
metrics-properties.xml
messaging-event-broker.xml
Check configurations related to external user stores, caching, mounting, transports etc.
- See the instructions on migrating log4j configurations for the Message Broker profile.
Migrating artifacts of the Message Broker profile
If multitenancy is used, copy the tenant artifacts from the <EI_6.4.0_HOME>/wso2/broker/repository/tenants
directory to the same directory in EI 6.6.0.
Business Process profile
Follow the instructions given below to upgrade the Business Process profile from EI 6.4.0 to EI 6.6.0.
Migrating configurations of the Business Process profile
Do not copy configuration files directly between servers. Instead, update the files manually.
To migrate all the required folders, files, libraries, etc. from EI 6.4.0 to EI 6.6.0:
Copy the database connector JAR files stored in the
<EI_6.4.0_HOME>/lib
directory to the same directory in EI 6.6.0. For example, the JAR for the Oracle database (ojdbc7.jar
) can be copied.- Copy the keystores and truststores used in the Business Process profile of EI 6.4.0 from the
<EI_6.4.0_HOME>/wso2/business-process/repository/resources/security
directory to the same directory in EI 6.6.0. - If you have secondary user stores created for the Business Process profile of EI 6.4.0, you need to copy the 'userstore' folder in the
<EI_6.4.0_HOME>/wso2/business-process/repository/deployment/server/
directory to the same directory in EI 6.6.0.
To migrate the configurations from EI 6.4.0 to EI 6.6.0:
- Update the configuration files with information of the migrated keystores and truststores. For more information, see Configuring Keystores in WSO2 Products.
- Go to the
<EI_6.6.0_HOME>/wso2/business-process/conf/datasources
directory and update the Carbon datasource configuration in themaster-
datasources.
xml file. The instructions are available in Changing the Carbon Database . - Go to the
<EI_6.6.0_HOME>/wso2/business-process/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_6.6.0_HOME>/wso2/business-process/conf/datasources
directory and update the files relevant to your BPMN/BPEL database:- If you are using BPMN, update the
activiti-datasources.xml
file with the datasource connection details. - If you are using BPEL, update the
bps-datasources.xml
file with the datasource connection details.
- If you are using BPMN, update the
Open the
<EI_6.6.0_HOME>/wso2/business-process/conf/humantask.xml
file and changeGenerateDdl
tofalse
. You can see the deployed human task packages with the version in the console. A migration success message is printed once the migration completes successfully.<GenerateDdl>false</GenerateDdl>
Check for any further configurations that were done for the Business Process profile of EI 6.4.0 based on your solution. For example, check and update the following configurations in EI 6.6.0:
humantask.xml
axis2.xml
bps.xml
Activiti.xml
Tenant-mgt.xml
b4p-coordination-config.xml
process-cleanup.properties
Check the configurations related to external user stores, caching, mounting, transports, etc.
- See the instructions on migrating log4j configurations for the Business Process profile.
Migrating artifacts of the Business Process profile
Follow the steps given below:
- Copy the BPEL .zip packages in the
<EI_6.4.0_HOME>/wso2/business-process/repository/deployment/server/bpel
directory to the same directory in EI 6.6.0. Copy the BPMN .bar packages in the
<EI_6.4.0_HOME>/wso2/business-process/repository/deployment/server/bpmn
directory to the same directory in EI 6.6.0.- Copy the humantask .zip packages in the
<EI_6.4.0_HOME>/wso2/business-process/repository/deployment/server/humantasks
directory to the same directory in EI 6.6.0. - If you have custom artifacts created in the
<EI_6.4.0_HOME>/wso2/business-process/repository/deployment/server/
directory, copy them to the same directory in EI 6.6.0. - If multitenancy is used, copy the tenant artifacts from the
<EI_6.4.0_HOME>/wso2/business-process/repository/tenants
directory to the same directory in EI 6.6.0.
Migrating Log4j configurations
All profiles of EI 6.6.0 use log4j2 instead of log4j. Therefore, the following configurations apply to all profiles of WSO2 EI.
EI 6.6.0 is based on Carbon Kernel 4.5.0, which introduces log4j2. Also, the carbon.logging jar is not packed with the EI 6.6.0 distribution and the pax-logging-api is used instead.
Follow the instructions given below to migrate from log4j (in EI 6.4.0) to log4j2 (in EI 6.6.0).
If you have used a custom log4j component in EI 6.4.0, apply the following changes to your component:
Replace carbon logging or
commons.logging
dependencies with pax-logging dependency as shown below.<!-- Pax Logging --> <dependency> <groupId>org.ops4j.pax.logging</groupId> <artifactId>pax-logging-api</artifactId> <version>${pax.logging.api.version}</version> </dependency> <!-- Pax Logging Version --> <pax.logging.api.version>1.10.1</pax.logging.api.version>
If log4j dependency is directly used, apply one of the options given below.
Replace the log4j dependency (shown below) with log4j2 and rewrite the loggers accordingly.
<dependency> <groupId>org.ops4j.pax.logging</groupId> <artifactId>pax-logging-log4j2</artifactId> <version>${pax.logging.log4j2.version}</version> </dependency>
Replace the log4j dependency with pax-logging dependency and rewrite the loggers using
commons.logging
accordingly.If
commons.logging
is imported using Import-Package add the version range.org.apache.commons.logging; version="${commons.logging.version.range}" <commons.logging.version.range>[1.2.0,2.0.0)</commons.logging.version.range>
- Follow the instructions on configuring log4j2 to register the Appenders and Loggers.
Starting the profiles
You can now start the EI 6.6.0 product. For instructions on starting each of the profiles in the product, see Running the Product.