This documentation is for WSO2 Enterprise Integrator version 6.2.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.2.0 from WSO2 EI 6.1.1. This will cover 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 Products in the WSO2 Administration Guide. The default ports in WSO2 EI are listed under 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.1.1 instance.
  • Copy the <EI_6.1.1_HOME> directory to back up the product configurations.
  • Go to the WSO2 Integration product page, click Download → Previous Releases. You can now download WSO2 EI 6.2.0 version.

    Note that there are several options for installing the product.

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

Upgrading the databases

You can use the same databases that you used for WSO2 EI 6.1.1 with WSO2 EI 6.2.0. However, you need to apply the changes discussed below. Once these changes are done, you can connect your WSO2 EI 6.2.0 instances to the old databases.

Upgrading databases for the ESB profile

As per the Security Advisory (WSO2-2017-0345), WSO2 EI 6.2.0 uses OAEP for data encryption in addition to the RSA algorithm (which is used in the ESB profile of WSO2 EI 6.1.1). Therefore, the internally-encrypted data in your current databases (such as datasource configurations, syslog passwords, user store configurations, keystore registry entries, service security policies, event publisher configurations, event receiver configurations, and event sink configurations), as well as data encrypted using secure vault (such as plain text passwords in configuration files and synapse configurations) should be re-encrypted using OAEP. 

  • To re-encrypt all internally-encrypted data using OAEP:

    1. Get the latest WUM updates (later than the update level released on 18/04/2018) for your WSO2 EI 6.1.1. This will give you a new WSO2 EI distribution with the latest updates.

    2. Connect the WUM-updated WSO2 EI distribution to your existing databases (which are used for registry data, and user management data):

       Connecting to the database
      1. Open the master-datasources.xml file (stored in the <WUM_UPDATED_EI_6.1.1_HOME>/conf/datasources/ directory) and update the parameters given below.

        By default, registry and user management data are stored in one database and is configured in the master-datasources.xml file. If you have separate databases for registry and user management data, you may have separate datasource configurations.

        ElementDescription
        urlThe URL of the database.
        username and passwordThe name and password of the database user.
        driverClassNameThe class name of the database driver.
      2. Open the registry.xml file (stored in the <WUM_UPDATED_EI_6.1.1_HOME>/conf directory) and specify the datasource name.

        <dbConfig name="wso2registry">    
            <dataSource>jdbc/MY_DATASOURCE_NAME</dataSource>
        </dbConfig>
      3. If a JDBC user store is used in your ESB, open the user-mgt.xml file (stored in the <WUM_UPDATED_EI_6.1.1_HOME>/conf/ directory), and update the following database connection parameters under the <UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager"> section.

        ElementDescription
        urlThe URL of the database.
        username and passwordThe name and password of the database user.
        driverClassNameThe class name of the database driver.

        Further, update the system administrator configurations and the datasource name in the user-mgt.xml file.

      4. Encrypt the plain text passwords that you added to the configuration files (master-datasources.xml, user-mgt.xml, etc.).

    3. Be sure that the carbon.properties file is included in the <WUM_UPDATED_EI_6.1.1_HOME>/conf/ directory with the following parameter:

      org.wso2.CipherTransformation=RSA/ECB/OAEPwithSHA1andMGF1Padding
    4. Start the WUM-updated ESB server of WSO2 EI 6.1. This will re-encrypt the data in the databases.
  • To re-encrypt plain text strings using OAEP:
    1. Connect the ESB profile of WSO2 EI 6.2.0 to your existing databases (which are used for registry data, and user management data):

       Connecting to the database
      1. Open the master-datasources.xml file (stored in the <EI_HOME>/conf/datasources/ directory) and update the parameters given below.

        By default, registry and user management data are stored in one database and is configured in the master-datasources.xml file. If you have separate databases for registry and user management data, you may need separate datasource configurations.

        ElementDescription
        urlThe URL of the database.
        username and passwordThe name and password of the database user.
        driverClassNameThe class name of the database driver.
      2. Open the registry.xml file (stored in the <EI_HOME>/conf directory) and specify the datasource name (as defined in step a).

        <dbConfig name="wso2registry">    
            <dataSource>jdbc/MY_DATASOURCE_NAME</dataSource>
        </dbConfig>
      3. If a JDBC user store is used, open the user-mgt.xml file (stored in the <EI_HOME>/conf/ directory), and update the following database connection parameters under the <UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager"> section.

        ElementDescription
        urlThe URL of the database.
        username and passwordThe name and password of the database user.
        driverClassNameThe class name of the database driver.

        Further, update the system administrator configurations and the datasource name in the user-mgt.xml file.

    2. The keystores for WSO2 EI 6.2.0 need to be setup and configured in order to perform this data re-encryption. 
      1. Migrate the keystores and truststores from WSO2 EI 6.1.1 to WSO2 EI 6.2.0 by copying the files from the <EI_6.1.1_HOME>/repository/resources/security directory to the same directory in WSO2 EI 6.2.0.
      2. Open the carbon.xml file (stored in the <EI_HOME>/conf/ directory), and update the details of the keystore used for data encryption.

         Using a common keystore for data encryption and SSL signing?

        Update the following configuration element:

        <KeyStore>    
            <Location>${carbon.home}/resources/security/wso2carbon.jks</Location>
            <Type>JKS</Type>
            <Password>wso2carbon</Password>
            <KeyAlias>wso2carbon</KeyAlias>
            <KeyPassword>wso2carbon</KeyPassword>
        </KeyStore>
          
        <TrustStore>
            <!-- trust-store file location -->
            <Location>${carbon.home}/repository/resources/security/client-truststore.jks</Location>
            <!-- trust-store type (JKS/PKCS12 etc.) -->
            <Type>JKS</Type> 
            <!-- trust-store password -->
            <Password>wso2carbon</Password>
        </TrustStore>
         Using a separate keystore exclusively for data encryption?

        Note that this feature is available as an update for WSO2 EI 6.2.0 as explained Configuring Keystores in WSO2 Products.

        Add the following configuration element under <Security> in the carbon.xml file, and update the values:

        <InternalKeyStore>  <Location>${carbon.home}/repository/resources/security/internal.jks</Location>
          <Type>JKS</Type>
          <Password>wso2carbon</Password>
          <KeyAlias>wso2carbon</KeyAlias>
          <KeyPassword>wso2carbon</KeyPassword>
        </InternalKeyStore>
    3. Create the <EI_HOME>/migration/ directory, copy the migration-conf.properties file, and update the following values:

      keystore.identity.locationThe location of the keystore that is used for data encryption in the WSO2 EI 6.2.0. By default, this is <EI_HOME>/repository/resources/security/wso2carbon.jks.
      keystore.identity.key.passwordThe key password of the default keystore. By default, this is wso2carbon.
      admin.user.nameThe user name of the system administrator.
    4. Copy the migration JAR file to the <EI_HOME>/dropins/ directory.
    5. Start the ESB profile of WSO2 EI 6.2.0:

      1. Open a terminal and navigate to the <EI_HOME>/bin/ directory.

      2. Execute the product start up script with the '-Dmigrate' command as shown below.

        Open a terminal and execute the following command:

        sh integrator.sh -Dmigrate

        Open a terminal and execute the following command:

        integrator.bat -Dmigrate

       The relevant data is now re-encrypted.

    6. Once the migration is successful, stop the server and delete the migration JAR (org.wso2.carbon.ei.migration-6.2.0.jar) from the <EI_HOME>/dropins/ directory.

ESB profile

Follow the instructions given below to upgrade the ESB profile from WSO2 EI 6.1.1 to WSO2 EI 6.2.0.

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 WSO2 EI 6.1.1 to WSO2 EI 6.2.0:

  1. Copy the database connector JAR files stored in the <EI_6.1.1_HOME>/lib directory to the same directory in WSO2 EI 6.2.0.
  2. You need to migrate the keystores and truststores used in the ESB profile of WSO2 EI 6.1.1 from the <EI_6.1.1_HOME>/repository/resources/security directory to the same directory in WSO2 EI 6.2.0. 

    Note that you have already completed this keystore migration before upgrading the ESB databases.

  3. If you have secondary user stores created for the ESB profile of WSO2 EI 6.1.1, you need to copy the 'userstore' folder in the <EI_6.1.1_HOME>/repository/deployment/server/ directory to the same directory in WSO2 EI 6.2.0.
  4. If there are any third-party libraries used with WSO2 EI 6.1.1 that you want to migrate, copy the relevant libraries from WSO2 EI 6.1.1 to WSO2 EI 6.2.0: 
    • If you have used JMS libraries, JDBC libraries, etc., copy the contents from the <EI_6.1.1_HOME>/lib directory to the same directory in WSO2 EI 6.2.0.
    • If you have used OSGi bundles such as SVN kit etc., copy the contents from the <EI_6.1.1_HOME>/dropins directory to the same directory in WSO2 EI 6.2.0.

To migrate the configurations from WSO2 EI 6.1.1 to WSO2 EI 6.2.0:

  1. Update the configuration files with information of the migrated keystores and truststores. For instructions, see Configuring Keystores in WSO2 productsNote that some keystore configurations were already updated before upgrading the ESB databases.
  2. Go to the <EI_HOME>/conf/datasources directory and update the Carbon datasource configuration in the master-datasources.xml file. Note that some configurations in this file were already updated before upgrading the ESB databases. For instructions, see Changing the Carbon Database and select your database type.
  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. Note that some configurations in these files were already updated before upgrading the ESB databases. The instructions are available in Changing the Carbon Database.

  4. Check for any other configurations that were done for WSO2 EI 6.1.1 based on your solution, and update the configuration files in WSO2 EI 6.2.0 accordingly. For example, check the configurations related to external user stores, caching, mounting, transports, etc.

Migrating artifacts of the ESB profile

You should manually deploy the Composite Application Archive (C-APP) files that you have in WSO2 EI 6.1.1 to WSO2 EI 6.2.0.

  • To migrate mediation artifacts including message flow configurations, copy the required Synapse artifacts from the <EI_6.1.1_HOME>/repository/deployment/server/synapse-configs/default directory to the same directory in WSO2 EI 6.2.0.
  • To migrate connector artifacts: 
    • Create a folder named synapse-libs in the <EI_HOME>/repository/deployment/server/synapse-configs/default/ directory of WSO2 EI 6.2.0, and copy the JARs from the directory by the same name in WSO2 EI 6.1.1. Note that this directory will not exist in your WSO2 EI 6.1.1 distribution if no connectors are used.
    • Copy the JARs from the <EI_6.1.1_HOME>/repository/deployment/server/synapse-configs/default/imports directory to the same directory in WSO2 EI 6.2.0.
  • To migrate the data service artifacts, copy the <EI_6.1.1_HOME>/repository/deployment/server/dataservices directory to the same directory in WSO2 EI 6.2.0.
  • If you have custom artifacts created in the <EI_6.1.1_HOME>/repository/deployment/server/ directory, copy them to the same directory in WSO2 EI 6.2.0.
  • If multitenancy is used, copy the tenant artifacts from the <EI_6.1.1_HOME>/repository/tenants directory to the same directory in WSO2 EI 6.2.0:

Message Broker profile

Follow the instructions given below to upgrade the Message Broker profile from WSO2 EI 6.1.1 to WSO2 EI 6.2.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 WSO2 EI 6.1.1 to WSO2 EI 6.2.0:

  1. Copy the database connector JAR files stored in the <EI_6.1.1_HOME>/lib directory to the same directory WSO2 EI 6.2.0.
  2. Copy the keystores and truststores used in the Message Broker profile of WSO2 EI 6.1.1 from the <EI_6.1.1_HOME>/wso2/broker/repository/resources/security directory to the same directory in WSO2 EI 6.2.0.
  3. If you have secondary user stores created for the Message Broker profile of WSO2 EI 6.1.1, you need to copy the 'userstore' folder in the <EI_6.1.1_HOME>/wso2/broker/repository/deployment/server/ directory to the same directory in WSO2 EI 6.2.0.

To migrate the configurations from WSO2 EI 6.1.1 to WSO2 EI 6.2.0:

  1. Update the configuration files with information of the migrated keystores and truststores. For instructions, 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. See Changing the Carbon Database for instructions.

  3. 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.

  4. 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. The instructions are available in Changing the Carbon Database.
  5. Check for any further configurations that were done for the Message Broker profile in WSO2 EI 6.1.1 based on your solution. For example, check and update the following configurations in the Message Broker profile of WSO2 EI 6.2.0:

    1. broker.xml

    2. metrics.xml

    3. metrics-properties.xml

    4. messaging-event-broker.xml

    5. Check configurations related to external user stores, caching, mounting, transports etc.

Migrating artifacts of the Message Broker profile

If multitenancy is used, copy the tenant artifacts from the <EI_6.1.1_HOME>/wso2/broker/repository/tenants directory to the same directory in WSO2 EI 6.2.0.

Business Process profile

Follow the instructions given below to upgrade the Business Process profile from WSO2 EI 6.1.1 to WSO2 EI 6.2.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 WSO2 EI 6.1.1 to WSO2 EI 6.2.0:

  1. Copy the database connector JAR files stored in the <EI_6.1.1_HOME>/lib directory to the same directory in WSO2 EI 6.2.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.1.1 from the <EI_6.1.1_HOME>/wso2/business-process/repository/resources/security directory to the same directory in WSO2 EI 6.2.0.
  3. If you have secondary user stores created for the Business Process profile of WSO2 EI 6.1.1, you need to copy the 'userstore' folder in the <EI_6.1.1_HOME>/wso2/business-process/repository/deployment/server/ directory to the same directory in WSO2 EI 6.2.0.

To migrate the configurations from WSO2 EI 6.1.1 to WSO2 EI 6.2.0:

  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. For instructions, see Changing the Carbon Database and select your database type.
  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 fileThe instructions are available in Changing the Carbon Database.
  4. Go to the <EI_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.
    For instructions, see Changing the Default Databases for BPMN and BPEL.
  5. Open the <EI_HOME>/wso2/business-process/conf/humantask.xml file and change GenerateDdl to false. 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>
  6. Check for any further configurations that were done for the Business Process profile of WSO2 EI 6.1.1 based on your solution. For example, check and update the following configurations in WSO2 EI 6.2.0:

    1. humantask.xml

    2. axis2.xml

    3. bps.xml

    4. Activiti.xml

    5. Tenant-mgt.xml

    6. b4p-coordination-config.xml

    7. process-cleanup.properties

    8. Check the 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_6.1.1_HOME>/wso2/business-process/repository/deployment/server/bpel directory to the same directory in WSO2 EI 6.2.0.
  • Copy the BPMN .bar packages in the <EI_6.1.1_HOME>/wso2/business-process/repository/deployment/server/bpmn directory to the same directory in WSO2 EI 6.2.0. 

  • Copy the humantask .zip packages in the <EI_6.1.1_HOME>/wso2/business-process/repository/deployment/server/humantasks directory to the same directory in WSO2 EI 6.2.0.
  • If you have custom artifacts created in the <EI_6.1.1_HOME>/wso2/business-process/repository/deployment/server/ directory, copy them to the same directory in WSO2 EI 6.2.0.
  • If multitenancy is used, copy the tenant artifacts from the <EI_6.1.1_HOME>/wso2/business-process/repository/tenants directory to the same directory in WSO2 EI 6.2.0.

Analytics profile

Follow the instructions given below to upgrade the Analytics profile from WSO2 EI 6.1.1 to WSO2 EI 6.2.0.

Migrating configurations of the Analytics profile

Follow the steps given below.

  1. Copy the database connector JAR files stored in the <EI_HOME>/lib directory of WSO2 EI 6.1.1 to WSO2 EI 6.2.0.
  2. Copy the keystores and truststores used in the Analytics profile of WSO2 EI 6.1.1 from the <EI_HOME>/wso2/analytics/repository/resources/security directory of WSO2 EI 6.1.1 to the same directory in WSO2 EI 6.2.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/analytics/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/analytics/conf/datasources directory and update the datasource configuration in the analytics-datasources.xml file with the details of the Analytics-specific databases.
    4. Go to the <EI_HOME>/wso2/analytics/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.
    5. Go to the <EI_HOME>/wso2/analytics/conf/analytics/ directory and update the rdbms-config.xml file according to the configurations in the same file of your previous Analytics installation.
    6. Go to the <EI_HOME>/wso2/analytics/conf/data-bridge directory in WSO2 EI 6.2.0 and update the configuration files according to the configurations in the previous installation.
    7. Go to the <EI_HOME>/wso2/analytics/conf directory in WSO2 EI 6.2.0 and update the event-processor.xml file according to the configurations in the previous installation.

      If you enable the HA mode for the Anlytics profile by setting the <mode name="HA" enable="true"> property in the event-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 the persistence attributeto false 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>
  4. If you have secondary user stores created for the Analytics profile of WSO2 EI 6.1.1, you need to copy the 'userstore' folder in the <EI_6.1.1_HOME>/wso2/analytics/repository/deployment/server/ directory to the same directory in WSO2 EI 6.2.0.
  5. Check for any other configurations that were done for the Analytics profile of WSO2 EI 6.1.1 based on your solution and update the configurations in WSO2 EI 6.2.10 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/analytics/repository/tenants directory of WSO2 EI 6.1.1 to WSO2 EI 6.2.0.

Starting the profiles

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

  • No labels