This documentation is for WSO2 Enterprise Integrator version 6.4.0 . View documentation for the latest release in the 6.x.x family and the latest release in the 7.x.x family.

All docs This doc
||
Skip to end of metadata
Go to start of metadata

This page walks you through the process of upgrading to WSO2 Enterprise Integrator (WSO2 EI) 6.4.0 from WSO2 EI 6.3.0. This will cover the steps for upgrading all the following profiles in WSO2 EI:

  • ESB profile
  • Message Broker profile
  • Business Process profile
  • Analytics profile
  • 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 Products in the WSO2 Administration Guide. The default ports in WSO2 EI are listed under Enterprise Integrator.

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.3.0 instance.
  • Copy the <EI_6.3.0_HOME> directory to back up the product configurations.
  • Download the product installer from here, and run the installer.
    Let's call the installation location of your product the <EI_HOME> directory. This is located in a place specific to your OS as shown below:
    OSHome directory
    Mac OS/Library/WSO2/EnterpriseIntegrator/6.4.0
    WindowsC:\Program Files\WSO2\EnterpriseIntegrator\6.4.0\
    Ubuntu/usr/lib/wso2/EnterpriseIntegrator/6.4.0
    CentOS/usr/lib64/EnterpriseIntegrator/6.4.0

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

Upgrading the databases

In WSO2 EI 6.4.0, you can use the same databases that you used for the profiles in WSO2 EI 6.3.0. Therefore, you can simply restore the backup of the existing Carbon databases to use with WSO2 EI 6.4.0.

ESB profile

Follow the steps given below to upgrade the ESB profile from WSO2 EI 6.3.0 to EI 6.4.0.

Migrating configurations of the ESB profile

Do not copy configurations directly between servers.

Follow the steps given below:

  1. Copy the database connector JAR files stored in the <EI_HOME>/lib directory of WSO2 EI 6.3.0 to WSO2 EI 6.4.0.
  2. Copy the keystores and truststores used in the ESB profile of WSO2 EI 6.3.0 from the <EI_HOME>/repository/resources/security directory of WSO2 EI 6.3.0 to the same directory in WSO2 EI 6.4.0.
  3. Update the configuration files:
    1. Update the configuration files with information of the migrated keystores and truststores. For more information, see Configuring Keystores in WSO2 products.
    2. Go to the <EI_HOME>/conf/datasources directory and update the Carbon datasource configuration in the master-datasources.xml file with the details of the Carbon database.
    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.

  4. If you have secondary user stores created for the ESB profile of WSO2 EI 6.3.0, you need to copy the 'userstore' folder in the <EI_6.3.0_HOME>/repository/deployment/server/ directory to the same directory in WSO2 EI 6.4.0.
  5. Check for any other configurations that were done for WSO2 EI 6.3.0 based on your solution and update the configurations in WSO2 EI 6.4.0 accordingly. For example, configurations related to external user stores, caching, mounting, transports, etc.

  6. If there are any third-party libraries used with WSO2 EI 6.4.0 that you want to migrate, copy the relevant libraries from WSO2 EI 6.3.0 to WSO2 EI 6.4.0: 
    • If you have used JMS libraries, JDBC libraries, etc., copy the contents from <EI_HOME>/lib.
    • If you have used OSGi bundles such as SVN kit etc., copy the contents from <EI_HOME>/dropins.
Migrating artifacts of the ESB profile
  • Migrating the CAR files that you created for 6.3.0:
    Copy the CAR from the <EI_HOME>/repository/deployment/server/carbonapps directory from WSO2 EI 6.3.0 to the same directory of EI 6.4.0.
  • Migrating deployment artifacts including message flow configurations:
    Copy the required Synapse artifacts from the <EI_HOME>/repository/deployment/server/synapse-configs/default directory from WSO2 EI 6.3.0 to the same directory of 6.4.0.
  • Migrating connector artifacts: 
    • Create a folder named synapse-libs  in the  <PRODUCT_HOME>/repository/deployment/server/synapse-configs/default/ directory of WSO2 EI 6.4.0, and  copy the JARs from the directory by the same name in WSO2 EI 6.3.0. Note that this directory will not exist in your WSO2 EI 6.3.0 distribution if no connectors are used.
    • Copy the JARs from the <PRODUCT_HOME>/repository/deployment/server/synapse-configs/default/imports directory in WSO2 EI 6.3.0 to the same directory in WSO2 EI 6.4.0.
  • Migrating the data service artifacts:
    Copy the <EI_HOME>/repository/deployment/server/dataservices directory of WSO2 EI 6.3.0 to WSO2 EI 6.4.0.

  • If you have custom artifacts created in the <EI_HOME>/repository/deployment/server/ directory of WSO2 EI 6.3.0, copy them to the same directory in WSO2 EI 6.4.0.
Migrating tenant artifacts

If multitenancy is used, copy the <EI_HOME>/repository/tenants directory of WSO2 EI 6.3.0 to WSO2 EI 6.4.0.

Message Broker profile

Follow the steps given below to upgrade the Message Broker profile from WSO2 EI 6.3.0 to EI 6.4.0.

Migrating configurations of the Message Broker profile

Do not copy configurations directly between servers.

Follow the steps below:

  1. Copy the database connector JAR files stored in the <EI_HOME>/lib directory of WSO2 EI 6.3.0 to WSO2 EI 6.4.0.
  2. Copy the keystores and truststores used in the Message Broker profile of WSO2 EI 6.3.0 from the <EI_HOME>/wso2/broker/repository/resources/security directory of WSO2 EI 6.3.0 to the same directory in WSO2 EI 6.4.0.
  3. Update the configuration files.

    1. Update the configuration files with information of the migrated keystores and truststores. For more information, see Configuring Keystores in WSO2 products.

    2. Go to the <EI_HOME>/wso2/broker/conf/datasources directory and update the Carbon datasource configuration in the master-datasources.xml file.

      Note that you need to update the datasource details for the Carbon database as well as the broker-specific database in the master-datasources.xml file.

    3. Go to the <EI_HOME>/wso2/broker/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.
    4. Check for any further configurations that were done for the Message Broker profile in WSO2 EI 6.3.0 based on your solution, and update the following configuration files in EI 6.4.0 accordingly:

      • broker.xml

      • metrics.xml

      • metrics-properties.xml

      • messaging-event-broker.xml

  4. If you have secondary user stores created for the Message Broker profile of WSO2 EI 6.3.0, you need to copy the 'userstore' folder in the <EI_6.3.0_HOME>/wso2/broker/repository/deployment/server/ directory to the same directory in WSO2 EI 6.4.0.

  5. Check for any other configurations that were done for the Message Broker profile of WSO2 EI 6.3.0 based on your solution and update the configurations in WSO2 EI 6.4.0 accordingly. For example, configurations related to external user stores, caching, mounting, transports etc.
Migrating tenant artifacts

If multitenancy is used, copy the <EI_HOME>/wso2/broker/repository/tenants directory of WSO2 EI 6.3.0 to WSO2 EI 6.4.0.

Business Process profile

Follow the steps given below to upgrade the Business Process profile from WSO2 EI 6.3.0 to EI 6.4.0.

Migrating configurations of the Business Process profile

Do not copy configurations directly between servers.

Follow the steps below:

  1. Copy the database connector JAR files stored in the <EI_HOME>/lib directory of WSO2 EI 6.3.0 to WSO2 EI 6.4.0. For example, the JAR for the Oracle database (ojdbc7.jar) can be copied.

  2. Copy the keystores and truststores used in the Business Process profile of WSO2 EI 6.3.0 from the <EI_HOME>/wso2/business-process/repository/resources/security directory of WSO2 EI 6.3.0 to the same directory in WSO2 EI 6.4.0.
  3. Update the configuration files.
    1. Update the configuration files with information of the migrated keystores and truststores. For more information, see Configuring Keystores in WSO2 products.
    2. Go to the <EI_HOME>/wso2/business-process/conf/datasources directory and update the Carbon datasource configuration in the master-datasources.xml file with the details of the Carbon database.
    3. Go to the  <EI_HOME>/wso2/business-process/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.
    4. Go to the <EI_HOME>/wso2/business-process/conf/datasources directory and update the activiti-datasources.xml file with details of the datasource connection to the BPMN database.
    5. Go to the <EI_HOME>/wso2/business-process/conf/datasources directory and update the bps-datasources.xml file with details of the datasource connection to the BPEL database.
    6. Open the <EI_HOME>/wso2/business-process/conf/humantask.xml file and change GenerateDdl to false. You can see the deployed humantask packages with the version in the console. A migration success message is printed once the migration completes successfully.

       <GenerateDdl>false</GenerateDdl>
    7. Check for any further configurations that were done for the Business Process profile of WSO2 EI 6.3.0 based on your solution and update the following configuration files in EI 6.4.0 accordingly:

      • humantask.xml

      • axis2.xml

      • bps.xml

      • Activiti.xml

      • Tenant-mgt.xml

      • b4p-coordination-config.xml

      • process-cleanup.properties

  4. If you have secondary user stores created for the Business Process profile of WSO2 EI 6.3.0, you need to copy the 'userstore' folder in the <EI_6.3.0_HOME>/wso2/business-process/repository/deployment/server/ directory to the same directory in WSO2 EI 6.4.0.
  5. Check for any other configurations that were done for the Business Process profile of WSO2 EI 6.3.0 based on your solution and update the configurations in WSO2 EI 6.4.0 accordingly. For example, configurations related to external user stores, caching, mounting, transports etc.
Migrating artifacts of the Business Process profile

Follow the steps given below:

  • Copy the BPEL .zip packages in the <EI_HOME>/wso2/business-process/repository/deployment/server/bpel directory of WSO2 EI 6.3.0 to 6.4.0.
  • Copy the BPMN .bar packages in the <EI_HOME>/wso2/business-process/repository/deployment/server/bpmn directory of WSO2 EI 6.3.0 to 6.4.0. 

  • Copy the humantask.zip packages in the <EI_HOME>/wso2/business-process/repository/deployment/server/humantasks directory of WSO2 EI 6.3.0 to 6.4.0.
  • If you have custom artifacts created in the <EI_HOME>/wso2/business-process/repository/deployment/server/ directory of WSO2 EI 6.3.0, copy them to the same directory in WSO2 EI 6.4.0.
Migrating tenant artifacts

If multitenancy is used, copy the <EI_HOME>/wso2/business-process/repository/tenants directory of WSO2 EI 6.3.0 to WSO2 EI 6.4.0.

Analytics profile

WSO2 EI Analytics is a profile within WSO2 EI that collects EI statistics such as successful and failed requests sent to proxies, REST APIs, sequences, mediators etc., analyzes them, and publishes the results in the EI Analytics dashboard. For more information, see Working with Analytics.

In EI 6.3.0 and previous versions, the EI Analytics profile is a solution designed on WSO2 Data Analytics Server. In EI 6.4.0 and later versions, the EI Analytics profile is designed on WSO2 Stream Processor. Based on this change, this section provides the instructions to follow when migrating the Analytics profiule when you are upgrading from EI 6.3.0 to EI 6.4.0.

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.

Overview

WSO2 Data Analytics Server is the predecessor of WSO2 Stream Processor. Similar to WSO2 SP, WSO2 DAS processed events via an event flow that consisted of event streams, receivers, publishers, and execution plans. These elements of the event flow are defined separate from each other via the DAS Management Console. WSO2 SP defines the complete event flow within a single application created via a Siddhi file. The application is then deployed in a SP worker node and executed at runtime.

In EI 6.4.0, the Siddhi application required to process EI statistics is already created and deployed in the SP-basedEI Analytics profile. Similarly, the required datasources to store data are pre-configured. This setup functions the same way the pre configured DAS artifacts functioned together in EI Analytics 6.4.0. Therefore, unless you have configured any custom DAS artifacts in your EI Analytics 6.3.0 setup, you do not need to migrate any artifacts. However, you need to setup the databases and migrate the analytics data that you have already saved in EI Analytics 6.3.0.

Upgrading the databases and migrating analytics-related data

The default databases for the SP-based Analytics profile in EI 6.4.0 are available in <EI_HOME>/wso2/analytics/wso2/<PROFILE>/database directory. However, you need to create the same databases and the tables that you currently have in the DAS-based  Analytics profile in EI 6.3.0, and then transfer the data that you have already saved in those. To do this, follow the procedure below:

  1. Fork the wos2/product-ei repository. Then download this repository from your fork.

    In the following steps, the directory that is downloaded into your machine is referred to as <PROJECT_HOME>.

  2. In your terminal, navigate to the <PROJECT_HOME>/distribution/src/analytics/migration/migration-EI6.x.x-6.4.0/resources/mig-ei-analytics sub directory and issue the following command.

    mvn clean install

    As a result, a new JAR named migEI.one-jar.jar is created inside the <PROJECT_HOME>/distribution/src/analytics/migration/migration-EI6.x.x-6.4.0/resources/mig-ei-analytics/target sub directory. The dependencies of this JAR are also created within the same sub directory.

  3. Copy the migEIAnalytics.bat and migEIAnalytics.sh files from the <PROJECT_HOME>/distribution/src/analytics/migration/migration-EI6.x.x-6.4.0/resources sub directory and place them in the <PROJECT_HOME>/distribution/src/analytics/migration/migration-EI6.x.x-6.4.0/resources/mig-ei-analytics/target sub directory.
  4. Navigate to the <PROJECT_HOME>/distribution/src/analytics/migration/migration-EI6.x.x-6.4.0/resources/mig-ei-analytics/target sub directory, and execute the Analytics migration script by issuing one of the following commands.
    • For Windows: migEIAnalytics.bat
    • For Linux: /migEIAnalytics.sh

    Once you issue the command, the following appears in your terminal.

    Enter the required database type. This should be the same database that is configured for WSO2 EI Analytics 6.4.0. The system creates the tables related to EI Analytics in the database you specified.
  5. To run the Analytics profile of WSO2 EI 6.3.0, open the terminal, navigate to the <EI-6.3.0_HOME>/wso2/analytics/bin directory and issue the following command.
    /wso2server.sh
  6. To migrate data related to the Analytics profile, navigate to the <PROJECT_HOME>/distribution/src/analytics/migration/migration-EI6.x.x-6.4.0/resources sub directory and execute the migEIAnalyticsSpark.sql Spark script. As a result, the migrated data is stored in the RDBMS database that you specified in step 4.

Migrating custom deployable artifacts

If you have created any custom DAS artifacts in your WSO2 EI 6.3.0 Analytics profile, you need to add them in the WSO2 EI 6.4.0 Analytics profile. For detailed instructions, see WSO2 Stream Processor Documentation - Upgrading from a previous release - Deployable artifacts.

Testing the migration

To test whether the EI Analytics profile is successfully migrated, follow the steps below:

  1. To start the Analytics profile of WSO2 EI 6.4.0, navigate to the <EI-6.4.0_HOME>/wso2/analytics/bin directory and issue the following command.
    • For Windows: worker.bat
    • For Linux: /worker.sh
  2. To view the migrated statistics, start the EI Analytics dashboard by navigating to the <EI-6.4.0_HOME>/wso2/analytics/bin directory and issuing the following command.
    • For Windows: dashboard.bat
    • For Linux: /dashboard.sh
    Once you run one of these scripts, you can access the dashboard via the dashboard URL displayed in the terminal.
  3. Run the EI Product and send a request to populate data to aggregation tables. Then check whether the statistics displayed in the Analytics dashboard are updated with the new requests.

Starting the profiles

You can now start the WSO2 EI 6.4.0 product. For instructions on starting each of the profiles in the product, see Running the Product.

  • No labels