WSO2 Complex Event Processor is succeeded by WSO2 Stream Processor. To view the latest documentation for WSO2 SP, see WSO2 Stream Processor Documentation.
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 21 Current »

This section provides information on how you can upgrade from WSO2 CEP 4.1.0 to WSO2 CEP 4.2.0. For more information on release versions, see the  Release Matrix .

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.

Migrating configurations

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

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.

  1. 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.
  2. 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
  3. Check the configurations in the following files in CEP 4.1.0, and apply same configurations in CEP 4.2.0. 

    Configuration FileLocation
    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
  4. 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 FileLocation
    cipher-text.properties<CEP_HOME>/repository/conf/security
    cipher-tool.properties<CEP_HOME>/repository/conf/security
  5. 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.
  6. 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.
  7. 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.

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.

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.

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 NamePathDescription
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.xThis triggers the execution of the migration
migration.xml<CEP_HOME>/migration/dashboards/migration-1.0.x-2.0.xThis contains the migration configuration that specifies the mode and user inputs.

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

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

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

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

            <!-- 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> -->
  2. 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
  3. 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.
  4. Perform the following steps for each gadget.

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

     

    1. Navigate to the home directory of the gadget. (e.g., <DESTINATION_DIRECTORY>/store/carbon.super/fs/gadget/my_gadget).
    2. 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.
    3. 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.

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.

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

    <!-- 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-->
  2. Configure the parameters in the Portal File Migration section as explained in the table below.

    ParameterDescriptionExample
    ModeThe 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). 
    SourceDirThe source of the dashboard elements to be migrated. The <CEP_4.1.0_HOME> should be specified as the source directory. 
    DestinationDirThe destination directory for the migrated Store. 
    TrustStoreLocationThis parameter specifies the trusted store location.<CEP_HOME>/repository/resources/security/wso2carbon.jks
    TrustStorePasswordThe password of the trust store.ashboardwso2carbon
    SourceURLThe 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
    SourceUsernameSpecify the username of the carbon super user.admin
    SourcePasswordSpecify the password of the carbon super user.admin
    DestinationURLThe destination URL. This should be the URL of the CEP 4.2.0 to which you are migrating the dashboard elements. https://hostname:port
    DestinationUsernameSpecify the username of the carbon super user. admin
    DestinationPasswordSpecify the password of the carbon super user.admin
    TenantDomainsThis 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.

    OptionDescriptionRequired ParametersConfiguration
    1Convert 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
    <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>
    2Convert 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
     
    <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.

    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
    <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>
  3. 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
  4. Perform the following steps for each gadget.

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

     

    1. Navigate to the home directory of the gadget. (e.g., <DESTINATION_DIRECTORY>/store/carbon.super/fs/gadget/my_gadget).
    2. 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.
    3. 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 Version4.1.04.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>
Indexing1 based indexing0 based indexing
Format
{
    "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 }
    ]
}
{
    "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

  1. Replace "size_x" and "size_y" attributes with "width" and "height" respectively.
  2. 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.

  • No labels