WSO2 APIM Product Migration

6 min readJun 27, 2021

WSO2 recommends using the latest product versions to get new features. (Image Reference[1])

Hello People,

I hope all are living healthy and safe.

Today topic is WSO2 APIM product migration. This content will describe why you need to migrate, How you can migrate, and the best practices you can follow for a successful migration?

What is product migration?

WSO2 product migration is moving to the latest version of the WSO2 product rather than using an old version. We know WSO2 APIM product has different versions like APIM 1.10.0, 2.1.0, 2.6.0, 3.0.0 .. etc. The latest APIM version is APIM 4.0.0[2]. Simply APIM product migration moves from an old APIM version(APIM 1.10.0, 2.x, 3.x) to the latest APIM 4.0.0.

When using a mobile application, you may have to upgrade them from time to time. You may have to click one button to upgrade the application. However wso2 product upgrade couldn’t be done in such a simple way. You need to follow a standard process that includes a set of steps need to follow carefully.

Therefore each WSO2 product has built its own migration process and published it through WSO2 official documents. Here I am taking the WSO2 APIM product to discuss the migration process.

Why do you need to migrate?

You may already use wso2 products and have a stable deployment. Then why you need to move to the latest version.

Your product version’s Life Cycle will end soon: WSO2 undertakes to provide support for any product version for a minimum of 3 years from its release date. After that, WSO2 eventually discontinues the product version from support services by defining an EOL date of the particular product version. You can refer to this page[3] listing each wso2 product’s EOL date.
To get the experience of new features: WSO2 is introducing new features for their products based on the customer requirements and the market trends. Therefore if you want to use them, you want to migrate your current wso2 product to its latest version.
To get fixes for already identified issues(Feature level or security level): WSO2 is fixing already identified bugs or code improvements before releasing a new product version. Therefore the new version will be much stable than the old one.
To get a good user experience: For instance, In APIM 2.x series used jaggery for their UI development. But when moving to APIM 3.x series, they are using React for UI. Therefore new APIM has a much attractive, user-friendly and responsive UI. It helps to improve the user experience.
To improve the system's performance: WSO2 has changed the architecture of the old APIM when releasing to the latest version to address the performance issues.

How can you migrate the WSO2 APIM product?

To migrate an old APIM product to the latest APIM product version, you need to follow a standard process, and you can find that list here in a detailed manner. Then, based on your old product version, you can choose the relevant document and follow. Here I will briefly put those steps.

New Deployment: As the first step, you need to set up your new deployment using the latest APIM version. In the migration process, we are not touching the up-and-running setup. Therefore, we need to set up a new deployment and move the old artifacts from old to new. Once successfully moved, we can change the traffic from the old environment to the new deployment.
Configuration Migration: You need to migrate the configuration from the old to the new deployment when doing the new setup. When coming to APIM 3.x, WSO2 has changed the configuration model[5] and based on that, you need to migrate the old configuration to the “deployment. toml”.
Customization Migration: You may use custom components in your old deployment, such as custom mediators, JWT generators ..etc. Then you need to update their dependencies as compatible with the latest APIM version. Hence, you need to build the code, get the new jar, and apply it to the new product if you have UI customization. That also, you need to rewrite them by using React.
Take DB dumps of old databases and restore them to new databases. Other migration will perform on these backup databases.
Registry versioning disables step[6]: Run the particular DB script on the Registry database (conf + governance registry databases)
Introduce new tables for the apimgt database: When coming to the latest product, WSO2 has added new features. Therefore apimgt database schema has changed due to these new features. So we need to run that DB script on the apimgt database[7].
GW artifact migration: This is an optional step for APIM 400 because GW artifact will not keep in the file system. However, this step should perform if you come from APIM 200 or later to APIM 3x series. For this, you have to execute a bash/shell script based on your OS type.
Identity Component Migration: WSO2 provide a client for this, and changes will be performed on the IDN tables of the apimgt database and UM tables of the user database.
AM Component Migration: WSO2 provides a client for this, and required changes will be done on the AM tables of the apimgt database and tables of the registry databases.
Re-indexing: Show the APIs on the UI correctly.

Once you completed the above steps, you can get the migrated set up with the migrated data. These steps have explained with details here[6], and you can review them for further clarification.

Best Practices for Migration

When performing the migration, you can consider the following points to complete the migration successfully.

When migrating, if you are doing an architectural change of your deployment, please review it with WSO2.
If you change the DB type (e.g. Mysql -> Oracle), please do it before or after completing the migration.
If you change the DB version, please check compatibility with the latest product version. If the existing DB version is not compatible with the latest version, you need to update it.
If you have LB, please make sure to ready them for the new deployment too.
Once deployed the new environment, please test the environment with the fresh DB before performing the migration. If the new deployment working fine with fresh DB (basic functionalities + your use cases + custom components), then you can perform the migration on that environment by using the old DB dumps.
You can run a pilot migration to understand the time to complete migration and identify the errors before the exact migration.
You can migrate your system at a time with low traffic, or else you can get a complete downtime(if possible)of the up-and-running system and do.
Please execute the DB cleanup script[8] on the DB dumps to reduce the size and speed up the migration process.
Please get the latest updated pack of APIM product before migrating.
Please take the latest version of each migration client and script from the official document[6] before migration.
If you faced any error while running the DB scripts or clients, you must fix them to complete the migration successfully. Then, you can get assistance from the WSO2[9], and they will help you fix them and proceed.
Once completed the migration, you should have ready your test suite to test the basic functionalities & your use cases on the migrated setup. Then, if the system is working fine, you can do the DNS cutover from the old to the new system.

I hope this content helps you to understand the WSO2 product migration process. Appreciate your claps and feedback :).

Stay safe and Healthy !!! Bye :)