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.5.0 from WSO2 Business Process Server (WSO2 BPS) 3.6.0.

Before you begin, note the following:

  • If you are upgrading from a version older than WSO2 BPS 3.6.0, you should first upgrade to WSO2 BPS 3.6.0 and then upgrade to WSO2 EI 6.5.0.
  • For information on what is new in this release and why you should upgrade, see About this Release.
  • See Default ports of WSO2 Products for more information on ports. The default ports in WSO2 EI are listed under Enterprise Integrator.
  • The distribution folder structure has changed from WSO2 BPS 3.6.0 to WSO2 EI 6.5.0.

     Comparing Folder Structures: WSO2 BPS 3.6.0 and WSO2 EI 6.5.0
    Business Process Server 3.6.0Enterprise Integrator 6.5.0
    <BPS_HOME>/repository/conf<EI_HOME>/wso2/business-process/conf
    <BPS_HOME>/repository/conf/axis2<EI_HOME>/wso2/business-process/conf/axis2
    <BPS_HOME>/repository/conf/datasources<EI_HOME>/wso2/business-process/conf/datasources
    <BPS_HOME>/repository/components/dropins<EI_HOME>/dropins
    <BPS_HOME>/repository/components/extensions<EI_HOME>/extensions
    <BPS_HOME>/repository/components/lib<EI_HOME>/lib
    <BPS_HOME>/repository/component/patches<EI_HOME>/patches

See the following topics for instructions:

Preparing to upgrade

The following prerequisites must be completed before upgrading:

  • Create a backup of the databases in your WSO2 BPS 3.6.0 instance.
  • Copy the <BPS_HOME> directory to back up the product configurations.
  • Download the product installer from here, and install WSO2 EI 6.5.0.
    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.5.0
    WindowsC:\Program Files\WSO2\EnterpriseIntegrator\6.5.0\
    Ubuntu/usr/lib/wso2/EnterpriseIntegrator/6.5.0
    CentOS/usr/lib64/EnterpriseIntegrator/6.5.0

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

Upgrading the databases

In WSO2 EI 6.5.0, you can use the same Carbon database and BPEL/BPMN databases that you used for WSO2 BPS 3.6.0. However, you need to apply Security Advisory (WSO2-2017-0345) before connecting the databases to WSO2 EI 6.5.0.

Due to Security Advisory (WSO2-2017-0345), WSO2 EI 6.5.0 uses OAEP for data encryption in addition to the RSA algorithm (which is used in WSO2 BPS 3.6.0). This applies only to internally-encrypted data in the BPS server. Therefore, the internally-encrypted data in your current databases (such as datasource configurations, user store configurations, keystore registry entries, service security policies, event publisher configurations, event receiver configurations, and event sink 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 BPS 3.6.0. This will give you a new WSO2 BPS distribution with the latest updates.

  2. Connect the WUM-updated WSO2 BPS 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_BPS_3.6.0_HOME>/repository/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_BPS_3.6.0_HOME>/repository/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 BPS server, open the user-mgt.xml file (stored in the <WUM_UPDATED_BPS_3.6.0_HOME>/repository/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.xmluser-mgt.xml, etc.).

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

    org.wso2.CipherTransformation=RSA/ECB/OAEPwithSHA1andMGF1Padding
  4. Start the WUM-updated BPS server. This will re-encrypt the data in the databases.

Migrating the configurations

 Do not copy configuration files directly between servers. Instead, update the files manually.

To migrate all the required folders, files, libraries, etc. from WSO2 BPS 3.6.0 to WSO2 EI 6.5.0:

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

  2. Copy the keystores and truststores from the <BPS_HOME>/repository/resources/security directory to the <EI_HOME>/wso2/business-process/repository/resources/security directory.
  3. If you have secondary user stores created for WSO2 BPS 3.6.0, you need to copy the 'userstore' folder in the <BPS_HOME>/repository/deployment/server/ directory to the <EI_HOME>/wso2/business-process/repository/deployment/server/ directory.

To migrate the configuration files from WSO2 BPS 3.6.0 to WSO2 EI 6.5.0:

  1. Update the configuration files with information of the migrated keystores and truststores. See Configuring Keystores in WSO2 products for more information.
  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 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 humantask 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 WSO2 BPS 3.6.0 based on your solution. For example, update the following configurations in WSO2 EI 6.5.0 accordingly:

    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

Follow the steps given below:

  1. Copy the BPEL .zip packages in the <BPS_HOME>/repository/deployment/server/bpel directory to the <EI_HOME>/wso2/business-process/repository/deployment/server/bpel directory.
  2. Copy the BPMN .bar packages in the <BPS_HOME>/repository/deployment/server/bpmn directory to the <EI_HOME>/wso2/business-process/repository/deployment/server/bpmn directory. 

  3. Copy the humantask .zip packages in the <BPS_HOME>/repository/deployment/server/humantasks directory to the <EI_HOME>/wso2/business-process/repository/deployment/server/humantasks directory.
  4. If you have custom artifacts created in the <BPS_HOME>/repository/deployment/server/ directory of WSO2 BPS 3.6.0, copy them to the <EI_HOME>/wso2/business-process/repository/deployment/server/ directory.
  5. If you have used multitenancy, copy the tenant directory packages from <BPS_HOME>/repository/tenants to the <EI_HOME>/wso2/business-process/repository/tenants directory.

Starting the server

Once you have completed the migration, you can start the Business Process profile of WSO2 EI. For details see Running the Product.

The Management Console, BPMN Explorer and Human Task Explorer URLs for the Business Process profile in WSO2 EI 6.5.0 are as follows:

  • Management Console : https://<ip>/<port>:9445/carbon/

  • BPMN Explorer : https://<ip>/<port>:9445/bpmn-explorer

  • HumanTask Explorer : https://<ip>/<port>:9445/humantask-explorer

  • No labels