Upgrading from a Previous Release

This page walks you through the process of upgrading to WSO2 Enterprise Store (ES) 2.1.0 from WSO2 ES 2.0.0. For more information on release versions, see the Release Matrix.

Preparing to upgrade

The following prerequisites must be completed before upgrading:

Stop all the WSO2 products that are connected to the database.
Make a backup of the <ES_HOME_2.0.0> directory in order to backup the product configurations.
Make a backup of any mounted databases of WSO2 ES 2.0.0.
Download WSO2 ES 2.1.0 from http://wso2.com/products/enterprise-store/ and unzip it. The unzipped folder is referred to as <ES_HOME> hereafter.

Limitations

The following are the limitations of upgrading.

This upgrading process can only be done for the same database types.
For example, these migration scripts will not work if you are using MySQL currently and you wish to use Oracle in the new version of WSO2 ES.
You cannot roll back the upgrading process. However, it is possible to restore a backup of the previous database and redo the upgrading progress.

Downtime

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

Upgrading the product

You need to execute the following types of migrations to upgrade WSO2 ES.

Step 1 - Migrate the configurations

Do not copy the configurations directly between the product servers.

Follow the instructions below to migrate the configurations to point to the existing database that is to be upgraded.

Connect WSO2 ES 2.1.0 to the database of WSO2 ES 2.0.0 by configuring the following files:

Configure the WSO2 ES 2.1.0 <ES_HOME>/repository/conf/datasources/master-datasources.xml file in the identical manner to which the WSO2 ES 2.0.0. master-datasources.xml file is configured.
For more information, see Configuring master-datasources.xml.
Navigate to the <ES_HOME>/repository/conf directory, and update the datasource references in the user-mgt.xml, registry.xml and identity.xml files in the identical manner to which the WSO2 ES 2.0.0. user-mgt.xml and registry.xml files are configured. For more information, see Configuring user-mgt.xml, Configuring registry.xml and Configuring identity.xml.
The following are sample configurations when the datasource is jdbc/WSO2CarbonDB.
registry.xml
```
<dbConfig name="wso2registry">
    <dataSource>jdbc/WSO2CarbonDB</dataSource>
</dbConfig> 
```
user-mgt.xml
```
<UserManager>
  <Realm>
  <Configuration>
  ...
  <Property name="dataSource">jdbc/WSO2CarbonDB</Property>
  </Configuration>
  ...
  </Realm>
</UserManager> 
```
identity.xml
```
<DataSource>      

    <Name>jdbc/WSO2CarbonDB</Name>
</DataSource> 
```

If there are several 1000s of artifacts in the system, increase the value of the <indexingFrequencyInSeconds> property (e.g., to 10), or reduce the value of the <batchSize> property (e.g., to 10) in the < ES_HOME>/repository/conf/registry.xml file based on your requirement.

    <!-- This defines index cofiguration which is used in meta data search feature of the registry -->
    <indexingConfiguration>
        <startingDelayInSeconds>30</startingDelayInSeconds>
        <indexingFrequencyInSeconds>5</indexingFrequencyInSeconds>
        <!--number of resources submit for given indexing thread -->
        <batchSize>50</batchSize>
         <!--number of worker threads for indexing -->
        <indexerPoolSize>50</indexerPoolSize>
        <!-- location storing the time the indexing took place-->
        <lastAccessTimeLocation>/_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime</lastAccessTimeLocation>
        <!-- the indexers that implement the indexer interface for a relevant media type/(s) -->
        <indexers>
           ...
            <indexer class="org.wso2.carbon.governance.registry.extensions.indexers.RXTIndexer" mediaTypeRegEx="application/vnd.(.)+\+xml" profiles ="default"/>
        
        </indexers>
        <exclusions>
            <exclusion pathRegEx="/_system/config/repository/dashboards/gadgets/swfobject1-5/.*[.]html"/>
            <exclusion pathRegEx="/_system/local/repository/components/org[.]wso2[.]carbon[.]registry/mount/.*"/>
        </exclusions>
    </indexingConfiguration>

If there are any third-party libraries used with ES 2.0.0 that you want to migrate, copy the following directories as applicable from ES 2.0.0 to ES 2.1.0:
- If you have used JDBC libraries, copy them into the <ES_HOME>/repository/components/lib directory.
- If you have used OSGi bundles, copy them into the <ES_HOME>/repository/components/dropins directory.

Step 2 - Upgrade the database

Follow the instructions below to perform a data migration to upgrade the WSO2 ES 2.0.0 database for use in WSO2 ES 2.1.0.

Download WSO2 Enterprise Store from http://wso2.com/products/enterprise-store/ if you have not done so already.
Stop all running server instances of WSO2 Enterprise Store 2.0.0.
Point WSO2 ES 2.1.0 to the database that you are in the process of migrating.

You should NOT connect a new version of WSO2 ES to an older database that has not been upgraded.
Download the WSO2 Identity server (IS) migration client (IS_migration_client.zip) and unzip it.
The unzipped folder is referred to as <IS_MIGRATION_CLIENT_HOME> hereafter.
Copy the <IS_MIGRATION_CLIENT_HOME>/org.wso2.carbon.is.migrate.client-5.1.0.jar file and add it to the <ES_HOME>/repository/components/dropins directory.
Copy the <IS_MIGRATION_CLIENT_HOME>/migration-identity-4.5.6_to_5.0.8 folder and add it to the <ES_HOME>/dbscripts/identity directory.
Copy the <IS_MIGRATION_CLIENT_HOME>/migration-um-4.5.6_to_5.0.8 folder and add it to the <ES_HOME>/dbscripts directory.
Apply the identity migration client for the WSO2 ES 2.0.0 to WSO2 2.1.0 migration.
1. Navigate to the <ES_HOME>/bin directory via the Command Line Interface or terminal, and start the WSO2 ES 2.1.0 server by executing the following command options to execute the identity migration client.
  The IS migration client updates the identity-related tables with respect to the version change.
2. Press CTRL+C to stop the server.
3. Restart the WSO2 ES 2.1.0 server by executing the following command.
  The migration client updates the user management tables with respect to the version change.

Step 3 - Clean resources of the previous version

Follow the instructions below to clean all existing resources of the WSO2 ES 2.0.0.

Download the ES migration client (es_2.0.0_to_2.1.0_migration_client.zip) and unzip it.
The unzipped folder is referred to as <ES_MIGRATION_CLIENT_HOME> hereafter.
Copy the org.wso2.carbon.es.migrate.client-2.1.0.jar file, which is in the <ES_MIGRATION_CLIENT_HOME> directory, into the <ES_HOME>/repository/components/dropins directory.

If you use a clustered/distributed setup, copy the JAR file only to the master node(s).
Navigate to the <ES_HOME>/bin directory via the Command Line Interface or terminal, and restart the server by executing the following commands.
Press CTRL+C to stop the server.

Do this only after the migration process that was executed in the previous step is completed.

Step 4 - Migrate data

Follow the instructions given below to migrate the data.

Step 1 - Migrate the data as required

Provider related data migration

Navigate to the <ES_HOME>/bin directory via the Command Line Interface or terminal, and start the WSO2 ES 2.1.0 server to carry out the mandatory data migration on the provider.

If you use a clustered/distributed setup, execute the following command options only in the master node(s).

Email login related data migration (Optional)

This data migration is mandatory if you have enabled login with email username.

When new users sign into WSO2 ES, if authentication via email is enabled, they need to use their email address as their username. Therefore, in the migration process if you want to migrate the WSO2 ES 2.0.0 assets that belong to one of the following categories, follow the instructions below.

Possesses an email as its username in the resource path.
Possesses a corresponding resource RXT that contains the overview_provider element in its storage path

Navigate to the <ES_HOME>/bin directory via the Command Line Interface or terminal, and start the WSO2 ES 2.1.0 server as follows to migrate the registry configurations.

If you use a clustered/distributed setup, execute the following command options only in the master node(s).

Step 2 - Migrate any customized configurations (Optional)

Check for any other configurations that you configured for WSO2 ES 2.0.0 (based on your solution), and update the configuration files in WSO2 ES 2.1.0 accordingly. For example, configurations for external user stores, caching, mounting etc.

Step 3 - Stop the Server

Press Ctrl+C to stop the ES 2.1.0 server.

Step 4 - Start the server without the migration client

Navigate to the <ES_HOME>/repository/components/dropins directory and remove the migration client related JARs (org.wso2.carbon.is.migrate.client-5.1.0.jar and org.wso2.carbon.es.migrate.client-2.1.0.jar).
Navigate to the <ES_HOME>/bin directory via the Command Line Interface or terminal and start the WSO2 ES 2.1.0 server using the normal approach.

Reindexing resources

If the assets that you possessed in ES 2.0.0 do not appear after the migration process, reindex the resources as follows:

Delete the <ES_HOME>/solr directory of the file system.
Change the name of the file that tracks the last access time that the resources were indexed, by changing the value of the <lastAccessTimeLocation> property in the <ES_HOME>/repository/conf/registry.xml file.
For example, if you are changing the latter mentioned value from lastaccesstime to lastaccesstime_1 the configuration should appear as follows:
```

<lastAccessTimeLocation>/_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1</lastAccessTimeLocation>
```
Restart the WSO2 ES server and wait for around 30 minutes for the assets to get reindexed.
The latter mentioned time duration varies based on the number of resources that are there in the registry.

Recommended checkpoints

When the database upgrade scripts are executed, the following are some of the new tables that are created in the database:

IDP_METADATA
SP_METADATA

Navigate to the database configurations in the <ES_HOME>/repository/conf/identity/identity.xml file and check if the latter mentioned tables are created, in order to verify whether these tables have been created in the identity database.

Testing the upgrade

Make sure that the server starts up fine without any errors.
Verify that the Users and Roles are picked up:

Navigate to Configure and click Users and Roles under the Accounts & Credentials menu.
Verify that the list of users and roles are shown correctly.
View the permissions of a chosen role, and make sure that the permissions are correct.

Carryout the following tests, which are recommended to run on the upgraded system.
- Create multiple user stores and try adding users to different user stores.
- Create multiple tenants and add different user stores to the different tenants. Thereafter, add users to the various user stores.

Once the above tests are run successfully, it is safe to consider that the upgrade is ready for production. However, it is recommended to test all the respective features that are being used in production.