Page Comparison

This section provides information on how you can upgrade from an older version of CEP to a newer versionWSO2 CEP 4.1.0 to WSO2 CEP 4.2.0. For more information on release versions, see the Release Matrix .

localtabgroup

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

Table of Contents

...

maxLevel

...

title	CEP 4.1.0 to CEP 4.2.0

...

3
minLevel	3

Preparing to upgrade

The following prerequisites should be completed before upgrading.

Make a backup of the CEP 4.1.0 database and copy the <CEP_HOME_4.1.0> directory in order to backup the product configurations.
Download CEP 4.2.0 from http://wso2.com/products/complex-event-processor/.

Migrating configurations

Follow the procedure below to migrate configurations from CEP 4.1.0 to CEP 4.2.0.

Note
Configurations should not be copied directly from CEP 4.1.0 to CEP 4.2.0 because some of th configuration files were updated with new properties between the two releases.

Make the required changes in the datasource files in the <CEP_HOME>/repository/conf/datasources directory to make sure that they are configured as required. For more information, see Datasources.
Check the configurations in the following files in <CEP_HOME>/repository/conf/data-bridge directory for CEP 4.1.0, and apply the same changes in CEP 4.2.0.
- data-agent-config.xml
- data-bridge-config.xml

Check the configurations in the following files in CEP 4.1.0, and apply same configurations in CEP 4.2.0.

Configuration File	Location
`axis2.xml`	`<CEP_HOME>/repository/conf/axis2`
`axis2_client.xml`	`<CEP_HOME>/repository/conf/axis2`
`carbon.xml`	`<CEP_HOME>/repository/conf`
`master-datasources.xml`	`<CEP_HOME>/repository/conf/datasources`
`identity.xml`	`<CEP_HOME>/repository/conf`
`log4j.properties`	`<CEP_HOME>/repository/conf`
`registry.xml`	`<CEP_HOME>/repository/conf`
`catalina-server.xml`	`<CEP_HOME>/repository/conf/tomcat`
`web.xml`	`<CEP_HOME>/repository/conf/tomcat`

If the Cipher tool was configured for CEP 4.1.0, check the configurations in the following files and apply the same changes in CEP 4.2.0.
Configuration File Location
cipher-text.properties <CEP_HOME>/repository/conf/security
cipher-tool.properties <CEP_HOME>/repository/conf/security
Check the configurations in the other files located in the <CEP 4.1.0_HOME>/repository/conf directory and apply the same changes to CEP 4.2.0.
If there are any third party libraries used with CEP 4.1.0 that you want to migrate, copy the following directories as applicable from CEP 4.1.0 to CEP 4.2.0.
- If you have used JMS libraries, JDBC libraries etc, copy <CEP_HOME>/repository/components/lib.
- If you have used OSGi bundles such as SVN kit etc, copy <CEP_HOME>/repository/components/dropins.
Start the CEP 4.2.0 server. For more information, see Running the Product.

Migrating artifacts

All artifacts can be migrated from CEP 4.1.0 to CEP 4.2.0 via Composite Application Archive (CAR) files. For detailed instructions package artifacts as C-App archives, see Packaging Artifacts as C-App Archive.

You should manually deploy Composite Application Archive (CAR) files that you have in CEP 4.1.0 to CEP 4.2.0.

Info
To migrate deployment artifacts: Copy the `<CEP_HOME>/repository/deployment/server` directory from CEP 4.1.0 to CEP 4.2.0. If multi-tenancy is used, copy the `<CEP_HOME>/repository/tenants` directory from CEP 4.1.0 to CEP 4.2.0.

Updating execution plans

WSO2 CEP 4.2.0 uses Siddhi 3.1.2 whereas CEP 4.1.0 uses Siddhi 3.0.5.

All Siddhi versions older than Siddhi 3.1.2 add a length window of size 1 for the initial stream of join queries. From Siddhi 3.1.2 onwards, a length window of size 0 is added. Therefore, once you migrate execution plans from CEP 4.1.0 to CEP 4.2.0, you need to manually add a length window of size 1 for the join queries as shown below (i.e. if you were relying on a length window of size 1 to be added by Siddhi in CEP 4.1.0).

e.g., The following query is included in an execution plan in CEP 4.1.0.

Code Block

language	sql

from TempStream[temp > 30.0]#window.time(1 min) as T join RegulatorStream[isOn == false] as R
  on T.roomNo == R.roomNo
select T.roomNo, R.deviceID, 'start' as action
insert into RegulatorActionStream;

When this execution plan is migrated to CEP 4.2.0, #window.length(1) property should be manually added to it as shown below.

Code Block

language	sql

from TempStream[temp > 30.0]#window.time(1 min) as T  join RegulatorStream[isOn == false]#window.length(1) as R
  on T.roomNo == R.roomNo
select T.roomNo, R.deviceID, 'start' as action
insert into RegulatorActionStream;

Migrating dashboard elements

This section covers the additional steps are required to migrate dashboard elements (i.e. gadgets and dashboards).

The Analytics Dashboard functionality in CEP 4.2.0 is powered by WSO2 Dashboard Server 2.1.0 whereas the same functionality in CEP 4.1.0 and earlier versions is powered by WSO2 Gadget Server 1.4.0. This section explains how to migrate the gadgets and dashboards from CEP 4.1.0 to 4.2.0.

There are two methods that can be used to migrate gadgets and dashboards between the two CEP versions.

Deploying the gadgets and dashboards in a CAR file
Migrating the dashboards and gadgets pointing your product home directory.

In both methods, the following two files are used to execute the migration.

File Name	Path	Description
`ds-migration-1.0.x-2.0.x.bat` or `ds-migration-1.0.x-2.0.x.sh`	`<CEP_HOME>/migration/dashboards/migration-1.0.x-2.0.x`	This triggers the execution of the migration
`migration.xml`	`<CEP_HOME>/migration/dashboards/migration-1.0.x-2.0.x`	This contains the migration configuration that specifies the mode and user inputs.

Click on the relevant tab depending on the method you want to follow.

Localtabgroup

Localtab

title	Using CAR files

Follow the procedure below to migrate gadgets and dashboards using CAR files.

Info
This method is appropriate when the dashboard elements to be migrated are deployed via a CAR file in CEP 4.1.0.

Open the <CEP_HOME>/migration/dashboard/migration1.0x-2.0.x/migration.xml file, and comment out the Portal File Migration section as shown in the example below.

Code Block

language	xml

        <!-- Portal File Migration-->
        <!-- Uncomment the below part to enable Portal migration -->

        <!-- DSMmigration-->

            <!-- Mode - Specifiy the migration type CAR or Portal -->
            <!-- Mode>Portal</Mode-->

            <!-- SourceDir - Specify the older PRODUCT_HOME direcotory.-->
            <!-- <SourceDir></SourceDir> -->

            <!-- DestinationDir - Specify the destination directory for migrated Store and Dashboards -->
            <!-- <DestinationDir></DestinationDir>-->

            <!-- TrustStoreLocation - Specify the trustedstore location. EX:- PRODUCT_HOME/repository/resources/security/wso2carbon.jks -->
            <!-- <TrustStoreLocation>YOUR_PRODUCT_HOME/repository/resources/security/wso2carbon.jks</TrustStoreLocation> -->

            <!-- TrustStorePassword - Specify the trustedstore password. EX:- wso2carbon -->
            <!-- <TrustStorePassword>wso2carbon</TrustStorePassword> -->

            <!-- SourceURL - Specify the source url - Older version of your product . EX:-https://hostname:port -->
            <!-- <SourceURL>https://localhost:9443</SourceURL> -->

            <!-- SourceUsername - Specify the carbon.super user's username EX:-admin -->
            <!-- <SourceUsername>admin</SourceUsername> -->

            <!-- SourcePassword - Specify the carbon.super user's password EX:-admin -->
            <!-- <SourcePassword>admin</SourcePassword> -->

            <!-- DestinationURL - Specify the destination url - Newer version of your product. EX:-https://hostname:port -->
            <!-- <DestinationURL>https://localhost:9444</DestinationURL> -->

            <!-- DestinationUsername - Specify the carbon.super user's username EX:-admin -->
            <!-- <DestinationUsername>admin</DestinationUsername> -->

            <!-- DestinationPassword - Specify the carbon.super user's password EX:-admin -->
            <!-- <DestinationPassword>admin</DestinationPassword> -->

            <!-- TenantDomains - Specify the tenant domain - This will migrate all the dashboards within these tenants. If you do not put anything here, It will update all the tenant dashboards -->
            <!-- <TenantDomains></TenantDomains>-->
        <!-- </DSMigration> -->

Run the following command to run the migration script.
For Windows: <CEP-4.1.0_HOME>/migration/dashboards/migration-1.0.x-2.0.x/ds-migration-1.0.x-2.0.x.bat --run
For Linux: <CEP-4.1.0_HOME>/migration/dashboards/migration-1.0.x-2.0.x/ds-migration-1.0.x-2.0.x.sh
Pack the required gadgets and dashboards in WSO2 CEP 4.1.0 to a CAR file and deploy it in WSO2 CEP 4.2.0. For more information, see Packaging Artifacts as C-App Archive.

Perform the following steps for each gadget.

Info
`<DESTINATION_DIRECTORY>` is the directory you specified for the `DestinationDir` parameter in the `Portal File Migration` section of the `<CEP_HOME>/migration/dashboard/migration1.0x-2.0.x`/`migration.xml` file.

Navigate to the home directory of the gadget. (e.g., <DESTINATION_DIRECTORY>/store/carbon.super/fs/gadget/my_gadget).
Replace the <DESTINATION_DIRECTORY>/store/carbon.super/fs/gadget/my_gadget/js/main.js file with the <CEP_HOME>/migration/dashboards/migration-1.0.x-2.0.x/resources/main.js file.
Similarly, replace the <DESTINATION_DIRECTORY>/store/carbon.super/fs/gadget/my_gadget/js/outputAdapterUiLibrary.js file with <CEP_HOME>/migration/dashboards/migration-1.0.x-2.0.x/resources/outputAdapterUiLibrary.js file.

Localtab

title	Pointing to the product home directory

In this approach the product home directory is defined as the source file. It migrates gadgets, layouts and widgets into the newer CEP version and copies them into the destination location specified by you.

Follow the procedure below to migrate gadgets and dashboards using the Portal.

Open the <CEP_HOME>/migration/dashboard/migration1.0x-2.0.x/migration.xml file, and comment out the CAR File Migration section as shown in the example below.

Code Block

language	xml

<!-- CAR File Migration-->
<!-- Uncomment the below part to enable CAR file migration -->
<!--DSMigration>
    <!-- Mode - Specifiy the migration type CAR or Portal -->
    <Mode>CAR</Mode>
    <!-- SourceDir - Specify the older PRODUCT_HOME direcotory.-->
    <SourceDir>CAR_FILE_SOURCE_DIRECTORY</SourceDir>
    <!-- DestinationDir - Specify the destination directory for migrated Store and Dashboards -->
    <DestinationDir>CAR_FILE_DESTINATION_DIRECTORY</DestinationDir>
</DSMigration-->

Configure the parameters in the Portal File Migration section as explained in the table below.

Parameter	Description	Example
`Mode`	The migration mode. This should be `CAR` (if you are migrating the dashboard elements in the CAR file), or `Portal` (if you are migrating the dashboard elements in via the portal).
`SourceDir`	The source of the dashboard elements to be migrated. The `<CEP_4.1.0_HOME>` should be specified as the source directory.
`DestinationDir`	The destination directory for the migrated Store.
`TrustStoreLocation`	This parameter specifies the trusted store location.	`<CEP_HOME>/repository/resources/security/wso2carbon.jks`
`TrustStorePassword`	The password of the trust store.ashboard	`wso2carbon`
`SourceURL`	The source URL. This should be the URL of the CEP 4.1.0 instance from which you are migrating the dashboard elements.	`https://hostname:port`
`SourceUsername`	Specify the username of the carbon super user.	`admin`
`SourcePassword`	Specify the password of the carbon super user.	`admin`
`DestinationURL`	The destination URL. This should be the URL of the CEP 4.2.0 to which you are migrating the dashboard elements.	`https://hostname:port`
`DestinationUsername`	Specify the username of the carbon super user.	`admin`
`DestinationPassword`	Specify the password of the carbon super user.	`admin`
`TenantDomains`	This parameter specifies the domains of all the tenants of whom the dashboards should be updated. If no value is specified for this parameter, the dashboards of all the tenants are updated.

The parameters that are required to have values depend on which dashboard elements you need to migrate as explained in the table below.

Option Description Required Parameters Configuration

1

Convert gadgets, widgets, and layouts in CEP 4.1.0 into the newer version (i.e. based on WSO2 Dashboard Server 2.x.x) and copy them into the destination directory. This allows you to merge the migrated store into the newer version of the CEP dashboards store.

Mode
SourceDir
DestinationDir

Code Block

language	xml

<DSMmigration>
    <Type>Portal</Type>
    <SourceDir>YOUR_PRODUCT_HOME</SourceDir>
    <DestinationDir>YOUR_DESTINATION_DIRECTORY</DestinationDir>
<TrustStoreLocation></TrustStoreLocation>
    <TrustStorePassword></TrustStorePassword>
    <SourceURL></SourceURL>
    <SourceUsername></SourceUsername>
    <SourcePassword></SourcePassword>
    <DestinationURL></DestinationURL>
    <DestinationUsername></DestinationUsername>
    <DestinationPassword></DestinationPassword>
    <TenantDomains></TenantDomains>
</DSMigration>

2

Convert gadgets, widgets, and layouts in CEP 4.1.0 into the newer version (i.e. based on WSO2 Dashboard Server 2.x.x) and copy them into the destination directory. In addition, get all the dashboards to reside in your source server (specified via the sourceURL parameter) and migrate it to the newer version. Once migration is done, it is copied into the destination directory defined in the migration.xml file.

Mode
SourceDir
DestinationDir
TrustStoreLocation
TrustStorePassword
SourceURL
SourceUsername
SourcePassword

Code Block

language	xml

<DSMmigration>
    <Type>Portal</Type>
    <SourceDir>YOUR_PRODUCT_HOME</SourceDir>
    <DestinationDir>YOUR_DESTINATION_DIRECTORY</DestinationDir>
<TrustStoreLocation>YOUR_PRODUCT_HOME/repository/resources/security/wso2carbon.jks</TrustStoreLocation>
    <TrustStorePassword>wso2carbon</TrustStorePassword>
    <SourceURL>https://localhost:9443</SourceURL>
    <SourceUsername>admin</SourceUsername>
    <SourcePassword>admin</SourcePassword>
    <DestinationURL></DestinationURL>
    <DestinationUsername></DestinationUsername>
    <DestinationPassword></DestinationPassword>
    <TenantDomains></TenantDomains>
</DSMigration>

3

Convert gadgets, widgets, and layouts in CEP 4.1.0 into the newer version (i.e. based on WSO2 Dashboard Server 2.x.x) and copy them into the destination directory. Update the dashboards in the server specified by the DestinationURL.

Info
This requires you to maintain the same trust store location and the trust password in both CEP versions.

Mode
SourceDir
DestinationDir
TrustStoreLocation
TrustStorePassword
SourceURL
SourceUsername
SourcePassword
DestinationURL
DestinationUsername
DestinationPassword

Code Block

language	xml

<DSMmigration>
    <Type>Portal</Type>
    <SourceDir>YOUR_PRODUCT_HOME</SourceDir>
    <DestinationDir>YOUR_DESTINATION_DIRECTORY</DestinationDir>
<TrustStoreLocation>YOUR_PRODUCT_HOME/repository/resources/security/wso2carbon.jks</TrustStoreLocation>
    <TrustStorePassword>wso2carbon</TrustStorePassword>
    <SourceURL>https://localhost:9443</SourceURL>
    <SourceUsername>admin</SourceUsername>
    <SourcePassword>admin</SourcePassword>
    <DestinationURL>https://localhost:9444</DestinationURL>
    <DestinationUsername>admin</DestinationUsername>
    <DestinationPassword>admin</DestinationPassword>
    <TenantDomains></TenantDomains>
</DSMigration>

Run the following command to run the migration script.
For Windows: <CEP-4.1.0_HOME>/migration/dashboards/migration-1.0.x-2.0.x/ds-migration-1.0.x-2.0.x.bat --run
For Linux: <CEP-4.1.0_HOME>/migration/dashboards/migration-1.0.x-2.0.x/ds-migration-1.0.x-2.0.x.sh

Perform the following steps for each gadget.

Info
`<DESTINATION_DIRECTORY>` is the directory you specified for the `DestinationDir` parameter in the `Portal File Migration` section of the `<CEP_HOME>/migration/dashboard/migration1.0x-2.0.x`/`migration.xml` file.

Navigate to the home directory of the gadget. (e.g., <DESTINATION_DIRECTORY>/store/carbon.super/fs/gadget/my_gadget).
Replace the <DESTINATION_DIRECTORY>/store/carbon.super/fs/gadget/my_gadget/js/main.js file with the <CEP_HOME>/migration/dashboards/migration-1.0.x-2.0.x/resources/main.js file.
Similarly, replace the <DESTINATION_DIRECTORY>/store/carbon.super/fs/gadget/my_gadget/js/outputAdapterUiLibrary.js file with <CEP_HOME>/migration/dashboards/migration-1.0.x-2.0.x/resources/outputAdapterUiLibrary.js file.

Validating path changes

CEP 4.2.0 has a different directory structure to CEP 4.1.0 that affects the path to the gadget store as shown below.

CEP 4.1.0: <CEP_HOME>/repository/deployment/server/jaggeryapps/portal/store/<Tenant_Name>/gadget
CEP 4.2.0: <CEP_HOME>/repository/deployment/server/jaggeryapps/portal/store/<Tenant_Name>/<StoreType [fs/es]>/gadget

Therefore, if a gadget has relative paths included in its index.xml file (i.e. in the <CEP_HOME>/repository/deployment/server/jaggeryapps/portal/store/<Tenant_Name>/<StoreType [fs/es] >/gadget/<GADGET_NAME> path), you should check whether they are updated with the change in the directory structure. This check should be carried out after running the migration script.

e.g., A path is given as follows in the index.xml file in CEP 4.1.0.

<script language="javascript" type="text/javascript" src="../../../../js/igviz.js"></script>

The same link should be given as follows in CEP 4.2.0 due to the change in the directory structure (i.e. an additional ../ should be added for the new directory added to the structure).

<script language="javascript" type="text/javascript" src="../../../../../js/igviz.js"></script>

Updating layout configurations

The dashboard layout configurations are defined in the index.xml file. This file differs as follows based on the CEP version.

CEP Version 4.1.0 4.2.0

Location <CEP_HOME>/repository/deployment/server/jaggeryapps/portal/store/<Tenant_Name>/layout/<LAYOUT_NAME> <CEP_HOME>/repository/deployment/server/jaggeryapps/portal/store/<Tenant_Name>/<StoreType [fs/es]>/layout/<LAYOUT_NAME>

Indexing 1 based indexing 0 based indexing

Format

Code Block

language	js

{
    "blocks": [
        { "id": "a", "row": 1, "col": 1, "size_x": 4, "size_y": 3 },
        { "id": "b", "row": 1, "col": 5, "size_x": 4, "size_y": 3 },
        { "id": "c", "row": 1, "col": 9, "size_x": 4, "size_y": 3 },
        { "id": "d", "row": 4, "col": 1, "size_x": 4, "size_y": 3 },
        { "id": "e", "row": 4, "col": 5, "size_x": 4, "size_y": 3 },
        { "id": "f", "row": 4, "col": 9, "size_x": 4, "size_y": 3 }
    ]
}

Code Block

language	js

{
    "blocks": [
        { "id": "a", "x": 0, "y": 0, "width": 4, "height": 3 },
        { "id": "b", "x": 4, "y": 0, "width": 4, "height": 3 },
        { "id": "c", "x": 8, "y": 0, "width": 4, "height": 3 },
        { "id": "d", "x": 0, "y": 3, "width": 4, "height": 3 },
        { "id": "e", "x": 4, "y": 3, "width": 4, "height": 3 },
        { "id": "f", "x": 8, "y": 3, "width": 4, "height": 3 }
    ]
}

The layouts migrated from CEP 4.1.0 to CEP 4.2.0 will have the format in which layouts are saved in CEP 4.1.0. To make them compatible with CEP 4.2.0

Replace "size_x" and "size_y" attributes with "width" and "height" respectively.
Replace "row" and "col" attributes with "x" and "y" respectively, and reduce their values by 1 to match the 0 based indexing.

e.g., { "id": "a", "row": 1, "col": 1, "size_x": 4, "size_y": 3 } should be replaced with { "id": "a", "x": 0, "y": 0, "width": 4, "height": 3 }.

Testing the upgrade

Verify that all the required scenarios are working as expected. This confirms that the upgrade is successful.

Localtab

title	CEP 4.0.0 to CEP 4.1.0

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

Preparing to upgrade

The following prerequisites should be completed before upgrading.

Make a backup of the CEP 4.0.0 database and copy the <CEP_HOME_4.0.0> directory in order to backup the product configurations.
Download CEP 4.1.0 from http://wso2.com/products/complex-event-processor/.

Upgrading the databases

The instructions in this section describe how you can perform a data migration to upgrade the 4.0.0 database for use in CEP 4.1.0.

Before you upgrade to CEP 4.1.0, create a new database and restore the backup of the CEP 4.0.0 database in this new database.
Info
title Note
You should NOT connect a new version of WSO2 CEP to an older database that has not been upgraded.

Select the relevant script for the upgrade from here and run it on the new database. Running this script will ensure that the new database is upgraded to have the additional tables and schemas that are required for CEP 4.1.0.

Info

title	Note

There are three migration scripts available: migration-service-provider.sql , migration-identity.sql and migration.sql. However, only the migration.sql script is required to be executed for the CEP database upgrade.

Migrating configurations

Follow the procedure below to migrate configurations from CEP 4.0.0 to CEP 4.1.0.

Note
Configurations should not be copied directly from CEP 4.0.0 to CEP 4.1.0 because the configuration files have new properties added to them as well as obsolete properties removed from them between the two releases.

Check the configurations in the following files in <CEP_HOME>/repository/conf/data-bridge directory for CEP 4.0.0, and apply the same changes in CEP 4.1.0 manually.
- data-agent-config.xml
- data-bridge-config.xml

Check the configurations in the following files in CEP 4.0.0, and apply same configurations in CEP 4.1.0 manually.

Configuration File	Location
`axis2.xml`	`<CEP_HOME>/repository/conf/axis2`
`axis2_client.xml`	`<CEP_HOME>/repository/conf/axis2`
`carbon.xml`	`<CEP_HOME>/repository/conf`
`master-datasources.xml`	`<CEP_HOME>/repository/conf/datasources`
`identity.xml`	`<CEP_HOME>/repository/conf`
`log4j.properties`	`<CEP_HOME>/repository/conf`
`registry.xml`	`<CEP_HOME>/repository/conf`
`catalina-server.xml`	`<CEP_HOME>/repository/conf/tomcat`
`web.xml`	`<CEP_HOME>/repository/conf/tomcat`

If the Cipher tool was configured for CEP 4.0.0, check the configurations in the following files and apply the same changes in CEP 4.1.0 manually.
Configuration File Location
cipher-text.properties <CEP_HOME>/repository/conf/security
cipher-tool.properties <CEP_HOME>/repository/conf/security
Check the configurations in the other files located in the <CEP 4.0.0_HOME>/repository/conf directory and apply the same changes to CEP 4.1.0 manually.
If there are any third party libraries used with CEP 4.0.0 that you want to migrate, copy the following directories as applicable from CEP 4.0.0 to CEP 4.1.0:
- If you have used JMS libraries, JDBC libraries etc, copy <CEP_HOME>/repository/components/lib.
- If you have used OSGi bundles such as SVN kit etc, copy <CEP_HOME>/repository/components/dropins.
Start the CEP 4.1.0 server. For more information, see Running the Product.

Migrating artifacts

You should manually deploy Composite Application Archive (CAR) files that you have in CEP 4.0.0 to CEP 4.1.0. For more information, see Packaging Artifacts as C-App Archive .

Info

title	Note

To migrate deployment artifacts:

Copy the <CEP_HOME>/repository/deployment/server directory from CEP 4.0.0 to CEP 4.1.0.
If multi-tenancy is used, copy the <CEP_HOME>/repository/tenants directory from CEP 4.0.0 to CEP 4.1.0.

Testing the upgrade

When the database upgrade scripts are executed, the following are some of the new tables that will be created in the database:
- UM_DOMAIN
- UM_SYSTEM_USER
- UM_SYSTEM_ROLE
- UM_SYSTEM_USER_ROLE
Verify that all the required scenarios are working as expected. This confirms that the upgrade is successful.

Localtab

title	CEP 3.1.0 to CEP 4.0.0

Warning

title	WSO2 CEP 4.0.0 is not backward compatible

Artifacts of CEP 4.0.0 are not backward comparable as there were major changes in the CEP architecture. Therefore, they need to be rewritten and deployed manually.

Preparing to upgrade

The following prerequisites must be completed before upgrading:

Make a backup of the CEP 3.1.0 database and copy the <CEP_HOME_3.1.0> directory in order to backup the product configurations.
Download CEP 4.0.0 from http://wso2.com/products/complex-event-processor/.

Info

title	Note

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

Upgrading the databases

The instructions in this section describe how you can perform a data migration to upgrade the 3.1.0 database for use in CEP 4.0.0.

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

Before you upgrade to CEP 4.0.0, create a new database and restore the backup of the CEP 3.1.0 database in this new database.
Info
title Note
You should NOT connect a new version of WSO2 CEP to an older database that has not been upgraded.

Select the relevant script for the upgrade from here and run it on the new database. Running this script will ensure that the new database is upgraded to have the additional tables and schemas that are required for CEP 4.0.0.

Info

title	Note

There are three migration scripts available: migration-service-provider.sql , migration-identity.sql and migration.sql. However, only the migration.sql script is required to be executed for the CEP database upgrade.

Handling Artifacts

Artifacts cannot be directly migrated from CEP 3.1.0 to CEP 4.0.0 since the configurable objects in CEP 4.0.0 are different to that in CEP 3.1.0. Therefore, the configuration should be handled as follows.

Artifact Type in CEP 3.1.0	Replaced in CEP 4.0.0 By	Note	Recommended Action
Input Event Adapter Event Builder	Event Receiver	The `Event Receiver` artifact in CEP 4.0.0 embeds both the `Input Event Adapter` and `Event Builder` artifacts in CEP 3.1.0.	Identify the input event adapters and event builders used in combination in CEP 3.1.0, and redefine them as event receivers. For detailed instructions, see Configuring Event Receivers.
Event Stream	N/A		Redefine the event streams in CEP 4.0.0. For detailed instructions, see Understanding Event Streams.
Output Event Adapter Event Formatter	Event Publisher	The `Event Publisher` artifact in CEP 4.0.0 embeds both the `Output Event Adapter` and `Event Formatter` artifacts in CEP 3.1.0.	Identify the output event adapters and event formatters used in combination in CEP 3.1.0, and redefine them as event publishers. For detailed instructions, see Configuring CEP to Create Alerts.
Execution Plan	N/A	The Siddhi Query Language in CEP 4.0.0 is different to that in CEP 3.1.0. Therefore, the Siddhi queries of an execution plan directly migrated from CEP 3.1.0 cannot function in CEP 4.0.0.	Redefine the execution plans in CEP 4.0.0. For detailed instructions on defining execution plans, see Creating a Standalone Execution Plan and Creating a Storm Based Distributed Execution Plan. For the modified Siddhi Query Language, see SiddhiQL Guide 3.1.

Testing the upgrade

When the database upgrade scripts are executed, the following are some of the new tables that will be created in the database:
- UM_DOMAIN
- UM_SYSTEM_USER
- UM_SYSTEM_ROLE
- UM_SYSTEM_USER_ROLE
Verify that all the required scenarios are working as expected. This confirms that the upgrade is successful.

...

Versions Compared

Old Version 19

New Version 20

Key

Preparing to upgrade

Migrating configurations

Migrating artifacts

Updating execution plans

Migrating dashboard elements

Validating path changes

Updating layout configurations

Testing the upgrade

Preparing to upgrade

Upgrading the databases

Migrating configurations

Migrating artifacts

Testing the upgrade

Preparing to upgrade

Upgrading the databases

Handling Artifacts

Testing the upgrade

Configuration File	Location
`cipher-text.properties`	`<CEP_HOME>/repository/conf/security`
`cipher-tool.properties`	`<CEP_HOME>/repository/conf/security`