API Manager 2.6.0

All docs This doc
Expand all   Collapse all
||
Skip to end of metadata
Go to start of metadata

The following information describes how to upgrade your WSO2 API Manager server (WSO2 API-M) from APIM 1.8.0/1.9.0/1.9.1/1.10.0/2.0.0/2.1.0/2.2.0/2.5.0 to 2.6.0. 

To upgrade from a version older than 1.8.0, follow the instructions in the document that was released immediately after your current release and upgrade incrementally.

Before you begin

This release is a WUM-only release. This means that there are no manual patches. Any further fixes or latest updates for this release can be updated through the WSO2 Update Manager (WUM).

  • If you are upgrading to this version, in order to use this version in your production environment, use the WSO2 Update Manager and get the latest available updates for WSO2 API Manager 2.6.0. For more information on how to do this, see Updating WSO2 Products.

Follow the instructions below to upgrade your WSO2 API Manager server from WSO2 API-M 2.5.0 to 2.6.0. 

If you are using WSO2 Identity Server (WSO2 IS) as a Key Manager, follow the instructions in Upgrading from the Previous Release when WSO2 IS is the Key Manager.

Step 1 - Migrate the WSO2 API-M 2.5.0 configurations

Do not copy entire configuration files from the current version of WSO2 API Manager to the new one, as some configuration files (e.g., api-manager.xml) may have changed. Instead, redo the configuration changes in the new configuration files.

Follow the instructions below to move all the existing API Manager configurations from the current environment to the new one.

  1. Back up all databases in your API Manager instances along with the Synapse configurations of all the tenants and the super tenant.

    • The Synapse configurations of the super tenant are in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory.

    • The Synapse configurations of tenants are in the <CURRENT_APIM_HOME>/repository/tenants directory. 

    • If you use a clustered/distributed API Manager setup, back up the available configurations in the API Gateway node.

  2. Download API Manager 2.6.0 from https://wso2.com/api-management/.

  3. Open the <API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml file and provide the datasource configurations for the following databases. You can copy the configuration values from the same file in the current API Manager instance that you are already using.

    • User Store
    • Registry database/s
    • API Manager databases
    • Statistics database (If statistics are configured)

    Unlike in previous WSO2 API-M versions, in WSO2 API-M 2.6.0 the defaultAutoCommit property is set to true by default for the following datasource configurations in the master-datasources.xml file.

    • WSO2_CARBON_DB
    • WSO2AM_DB
    • WSO2AM_STATS_DB

    When auto committing is enabled, each SQL statement will be committed to the database as an individual transaction, as opposed to committing multiple statements as a single transaction.

  4. Edit the registry configurations in the <API-M_2.6.0_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.6.0_HOME>/repository/conf/user-mgt.xml file, similar to the configurations of the current WSO2 API Manager.

    If you are working with a clustered/distributed API Manager setup, follow step 5 on the Gateway node.

  5. Move all your Synapse configurations to API-M 2.6.0 pack.
    • Move your Synapse super tenant configurations.
      Copy the contents in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory and replace the contents in the <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default directory with the copied contents.
    • Move all your tenant Synapse configurations.
      Copy the contents in the <CURRENT_API-M_HOME>/repository/tenants directory and replace the contents in the  <API-M_2.6.0_HOME>/repository/tenants directory with the copied contents.
  6. If you manually added any custom OSGI bundles to the <API-M_2.5.0_HOME>/repository/components/dropins directory, copy those to the <API-M_2.6.0_HOME>/repository/components/dropins directory. 
  7. If you manually added any JAR files to the <API-M_2.5.0_HOME>/repository/components/lib directory, copy those and paste them in the <API-M_2.6.0_HOME>/repository/components/lib directory. 

Step 2 - Upgrade WSO2 API-M 2.5.0 to 2.6.0

  1. Stop all WSO2 API Manager server instances that are running.

  2. Make sure you backed up all the databases and Synapse configurations as instructed in step 1 of the previous section.

  3. Upgrade the WSO2 API Manager database from version 2.5.0 to version 2.6.0.

    1. Download apimgt-db-migration-scripts-2.5to2.6.zip and extract it.

    2. Execute the relevant database script, from the scripts that are provided in the extracted directory, on the WSO2AM_DB database.

  4. Upgrade the Identity component in WSO2 API Manager from version 5.6.0 to 5.7.0.

    As WSO2 API-M shares identity components with WSO2 Identity Server (WSO2 IS), this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).

    1. Download the identity component migration resources and unzip it to a local directory.
      Navigate to the latest release tag and download the wso2is-migration-x.x.x.zip under Assets.
    2. Copy the migration-resources folder from the extracted folder to the <API-M_2.6.0_HOME> directory.

    3. Open the migration-config.yaml file in the migration-resources directory and make sure that the currentVersion element is set to 5.6.0, as shown below.

      migrationEnable: "true"

currentVersion: "5.6.0"
migrateVersion: "5.7.0"

      Make sure you have enabled migration by setting the migrationEnable element to true as shown above.

    4. Copy the JAR (org.wso2.carbon.is.migration-x.x.x.jar) from the extracted folder to the <API-M_2.6.0_HOME> /repository/components/dropins directory.

    5. Copy the keystores (i.e., client-truststore.jks, wso2cabon.jks and any other custom JKS) used in the previous version and replace the existing keystores in the <API-M_2.6.0_HOME>/repository/resources/security directory

    6. Start WSO2 API Manager 2.6.0 as follows to carry out the complete Identity component migration.

      sh wso2server.sh -Dmigrate -Dcomponent=identity
      wso2server.bat -Dmigrate -Dcomponent=identity

      If you run WSO2 API-M as a Windows Service when doing the identity component migration, then you need to add the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

      -Dmigrate -Dcomponent=identity

      Please note that depending on the number of records in the identity tables, this identity component migration will take a considerable amount of time to finish. Do not stop the server during the migration process and please wait until the migration process finish completely and server get started.

      Troubleshooting

      When running the above step if you encounter the following error message, follow the steps in this section. Note that this error could occur only if the identity tables contain a huge volume of data. 

      Sample exception stack trace
      ERROR {org.wso2.carbon.registry.core.dataaccess.TransactionManager} -  Failed to start new registry transaction. {org.wso2.carbon.registry.core.dataaccess.TransactionManager} 
org.apache.tomcat.jdbc.pool.PoolExhaustedException: [pool-30-thread-11] Timeout: Pool empty. Unable to fetch a connection in 60 seconds, none available[size:50; busy:50; idle:0; 
lastwait:60000

      1. Change the value in <indexingFrequencyInSeconds> in <API-M_HOME>/repository/conf/registry.xml file to a higher value (e.g., 10)

      2. Re-run the command above.

      Make sure to revert the change done in Step 1, after the migration is complete.

    7. After you have successfully completed the migration, stop the server and remove the following files and folders.

      • Remove the JAR (org.wso2.carbon.is.migration-x.x.x.jar) file, which is in the <API-M_2.6.0_HOME>/repository/components/dropins directory.

      • Remove the migration-resources directory, which is in the <API-M_2.6.0_HOME> directory.

      • If you ran WSO2 API-M as a Windows Service when doing the identity component migration , then you need to remove the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

        -Dmigrate -Dcomponent=identity

  5. Re-index the artifacts in the registry.

    1. Run the reg-index.sql script against the REG_DB database.

      Please note that depending on the number of records in the REG_LOG table, this script will take a considerable amount of time to finish. Do not stop the execution of script until it is completed.

    2. Add the tenantloader-1.0.jar to <API-M_2.6.0_HOME>/repository/components/dropins directory
    3. Rename the <lastAccessTimeLocation> element in the <API-M_2.6.0_HOME>/repository/conf/registry.xml file.
    4. If you use a clustered/distributed API Manager setup, change the file in the API Publisher node.
       For example, change the /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime registry path to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1
    5. If the <API-M_2.6.0_HOME>/ solr directory exists, take a backup and thereafter delete it.
    6. Start the WSO2 API-M server.
    7. Stop the WSO2 API-M server and remove the tenantloader-1.0.jar from the <API-M_2.6.0_HOME>/repository/components/dropins directory.

Step 3 - Optionally, migrate the WSO2 API-M Analytics 2.5.0 configurations to 2.6.0

This step is only required if you have WSO2 API-M-Analytics configured in your current deployment.

Before you procceed with the WSO2 API-M Analytics migration do the following, if you have already not done the configuration changes as mentioned in Step 1.

Edit the registry configurations in the <API-M_2.6.0_HOME>/repository/conf/registry.xml file and the user database configurations in the <API-M_2.6.0_HOME>/repository/conf/user-mgt.xml file so that the configurations are similar to the configurations of the current WSO2 API Manager.


Follow the steps below to migrate APIM Analytics 2.5.0 to APIM Analytics 2.6.0

Step 3.1 - Configure WSO2 API-M Analytics 2.6.0

  1. Download the WUM updated pack for WSO2 API Manager Analytics 2.6.0.

    Note that it is mandatory to use a WUM updated WSO2 API Manager Analytics 2.6.0 pack when migrating the configurations for WSO2 API-M Analytics.

  2. Create a new database for the new statistics database and configure it in the <API-M_ANALYTICS_2.6.0_HOME>/conf/worker/deployment.yaml as follows:
    In this example shows to configure MySQL database configurations.

    - name: APIM_ANALYTICS_DB
      description: "The datasource used for APIM statistics aggregated data."
      jndiConfig:
        name: jdbc/APIM_ANALYTICS_DB
      definition:
        type: RDBMS
        configuration:
          jdbcUrl: 'jdbc:mysql://localhost:3306/spDatabase?autoReconnect=true'
          username: username
          password: password
          driverClassName: com.mysql.jdbc.Driver
          maxPoolSize: 50
          idleTimeout: 60000
          connectionTestQuery: SELECT 1
          validationTimeout: 30000
          isAutoCommit: true

    In previous versions of WSO2 API-M, even though the defaultAutoCommit value was set to false in the STAT_DB, when performing Analytics migration in WSO2 API-M Analytics 2.6.0, you need to set the isAutoCommit value to true in the APIM_ANALYTICS_DB datasource configuration.

  3. Copy the relevant JDBC driver to the <APIM_ANALYTICS_2.6.0_HOME>/lib folder.

  4. Start the new API-M Analytics server.

    cd <APIM_ANALYTICS_2.6.0_HOME>/bin
sh worker.sh

    When the WSO2 API-M Analytics 2.6.0 server starts, the new statistics tables will get generated in the database that you configured in step 3.1 - (2.) above.

Step 3.2 - Configure WSO2 API-M 2.6.0 for Analytics

Follow the instructions below to configure WSO2 API Manager for the WSO2 API-M Analytics migration in order to migrate the statistics related data.

  1. Configure the statistics related datasources for WSO2 API Manager Analytics.
    Configure the following 3 datasources in the <API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml file.

    The following 3 datasources should be configured in the <API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml file only until the stats migration is complete . After the statistics migration is complete remove the APIM_ANALYTICS_DB datasource configuration, which was added for the new statistics database, from the latter mentioned file.

    The following in an example of how the configurations should be defined when using MySQL.

      • The first datasource points to the previous API-M version's AM_DB datasource.

              <datasource>
            <name>WSO2AM_DB</name>
            <description>The datasource used for API Manager database</description>
            <jndiConfig>
                <name>jdbc/WSO2AM_DB</name>
            </jndiConfig>
            <definition type="RDBMS">
                <configuration>
                    <url>jdbc:mysql://localhost:3306/AM_DB?autoReconnect=true</url>
                    <username>username</username>
                    <password>password</password>
                    <defaultAutoCommit>true</defaultAutoCommit>
                    <driverClassName>com.mysql.jdbc.Driver</driverClassName>
                    <maxActive>50</maxActive>
                    <maxWait>60000</maxWait>
                    <testOnBorrow>true</testOnBorrow>
                    <validationQuery>SELECT 1</validationQuery>
                    <validationInterval>30000</validationInterval>
                </configuration>
            </definition>
     </datasource>

      • The second datasource points to the WSO2 Data Analytics (WSO2 DAS) based previous datasource WSO2AM_STATS_DB for statistics.

               <datasource>
            <name>WSO2AM_STATS_DB</name>
            <description>The datasource used for getting statistics to API Manager</description>
            <jndiConfig>
                <name>jdbc/WSO2AM_STATS_DB</name>
            </jndiConfig>
            <definition type="RDBMS">
                <configuration>
                    <url>jdbc:mysql://localhost:3306/dasDatabase?autoReconnect=true</url>
                    <username>username</username>
                    <password>password</password>
                    <defaultAutoCommit>true</defaultAutoCommit>
                    <driverClassName>com.mysql.jdbc.Driver</driverClassName>
                    <maxActive>50</maxActive>
                    <maxWait>60000</maxWait>
                    <testOnBorrow>true</testOnBorrow>
                    <validationQuery>SELECT 1</validationQuery>
                    <validationInterval>30000</validationInterval>
                </configuration>
            </definition>
         </datasource>

      • The third datasource points to the WSO2 Stream Processor (WSO2 SP) based new datasource APIM_ANALYTICS_DB for statistics.

                 <datasource>
            <name>APIM_ANALYTICS_DB</name>
            <description>The datasource used for getting statistics to API Manager for APIM 2.6.0</description>
            <jndiConfig>
                <name>jdbc/APIM_ANALYTICS_DB</name>
            </jndiConfig>
            <definition type="RDBMS">
                <configuration>
                    <url>jdbc:mysql://localhost:3306/spDatabase?autoReconnect=true</url>
                    <username>username</username>
                    <password>password</password>
                    <defaultAutoCommit>true</defaultAutoCommit>
                    <driverClassName>com.mysql.jdbc.Driver</driverClassName>
                    <maxActive>50</maxActive>
                    <maxWait>60000</maxWait>
                    <testOnBorrow>true</testOnBorrow>
                    <validationQuery>SELECT 1</validationQuery>
                    <validationInterval>30000</validationInterval>
                </configuration>
            </definition>
         </datasource>
  2. Download and extract the WSO2 API Manager migration client and carry out the following steps to upgrade to WSO2 API Manager Analytics 2.6.0.
  3. Copy the migrate.client-2.6.x-1.jar to the <API-M_2.6.0_HOME>/repository/components/dropins folder.
  4. Copy the relevant JDBC driver to the <API-M_2.6.0_HOME>/repository/components/lib folder.

  5. Make sure that WSO2 API-M Analytics is disabled in the <API-M_2.6.0_HOME>/repository/conf/ api-manager.xml file.

    <Analytics>    
	<Enabled>false</Enabled>
    ...
<Analytics>

  6. After setting the above configurations in place, start up the WSO2 API-M 2.6.0 server with the following commands.

    cd <API-M_2.6.0_HOME>/bin
sh wso2server.sh -DmigrateStats=true

    Table-wise Migration

    The migration client provides the support for table-wise migration.

    The following are the table names that needs to be migrated.

    ApiPerDestinationAgg,ApiResPathPerApp,ApiVersionPerAppAgg,ApiLastAccessSummary,ApiFaultyInvocationAgg,ApiUserBrowserAgg,GeoLocationAgg,ApiExeTimeDay,ApiExeTimeHour,ApiExeTimeMinute,ApiThrottledOutAgg,APIM_ReqCountAgg,ApiUserPerAppAgg

    You need to use the statTable migration property for table wise migration.

    For example, if you need to migrate only the ApiPerDestinationAgg and ApiResPathPerApp tables use the following command:

    When you need to migrate multiple tables, the comma separated table names should without spaces before or after the comma as shown below.

    sh wso2server.sh -DmigrateStats=true -DstatTable=ApiPerDestinationAgg,ApiResPathPerApp

    If the default 3 datasource names/name, which you specified above, changed from the details that you specified in the <API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml file. Use the following command to pass the values to the migration client.

     Click here to see a code snippet of the definition of the datasource name...
    <jndiConfig>
	<name>jdbc/WSO2AM_DB</name>
</jndiConfig>
    sh wso2server.sh -DdataSource=<AM_DATASOURCE_NAME>,<OLD_STAT_DATASOURCE_NAME>,<NEW_STAT_DATASOURCE_NAME>
    sh wso2server.sh -DdataSource=jdbc/WSO2AM_DB,jdbc/WSO2AM_STATS_DB,jdbc/APIM_ANALYTICS_DB

    The following warning message could occur during migration if the relevant consumer key does not exist in the AM_APPLICATION_KEY_MAPPING table due to Application deletion.

    ConsumerKey <consumerKey> does not contain in the AM_APPLICATION_KEY_MAPPING table.

    In such scenarios, you will face a migration data loss due to API or Application deletion.

  7. Stop the WSO2 API-M server and remove the migration JAR copied under Step 3.2 - (3.) above.
  8. Remove both the old and new STAT_DB datasources from the <API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml file, which you defined in step 3.2 - (1.).

  9. Enable analytics in WSO2 API-M by setting the following configuration to true in the <API-M_2.6.0_HOME>/repository/conf/ api-manager.xml file.

    <Analytics>    
	<Enabled>true</Enabled>
    ...
<Analytics>

  10. Restart the WSO2 API-M Server.

    cd <API-M_2.6.0_HOME>/bin
sh wso2server.sh

Step 4 - Start the WSO2 API-M 2.6.0 server

sh wso2server.sh

wso2server.bat

Follow the instructions below to upgrade your WSO2 API Manager server from WSO2 API-M 2.2.0 to 2.6.0. 

If you are using WSO2 Identity Server (WSO2 IS) as a Key Manager, follow the instructions in Upgrading from the Previous Release when WSO2 IS is the Key Manager.

Step 1 - Migrate the WSO2 API-M 2.2.0 configurations

Do not copy entire configuration files from the current version of WSO2 API Manager to the new one, as some configuration files (e.g., api-manager.xml) may have changed. Instead, redo the configuration changes in the new configuration files.

Follow the instructions below to move all the existing API Manager configurations from the current environment to the new one.

  1. Back up all databases in your API Manager instances along with the Synapse configs of all the tenants and the super tenant.

    • The Synapse configs of the super tenant are in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory.

    • The Synapse configs of tenants are in the <CURRENT_APIM_HOME>/repository/tenants directory. 

    • If you use a clustered/distributed API Manager setup, back up the available configurations in the API Gateway node.

  2. Download WSO2 API Manager 2.6.0 from https://wso2.com/api-management/.

  3. Open the <API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml file and provide the datasource configurations for the following databases. You can copy the configuration values from the same file in the current WSO2 API Manager instance already being used.

    • User Store
    • Registry database/s
    • API Manager databases

    • Statistics database (If statistics are configured)

      Unlike in previous WSO2 API-M versions, in WSO2 API-M 2.6.0 the defaultAutoCommit property is set to true by default for the following datasource configurations in the master-datasources.xml file.

      • WSO2_CARBON_DB
      • WSO2AM_DB
      • WSO2AM_STATS_DB

      When auto committing is enabled, each SQL statement will be committed to the database as an individual transaction, as opposed to committing multiple statements as a single transaction.

  4. Edit the registry configurations in the <API-M_2.6.0_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.6.0_HOME>/repository/conf/user-mgt.xml file, similar to the configurations of the current API Manager.

    If you are working with a clustered/distributed API Manager setup, follow step 5 on the Gateway node.

  5. Move all your Synapse configurations to API-M 2.6.0 pack.
    • Move your Synapse super tenant configurations.
      Copy the contents in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory and replace the contents in the <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default directory with the copied contents.
    • Move all your tenant Synapse configurations.
      Copy the contents in the <CURRENT_API-M_HOME>/repository/tenants directory and replace the contents in the  <API-M_2.6.0_HOME>/repository/tenants directory with the copied contents.
  6. If you manually added any custom OSGI bundles to the <API-M_2.2.0_HOME>/repository/components/dropins directory, copy those to the <API-M_2.6.0_HOME>/repository/components/dropins directory. 
  7. If you manually added any JAR files to the <API-M_2.2.0_HOME>/repository/components/lib directory, copy those and paste them in the <API-M_2.6.0_HOME>/repository/components/lib directory. 

Step 2 - Upgrade WSO2 API-M 2.2.0 to 2.6.0

  1. Stop all WSO2 API Manager server instances that are running.

  2. Make sure you backed up all the databases and Synapse configs, as instructed in step 1 of the previous section.

  3. To start the migration process, run the respective migration script based on your environment. 

    Run the apim220_to_apim260_gateway_artifact_migrator.sh script, as shown below, to migrate from WSO2 API Manager 2.2.0 to 2.6.0. 

    ./apim220_to_apim260_gateway_artifact_migrator.sh <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.2.0 deployment, reside.

    The API definition paths <API-definition-path> are as follows:

    • Super Tenant - <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default

    • Tenant - <API-M_2.6.0_HOME>/repository/tenants

    Where, <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0.

    Run the PowerShell script apim220_to_apim260_gateway_artifact_migrator.ps1 as shown below, to migrate from WSO2 API Manager 2.2.0 to 2.6.0.

    1. Open a Windows command prompt and type the following command.

      powershell

      A message about PowerShell appears, and the shell changes to PowserShell (PS).

    2. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

      .\apim220_to_apim260_gateway_artifact_migrator.ps1 <API-definitions-path>

      <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.2.0 deployment, reside.

      • Super Tenant - <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default

      Where <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0.

    Run the PowerShell script apim220_to_apim260_gateway_artifact_migrator_for_tenants.ps1 as follows:

    1. Open a Windows command prompt and type the following command.

      powershell

      A message about PowerShell appears, and the shell changes to PowerShell (PS).

    2. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

      .\apim220_to_apim260_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>

      <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.2.0 deployment, reside.

      • Tenants - <API-M_2.6.0_HOME>/repository/tenants

      Where <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0.

    It may take a considerable amount of time, which is proportionate to the amount of artifacts, to complete the migration process.

    Troubleshooting

    Why do I get the following error - apim220_to_apim260_gateway_artifact_migrator.ps1 / apim220_to_apim250_gateway_artifact_migrator_for_tenants.ps1 cannot be loaded because the execution of scripts is disabled on this system?

    When running the apim220_to_apim260_gateway_artifact_migrator.ps1 script, if the execution process is aborted with the above error, it means that the execution of unknown scripts is disabled in the system.

    To overcome this issue and allow the execution of such scripts, run the following command in the terminal/command-line as the Administrator.

    Set-ExecutionPolicy RemoteSigned

  4. Upgrade the API Manager database from version 2.2.0 to version 2.6.0.

    1. Download apimgt-db-migration-scripts-2.2to2.6.zip and extract it.

    2. Execute the relevant database script, from the scripts that are provided in the extracted directory, on the WSO2AM_DB database.

  5. Upgrade the Identity component in WSO2 API Manager from version 5.5.0 to 5.7.0.

    As WSO2 API-M shares identity components with WSO2 IS, this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).

    1. Download the identity component migration resources and unzip it to a local directory.
      Navigate to the latest release tag and download the wso2is-migration-x.x.x.zip under Assets.
    2. Copy the migration-resources folder from the extracted folder to the <API-M_2.6.0_HOME> directory.

    3. Open the migration-config.yaml file in the migration-resources directory and make sure define the currentVersion element to 5.5.0, as shown below.

      migrationEnable: "true"

currentVersion: "5.5.0"
migrateVersion: "5.7.0"

      Make sure you have enabled migration by setting the migrationEnable element to true as shown above.

    4. Copy the JAR (org.wso2.carbon.is.migration-x.x.x.jar) from the extracted folder to the <API-M_2.6.0_HOME>/repository/components/dropins directory.

    5. Copy the keystores (i.e., client-truststore.jks, wso2cabon.jks and any other custom JKS) used in the previous version and replace the existing keystores in the <API-M_2.6.0_HOME>/repository/resources/security directory.

    6. Start WSO2 API Manager 2.6.0 via the terminal as follows to carry out the complete Identity component migration.

      sh wso2server.sh -Dmigrate -Dcomponent=identity
      wso2server.bat -Dmigrate -Dcomponent=identity

      If you run WSO2 API-M as a Windows Service when doing the identity component migration, then you need to add the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

      -Dmigrate -Dcomponent=identity

      Please note that depending on the number of records in the identity tables, this identity component migration will take a considerable amount of time to finish. Do not stop the server during the migration process and please wait until the migration process finish completely and server get started.

      Troubleshooting

      When running the above step if you encounter the following error message, please follow the steps in this section. Please note that this error could occur only if the identity tables contain a huge volume of data.

      Sample exception stack trace
      ERROR {org.wso2.carbon.registry.core.dataaccess.TransactionManager} -  Failed to start new registry transaction. {org.wso2.carbon.registry.core.dataaccess.TransactionManager} 
    org.apache.tomcat.jdbc.pool.PoolExhaustedException: [pool-30-thread-11] Timeout: Pool empty. Unable to fetch a connection in 60 seconds, none available[size:50; busy:50; idle:0; 
lastwait:60000

      1. Change the value in <indexingFrequencyInSeconds> in <API-M_HOME>/repository/conf/registry.xml to a higher value (e.g., 10)

      2. Re-run the command above.

      Make sure to revert the change done in Step 1 , after the migration is complete

    7. After you have successfully completed the migration, stop the server and remove the following files and folders.

      • Remove the JAR (org.wso2.carbon.is.migration-x.x.x.jar) file, which is in the <API-M_2.6.0_HOME>/repository/components/dropins directory.

      • Remove the migration-resources directory, which is in the <API-M_2.6.0_HOME> directory.

      • If you ran WSO2 API-M as a Windows Service when doing the identity component migration , then you need to remove the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

        -Dmigrate -Dcomponent=identity

  6. Re-index the artifacts in the registry.

    1. Run the reg-index.sql script against the REG_DB database.

      Please note that depending on the number of records in the REG_LOG table, this script will take a considerable amount of time to finish. Do not stop the execution of script until it is completed.

    2. Add the tenantloader-1.0.jar to <API-M_2.6.0_HOME>/repository/components/dropins directory.

    3. Rename the <lastAccessTimeLocation> element in the <API-M_2.6.0_HOME>/repository/conf/registry.xml file.

    4. If you use a clustered/distributed API Manager setup, change the file in the API Publisher node.
      For example, change the /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime registry path to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1  

    5. If the <API-M_2.6.0_HOME>/ solr directory exists, take a backup and thereafter delete it.

    6. Start the WSO2 API-M server.

    7. Stop the WSO2 API-M server and remove the tenantloader-1.0.jar from the <API-M_2.6.0_HOME>/repository/components/dropins directory.

Step 3 - Optionally, migrate the WSO2 API-M Analytics 2.2.0 configurations to 2.6.0

This step is only required if you have WSO2 API-M-Analytics configured in your current deployment.

As you are upgrading from WSO2 API-M Analytics 2.2.0, in order migrate the configurations required to run WSO2 API-M Analytics for WSO2 API-M 2.6.0 carryout the same instructions as mentioned in

Upgrading from 2.5.0 to 2.6.0 - Step 3 - Optionally, migrate the configurations for WSO2 API-M Analytics.

Step 4 - Restart the WSO2 API-M 2.6.0 server

sh wso2server.sh

wso2server.bat

Follow the instructions below to upgrade your WSO2 API Manager server from WSO2 API-M 2.1.0 to 2.6.0. 

If you are using WSO2 Identity Server (WSO2 IS) as a Key Manager, follow the instructions in Upgrading from the Previous Release when WSO2 IS is the Key Manager.

Step 1 - Migrate the WSO2 API-M 2.1.0 configurations

Do not copy entire configuration files from the current version of WSO2 API Manager to the new one, as some configuration files (e.g., api-manager.xml) may have changed. Instead, redo the configuration changes in the new configuration files.

Follow the instructions below to move all the existing API Manager configurations from the current environment to the new one.

  1. Back up all databases in your API Manager instances along with the Synapse configs of all the tenants and the super tenant.

    • The Synapse configs of the super tenant are in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory.

    • The Synapse configs of tenants are in the <CURRENT_APIM_HOME>/repository/tenants directory. 

    • If you use a clustered/distributed API Manager setup, back up the available configurations in the API Gateway node.

  2. Download API Manager 2.6.0 from https://wso2.com/api-management/.

  3. Open the <API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml file and provide the datasource configurations for the following databases.
    You can copy the configuration values from the same file in the current WSO2 API Manager instance that is already being used.

    • User Store
    • Registry database/s
    • API Manager databases

    • Statistics database (If statistics are configured)

      Unlike in previous WSO2 API-M versions, in WSO2 API-M 2.6.0 the defaultAutoCommit property is set to true by default for the following datasource configurations in the master-datasources.xml file.

      • WSO2_CARBON_DB
      • WSO2AM_DB
      • WSO2AM_STATS_DB

      When auto committing is enabled, each SQL statement will be committed to the database as an individual transaction, as opposed to committing multiple statements as a single transaction.

  4. Edit the registry configurations in the <API-M_2.6.0_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.6.0_HOME>/repository/conf/user-mgt.xml file, similar to the configurations of the current API Manager. 

    In a clustered/distributed API Manager setup, follow steps 5 and 6 for the Gateway node.

  5. Move all your Synapse configurations with the exception of the files mentioned below, by copying the contents in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory and by using it to replace the contents of the <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default directory. 

    NOTE: Do not replace the files listed below from the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default folder to API Manager 2.6.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, you need to merge the changes to the corresponding files in 2.6.0.

    /api/_AuthorizeAPI_.xml
    /api/_RevokeAPI_.xml
    /api/_TokenAPI_.xml
    /api/_UserInfoAPI_.xml
    /sequences/_auth_failure_handler_.xml
    /sequences/_build_.xml
    /sequences/_cors_request_handler_.xml
    /sequences/fault.xml
    /sequences/main.xml
    /sequences/_production_key_error_.xml
    /sequences/_resource_mismatch_handler_.xml
    /sequences/_sandbox_key_error_.xml
    /sequences/_throttle_out_handler_.xml
    /sequences/_token_fault_.xml
    /proxy-services/WorkflowCallbackService.xml

  6. Move all your tenant Synapse configurations by copying the contents in the <CURRENT_API-M_HOME>/repository/tenants directory and adding the copied contents to the <API-M_2.6.0_HOME>/repository/tenants directory.

    NOTE: Copy the files listed below from the <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default/sequences directory and replace the corresponding files in the <API-M_2.6.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default/sequences directory.

    _auth_failure_handler_.xml
    _cors_request_handler_.xml
    fault.xml
    main.xml
    _production_key_error_.xml
    _resource_mismatch_handler_.xml
    _sandbox_key_error_.xml
    _throttle_out_handler_.xml

    In a clustered/distributed API Manager setup, do this step on the Gateway node.

  7. If you manually added any custom OSGI bundles to the <API-M_2.1.0_HOME>/repository/components/dropins directory, copy those to the <API-M_2.6.0_HOME>/repository/components/dropins directory. 
  8. If you manually added any JAR files to the <API-M_2.1.0_HOME>/repository/components/lib directory, copy those and paste them in the <API-M_2.6.0_HOME>/repository/components/lib directory. 

Step 2 - Upgrade WSO2 API-M 2.1.0 to 2.6.0

  1. Stop all WSO2 API Manager server instances that are running.

  2. Make sure you backed up all the databases and Synapse configs, as instructed in step 1 of the previous section.

  3. To start the migration process, run the respective migration script based on your environment. 

    Run the apim210_to_apim260_gateway_artifact_migrator.sh script, as shown below, to migrate from WSO2 API Manager 2.1.0 to 2.6.0. 

    ./apim210_to_apim260_gateway_artifact_migrator.sh <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the WSO2 API-M 2.1.0 deployment, reside.

    The API definition paths <API-definition-path> are as follows:

    • Super Tenant - <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default

    • Tenant - <API-M_2.6.0_HOME>/repository/tenants

    Where, <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0.

    Run the PowerShell script apim210_to_apim260_gateway_artifact_migrator.ps1 as follows:

    1. Open a Windows command prompt and type the following command.

      powershell

      A message about PowerShell appears, and the shell changes to PowerShell (PS).

    2. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

      .\apim210_to_apim260_gateway_artifact_migrator.ps1 <API-definitions-path>

      <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the WSO2 API-M 2.1.0 deployment, reside.

      • Super Tenant - <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default

      Where <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0.

    Run the PowerShell script apim210_to_apim260_gateway_artifact_migrator_for_tenants.ps1 as follows:

    1. Open a Windows command prompt and type the following command.

      powershell

      A message about PowerShell appears, and the shell changes to PowerShell (PS).

    2. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

      .\apim210_to_apim260_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>

      <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the WSO2 API-M 2.1.0 deployment, reside.

      • Tenants - <API-M_2.6.0_HOME>/repository/tenants

      Where <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0.

    It may take a considerable amount of time, which is proportionate to the amount of artifacts, to complete the migration process.

    Troubleshooting

    Why do I get the following error - apim210_to_apim260_gateway_artifact_migrator.ps1 / apim210_to_apim260_gateway_artifact_migrator_for_tenants.ps1 cannot be loaded because the execution of scripts is disabled on this system?

    When running the apim210_to_apim260_gateway_artifact_migrator.ps1 script, if the execution process is aborted with the above error, it means that the execution of unknown scripts is disabled in the system. To overcome this issue and allow the execution of such scripts, run the following command in the terminal as the Administrator.

    Set-ExecutionPolicy RemoteSigned

  4. Upgrade the WSO2 API Manager database from version 2.1.0 to version 2.6.0.

    1. Download the apimgt-db-migration-scripts-2.1to2.6.zip and extract it.

    2. Execute the relevant database script, from the scripts that are provided in the extracted directory, on the WSO2AM_DB database.

  5. If your MB Store database on WSO2 API-M 2.1.0 is not the default H2 DB, upgrade the MB Store database from version 3.1.0 to version 3.2.0.

    It is recommended to use the default H2 database for the MB store database in API-Manager.

    1. Download mb-store-migration-scripts-3.1.0_to_3.2.0.zip and extract it.

    2. Execute the relevant database script, from the scripts that are provided in the extracted directory, on the WSO2_MB_STORE_DB database.

  6. Upgrade the Identity component in WSO2 API Manager from version 5.3.0 to 5.7.0.

    As WSO2 API-M shares identity components with WSO2 IS, this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).

    1. Download the identity component migration resources and unzip it to a local directory.
      Navigate to the latest release tag and download the wso2is-migration-x.x.x.zip under Assets.
    2. Copy the migration-resources folder from the extracted folder to the <API-M_2.6.0_HOME> directory.

    3. Open the migration-config.yaml file in the migration-resources directory and edit the currentVersion element to 5.3.0, as shown below.

      migrationEnable: "true"

currentVersion: "5.3.0"
migrateVersion: "5.7.0"

      Make sure you have enabled migration by setting the migrationEnable element to true.

    4. Remove the following entry from the migration-config.yaml file.

         -
    name: "EventPublisherMigrator"
    order: 11

    5. Copy the JAR (org.wso2.carbon.is.migration-x.x.x.jar) from the extracted folder to the <API-M_2.6.0_HOME> / repository/components/dropins directory.

    6. Copy the keystores (i.e., client-truststore.jks, wso2cabon.jks and any other custom JKS) used in the previous version and replace the existing keystores in the <API-M_2.6.0_HOME>/repository/resources/security directory

    7. Start WSO2 API Manager 2.6.0 via the terminal to carry out the complete Identity component migration.

      sh wso2server.sh -Dmigrate -Dcomponent=identity
      wso2server.bat -Dmigrate -Dcomponent=identity

      If you run WSO2 API-M as a Windows Service when doing the identity component migration, then you need to add the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

      -Dmigrate -Dcomponent=identity

      Please note that depending on the number of records in the identity tables, this identity component migration will take a considerable amount of time to finish. Do not stop the server during the migration process and please wait until the migration process finish completely and server get started.

      Troubleshooting

      When running the above step if you encounter the following error message, please follow the steps in this section. Please note that this error could occur only if the identity tables contain a huge volume of data.

      Sample exception stack trace
      ERROR {org.wso2.carbon.registry.core.dataaccess.TransactionManager} -  Failed to start new registry transaction. {org.wso2.carbon.registry.core.dataaccess.TransactionManager} 
org.apache.tomcat.jdbc.pool.PoolExhaustedException: [pool-30-thread-11] Timeout: Pool empty. Unable to fetch a connection in 60 seconds, none available[size:50; busy:50; idle:0; 
lastwait:60000

      1. Change the value in <indexingFrequencyInSeconds> in <APIM_HOME>/repository/conf/registry.xml to a higher value (e.g., 10)

      2. Re-run the command above.

      Make sure to revert the change done in Step 1, after the migration is complete

    8. After you have successfully completed the migration, stop the server and remove the following files and folders.

      • Remove the JAR (org.wso2.carbon.is.migration-x.x.x.jar) file, which is in the <API-M_2.6.0_HOME>/repository/components/dropins directory.

      • Remove the migration-resources folder, which is in the <API-M_2.6.0_HOME> directory.

      • If you ran WSO2 API-M as a Windows Service when doing the identity component migration , then you need to remove the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

        -Dmigrate -Dcomponent=identity


    1. Download WSO2 API Manager Migration Client, extract and copy org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar to <API-M_HOME>/repository/components/dropins directory.

    2. Start the WSO2 API-M server as follows.

      sh wso2server.sh -DmigrateAccessControl=true

  8. Re-index the artifacts in the registry.

    1. Shut down WSO2 API Manager 2.6.0 (if you have already started it).

    2. Run the reg-index.sql script against the REG_DB database.

      Please note that depending on the number of records in the REG_LOG table, this script will take a considerable amount of time to finish. Do not stop the execution of script until it is completed.

    3. Add the tenantloader-1.0.jar to <API-M_2.6.0_HOME>/repository/components/dropins directory

    4. Rename the <lastAccessTimeLocation> element in the <API-M_2.6.0_HOME>/repository/conf/registry.xml file.

    5. If you use a clustered/distributed API Manager setup, change the file in the API Publisher node.
      For example, change the /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime registry path to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1  

    6. If the <API-M_2.6.0_HOME>/ solr directory exists, take a backup and thereafter delete it.

    7. Start the WSO2 API-M server.
    8. Stop the WSO2 API-M server and remove the tenantloader-1.0.jar from the <API-M_2.6.0_HOME>/repository/components/dropins directory.
      Make sure to remove the WSO2 API-M client migration jar (org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar) from the <API-M_2.6.0_HOME>/repository/components/dropins directory as well.

Step 3 - Optionally, migrate the WSO2 API-M Analytics 2.1.0 configurations to 2.6.0

This step is only required if you have API-M-Analytics configured in your current deployment.

As you are upgrading from WSO2 API-M Analytics 2.1.0, in order migrate the configurations required to run WSO2 API-M Analytics for WSO2 API-M 2.6.0 carryout the same instructions as mentioned in

Upgrading from 2.5.0 to 2.6.0 - Step 3 - Optionally, migrate the configurations for WSO2 API-M Analytics.

Step 4 - Restart the WSO2 API-M 2.6.0 server

sh wso2server.sh

wso2server.bat

Follow the instructions below to upgrade your WSO2 API Manager server from WSO2 API-M 2.0.0 to 2.6.0. 

If you are using WSO2 Identity Server (WSO2 IS) as a Key Manager, follow the instructions in Upgrading from the Previous Release when WSO2 IS is the Key Manager.

Step 1 - Migrate the WSO2 API-M 2.0.0 configurations

Do not copy entire configuration files from the current version of API Manager to the new one, as some configuration files (e.g., api-manager.xml) may have changed. Instead, redo the configuration changes in the new configuration files.

In this section, you move all existing API Manager configurations from the current environment to the new one.

  1. Back up all databases in your API Manager instances along with the Synapse configs of all the tenants and the super tenant.

    • The Synapse configs of the super tenant are in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory.

    • The Synapse configs of tenants are in the <CURRENT_APIM_HOME>/repository/tenants directory. 

    • If you use a clustered/distributed API Manager setup, back up the available configurations in the API Gateway node.

  2. Download API Manager 2.6.0 from https://wso2.com/api-management/.

  3. Open the <API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml file and provide the datasource configurations for the following databases.
    You can copy the configuration values from the same file in the current WSO2 API Manager instance that is already being used.

    • User Store
    • Registry database/s
    • API Manager databases

    • Statistics database (if statistics are configured)

      Unlike in previous WSO2 API-M versions, in WSO2 API-M 2.6.0 the defaultAutoCommit property is set to true by default for the following datasource configurations in the master-datasources.xml file.

      • WSO2_CARBON_DB
      • WSO2AM_DB
      • WSO2AM_STATS_DB

      When auto committing is enabled, each SQL statement will be committed to the database as an individual transaction, as opposed to committing multiple statements as a single transaction.

  4. Edit the registry configurations in the <API-M_2.6.0_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.6.0_HOME>/repository/conf/user-mgt.xml file similar to the configurations of the current WSO2 API Manager. 

    In a clustered/distributed API Manager setup, follow steps 5 and 6 for the Gateway node.

  5. Move all your Synapse configurations, except the files mentioned below, by copying the contents of the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory and by using it to replace the contents of the <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default directory. 

    NOTE: Do not replace the files listed below from the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default folder to WSO2 API Manager 2.6.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, you need to merge the changes to the corresponding files in WSO2 API-M 2.6.0.

    /api/_AuthorizeAPI_.xml
    /api/_RevokeAPI_.xml
    /api/_TokenAPI_.xml
    /api/_UserInfoAPI_.xml
    /sequences/_auth_failure_handler_.xml
    /sequences/_build_.xml
    /sequences/_cors_request_handler_.xml
    /sequences/fault.xml
    /sequences/main.xml
    /sequences/_production_key_error_.xml
    /sequences/_resource_mismatch_handler_.xml
    /sequences/_sandbox_key_error_.xml
    /sequences/_throttle_out_handler_.xml
    /sequences/_token_fault_.xml
    /proxy-services/WorkflowCallbackService.xml

  6. Move all your tenant Synapse configurations by updating the configurations made in the <CURRENT_API-M_HOME>/repository/tenants directory to the <API-M_2.6.0_HOME>/repository/tenants directory.

    NOTE: Get the files listed below from the <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default/sequences directory and replace the corresponding files in the <API-M_2.6.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default/sequences directory.

    _auth_failure_handler_.xml
    _cors_request_handler_.xml
    fault.xml
    main.xml
    _production_key_error_.xml
    _resource_mismatch_handler_.xml
    _sandbox_key_error_.xml
    _throttle_out_handler_.xml

    In a clustered/distributed API Manager setup, follow this step for the Gateway node.

  7. If you manually added any custom OSGI bundles to the <API-M_2.0.0_HOME>/repository/components/dropins directory, copy those to the <API-M_2.6.0_HOME>/repository/components/dropins directory. 
  8. If you manually added any JAR files to the <API-M_2.0.0_HOME>/repository/components/lib directory, copy those and paste them in the <API-M_2.6.0_HOME>/repository/components/lib directory. 

Step 2 - Upgrade WSO2 API-M 2.0.0 to 2.6.0

  1. Stop all WSO2 API Manager server instances that are running.

  2. Make sure you backed up all the databases and Synapse configs as instructed in step 1 of the previous section.

  3. To start the migration process, run the respective migration script based on your environment. 

    Run the apim200_to_apim260_gateway_artifact_migrator.sh  script, as shown below, to migrate from API Manager 2.0.0 to 2.6.0. 

    ./apim200_to_apim260_gateway_artifact_migrator.sh <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the WSO2 API-M 2.0.0 deployment, reside.

    The API definition paths <API-definition-path> are as follows:

    • Super Tenant - <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default

    • Tenant - <API-M_2.6.0_HOME>/repository/tenants

    Where, <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0. 

    Run the PowerShell script apim200_to_apim260_gateway_artifact_migrator.ps1 as follows:

    1. Open a Windows command prompt and type the following command.

      powershell

      A message about PowerShell appears, and the shell changes to PowerShell (PS).

    2. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

      .\apim200_to_apim260_gateway_artifact_migrator.ps1 <API-definitions-path>

      <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which are copied from the WSO2 API-M 2.0.0 deployment, reside.

      • Super Tenant - <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default

      Where <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0.

    Run the PowerShell script apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1 as follows:

    1. Open a Windows command prompt and type the following command.

      powershell

      A message about PowerShell appears, and the shell changes to PowerShell ( PS).

    2. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

      .\apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>

      <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.0.0 deployment, reside.

      • Tenants - <API-M_2.6.0_HOME>/repository/tenants

      Where <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0.

    It may take a considerable amount of time, which is proportionate to the amount of artifacts, to complete the migration process.

    Troubleshooting

    Why do I get the following error - apim200_to_apim260_gateway_artifact_migrator.ps1 / apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1 cannot be loaded because the execution of scripts is disabled on this system?

    When running the apim200_to_apim260_gateway_artifact_migrator.ps1 script, if the execution process is aborted with the above error, it means that the execution of unknown scripts is disabled in the system. To overcome this issue and allow the execution of such scripts, run the following command in the terminal as the Administrator.

    Set-ExecutionPolicy RemoteSigned

  4. Upgrade the WSO2 API Manager database from version 2.0.0 to version 2.6.0.

    1. Download the apimgt-db-migration-scripts-2.0to2.6.zip ZIP and extract it.

    2. Execute the relevant database script, from the scripts that are provided in the extracted directory, on the WSO2AM_DB database.

  5. Upgrade the Identity component in WSO2 API Manager from version 5.2.0 to 5.7.0.

    As WSO2 API-M shares identity components with WSO2 IS, this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).

    1. Download the identity component migration resources and unzip it to a local directory.
      Navigate to the latest release tag and download the wso2is-migration-x.x.x.zip under Assets.

    2. Copy the migration-resources folder in the extracted folder to the <API-M_2.6.0_HOME>.

    3. Open the migration-config.yaml file in the migration-resources directory and edit the currentVersion element to 5.2.0, as shown below.

      migrationEnable: "true"

currentVersion: "5.2.0"
migrateVersion: "5.7.0"

      Make sure you have enabled migration by setting the migrationEnable element to true as defined above.

    4. Remove the following entries from the migration-config.yaml file, which is in the migration-resources directory.

         -
    name: "EventPublisherMigrator"
    order: 11

      and

         -
    name: "ChallengeQuestionDataMigrator"
    order: 6
    parameters:
      schema: "identity"

    5. Copy the JAR (org.wso2.carbon.is.migration-x.x.x.jar) from the extracted folder to the <API-M_2.6.0_HOME>/repository/components/dropins directory.

    6. Copy the keystores (i.e., client-truststore.jks, wso2cabon.jks and any other custom JKS) used in the previous version and replace the existing keystores in the <API-M_2.6.0_HOME>/repository/resources/security directory.

    7. Start WSO2 API Manager 2.6.0 via the terminal to carry out the complete Identity component migration.

      sh wso2server.sh -Dmigrate -Dcomponent=identity
      wso2server.bat -Dmigrate -Dcomponent=identity

      If you run WSO2 API-M as a Windows Service when doing the identity component migration, then you need to add the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

      -Dmigrate -Dcomponent=identity

      Please note that depending on the number of records in the identity tables, this identity component migration will take a considerable amount of time to finish. Do not stop the server during the migration process and please wait until the migration process finish completely and server get started.

      Troubleshooting

      When running the above step if you encounter the following error message, please follow the steps in this section. Please note that this error could occur only if the identity tables contain a huge volume of data.

      Sample exception stack trace
      ERROR {org.wso2.carbon.registry.core.dataaccess.TransactionManager} -  Failed to start new registry transaction. {org.wso2.carbon.registry.core.dataaccess.TransactionManager} 
org.apache.tomcat.jdbc.pool.PoolExhaustedException: [pool-30-thread-11] Timeout: Pool empty. Unable to fetch a connection in 60 seconds, none available[size:50; busy:50; idle:0; 
lastwait:60000

      1. Change the value in <indexingFrequencyInSeconds> in <API-M_HOME>/repository/conf/registry.xml to a higher value (e.g.,10)

      2. Re-run the command above.

      Make sure to revert the change done in Step 1 , after the migration is complete

    8. After you have successfully completed the migration, stop the server and remove the following files and folders.

      • Remove the JAR (org.wso2.carbon.is.migration-x.x.x.jar) file, which is in the <API-M_2.6.0_HOME>/repository/components/dropins directory.

      • Remove the migration-resources directory, which is in the <API-M_2.6.0_HOME> directory.

      • If you ran WSO2 API-M as a Windows Service when doing the identity component migration , then you need to remove the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

        -Dmigrate -Dcomponent=identity

  6. Stop the WSO2 API-M server if you have started it. Download the WSO2 API Manager Migration Client, extract and copy org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar to the <API-M_HOME>/repository/components/dropins  directory.

  7. Migrate Access Control support for API Publisher.
    You have to run the following migration client to migrate the Access Control support for the API Publisher, because Publisher Access Control is enabled by default in WSO2 API Manager 2.6.0.

    sh wso2server.sh -DmigrateAccessControl=true

  8. Stop the WSO2 API-M server and carryout migration for fault sequence from API-M 2.0.0 to API-M 2.6.0 using the migration client.

    sh wso2server.sh -DmigrateFromVersion=2.0.0

  9. Preserve the case sensitive behavior for the migrated resources by adding the following property to the <API-M_HOME>/repository/conf/user-mgt.xml file under <AuthorizationManager> as follows:

    <AuthorizationManager class="org.wso2.carbon.user.core.authorization.JDBCAuthorizationManager">
	...
	<Property name="PreserveCaseForResources">false</Property>
</AuthorizationManager>

  10. Re-index the artifacts in the registry.

    1. Shut down WSO2 API Manager 2.6.0 (if you have already started it).

    2. Run the reg-index.sql script against the REG_DB database.

      Please note that depending on the number of records in the REG_LOG table, this script will take a considerable amount of time to finish. Do not stop the execution of script until it is completed.

    3. Add the tenantloader-1.0.jar to <API-M_2.6.0_HOME>/repository/components/dropins directory

    4. Rename the <lastAccessTimeLocation> element in the <API-M_2.6.0_HOME>/repository/conf/registry.xml file.

    5. If you use a clustered/distributed API Manager setup, change the file in the API Publisher node.
      For example, change the /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime registry path to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1  

    6. If the <API-M_2.6.0_HOME>/ solr directory exists, take a backup and thereafter delete it.

    7. Start the WSO2 API-M server.

    8. Stop the WSO2 API-M server and remove the tenantloader-1.0.jar from the <API-M_2.6.0_HOME>/repository/components/dropins directory. Make sure to remove the WSO2 API-M client migration jar (org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar) from the <API-M_2.6.0_HOME>/repository/components/dropins directory as well.

Step 3 - Optionally, migrate the WSO2 API-M Analytics 2.0.0 configurations to 2.6.0

This step is only required if you have WSO2 API-M Analytics configured in your current deployment.

As you are upgrading from WSO2 API-M Analytics 2.0.0, in order migrate the configurations required to run WSO2 API-M Analytics for WSO2 API-M 2.6.0 carryout the same instructions as mentioned in Upgrading from 2.5.0 to 2.6.0 - Step 3 - Optionally, migrate the configurations for WSO2 API-M Analytics.

Step 4 - Restart the WSO2 API-M 2.6.0 server

sh wso2server.sh

wso2server.bat

Follow the instructions below to upgrade your WSO2 API Manager server from APIM 1.10.0 to 2.6.0. 

If you are using WSO2 Identity Server (WSO2 IS) as a Key Manager, follow the instructions in Upgrading from the Previous Release when WSO2 IS is the Key Manager.

Do not copy entire configuration files from the current version of API Manager to the new one, as some configuration files (e.g., api-manager.xml) may have changed. Instead, redo the configuration changes in the new configuration files.

Follow the instructions below to move all the existing API Manager configurations from the current environment to the new one.

  1. Back up all databases in your API Manager instances along with the Synapse configs of all the tenants and the super tenant.

    • The Synapse configs of the super tenant are in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory.

    • The Synapse configs of tenants are in the <CURRENT_APIM_HOME>/repository/tenants directory. 

    • If you use a clustered/distributed API Manager setup, back up the available configurations in the API Gateway node.

  2. Download API Manager 2.6.0 from http://wso2.com/api-management/.

  3. Open the <API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml file and provide the datasource configurations for the following databases. You can copy the configuration values from the same file in the current WSO2 API Manager instance that is already being used.

    • User Store
    • Registry database/s
    • API Manager databases

    • Statistics database (if statistics are configured)

      Unlike in previous WSO2 API-M versions, in WSO2 API-M 2.6.0 the defaultAutoCommit property is set to true by default for the following datasource configurations in the master-datasources.xml file.

      • WSO2_CARBON_DB
      • WSO2AM_DB
      • WSO2AM_STATS_DB

      When auto committing is enabled, each SQL statement will be committed to the database as an individual transaction, as opposed to committing multiple statements as a single transaction.

  4. Edit the registry configurations in the <API-M_2.6.0_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.6.0_HOME>/repository/conf/user-mgt.xml file similar to the configurations of the current WSO2 API Manager. 

    In a clustered/distributed API Manager setup, follow steps 5 and 6 for the Gateway node.

  5. Move all your Synapse configurations, except the files mentioned below, by copying the contents in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory and by using it to replace the contents in the <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default directory.

    NOTE: Do not replace the files listed below from the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default folder to WSO2 API-M 2.6.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, you need to merge the changes to the corresponding files in 2.6.0.

    /api/_AuthorizeAPI_.xml
    /api/_RevokeAPI_.xml
    /api/_TokenAPI_.xml
    /api/_UserInfoAPI_.xml
    /sequences/_auth_failure_handler_.xml
    /sequences/_build_.xml
    /sequences/_cors_request_handler_.xml
    /sequences/fault.xml
    /sequences/main.xml
    /sequences/_production_key_error_.xml
    /sequences/_resource_mismatch_handler_.xml
    /sequences/_sandbox_key_error_.xml
    /sequences/_throttle_out_handler_.xml
    /sequences/_token_fault_.xml
    /proxy-services/WorkflowCallbackService.xml

  6. Move all your tenant Synapse configurations.
    Copy the contents in the <CURRENT_API-M_HOME>/repository/tenants directory. Replace the contents in the <API-M_2.6.0_HOME>/repository/tenants directory with the copied contents.

    NOTE: Get the files listed below from the <API_M_2.6.0_MANAGER_HOME>/repository/deployment/server/synapse-configs/default/sequences directory and replace the corresponding files in the <API_M_2.6.0_MANAGER_HOME>/repository/tenants/<tenant-id>/synapse-configs/default/sequences directory.

    _auth_failure_handler_.xml
    _cors_request_handler_.xml
    fault.xml
    main.xml
    _production_key_error_.xml
    _resource_mismatch_handler_.xml
    _sandbox_key_error_.xml
    _throttle_out_handler_.xml

    In a clustered/distributed API Manager setup, do this step for the Gateway node.

  7. If you have documentation defined for your APIs, make sure you add a value to the Documentation Summary field. 
    Documentation summary is mandatory in APIM 2.0.0 onwards. Therefore, you may face issues when trying to migrate with an empty documentation summary field from an older version. 

  8. If you manually added any custom OSGI bundles to the <API-M_1.10.0_HOME>/repository/components/dropins directory, copy those to the <API-M_2.6.0_HOME>/repository/components/dropins directory. 

  9. If you manually added any JAR files to the <API-M_1.10.0_HOME>/repository/components/lib directory, copy those and paste them in the <API-M_2.6.0_HOME>/repository/components/lib directory. 

Step 2 - Upgrade WSO2 API-M 1.10.0 to 2.6.0

  1. Stop all WSO2 API Manager server instances that are running.

  2. Make sure you backed up all the databases and Synapse configs as instructed in step 1 of the previous section.

  3. Before you run the migration client, open the <API-M_2.6.0_HOME>/repository/conf/datasources/master-datasources.xml file, and set the <username>, and <password> elements of the AM_DB JNDI to that of a user who has permissions to alter tables in the database.

    Tip: After you are done running the migration client, you can switch these credentials back to a user with lesser privileges.

    Example
    <datasource>
        ...
        <definition type="RDBMS">
            <configuration>
                ...
                <username>xxxxxx</username>
                <password>xxxxxx</password>
                ...
            </configuration>
         </definition>
</datasource>

  4. Upgrade the Identity component in WSO2 API Manager from version 5.1.0 to 5.2.0.

    As WSO2 API-M shares identity components with WSO2 IS, this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).

    1. Download the identity component migration resources and unzip it to a local directory.
      Navigate to the latest release tag and download the wso2is-migration-x.x.x.zip under Assets.
    2. Find the correct DB script in the  wso2is-migration-x.x.x/migration-resources/5.2.0/dbscripts/step1/identity  directory.

    3. Manually execute the DB scripts that correspond to the RDBMS that you are working with.

      Apply the respective DB script found inside the following directories against the respective DB as follows:

      DB script directoryApplicable DBDescription

      wso2is-migration-x.x.x/migration-resources/5.2.0/dbscripts/step1/identity

      		AM_DBRun the script against AM_DB.

      wso2is-migration-x.x.x/migration-resources/5.2.0/dbscripts/step1/um

      		UM_DB REG_DBThis script includes insert operations against the UM_CLAIM table and some index creation scripts against REG_DB, which are required in order for you to upgrade from your previous WSO2 API-M version to WSO2 API-M 2.0.0. Please run the index creation queries against the REG_DB and UM_CLAIM table insert queries against the UM_DB

      For example, if you are working with a MySQL DB, run the mysql.sql script.

  5. Download and extract the WSO2 API Manager migration client and do the following to upgrade your version of WSO2 API Manager to WSO2 API-M 2.0.0:

    This migration client upgrades the WSO2 API Manager components from WSO2 API-M 1.10.0 to WSO2 API-M 2.0.0 first. Thereafter, from step 6 onwards, you need to carryout the rest of the changes that are required to upgrade from version WSO2 API-M 2.0.0 to WSO2 API-M 2.6.0.

    1. Copy the org.wso2.carbon.apimgt.migrate.client-2.0.X.jar file to the <API-M_2.6.0_HOME>/repository/components/dropins directory.
      If you use a clustered/distributed API Manager setup, copy the JAR file to the Publisher and Gateway nodes.
    2. Copy the migration-script folder into <API-M_2.6.0_HOME>. 
      If you use a clustered/distributed API Manager setup, copy the migration-script folder to a Publisher node.

      1. Start API Manager 2.6.0 with the following command-line options to migrate the database, registry, and the file system, separately, in the given order.

        DescriptionCommand
        To migrate the database only.
        This migrates the AM_DB database. Please ensure that the <API_M_PUBLISHER>/repository/conf/datasources/master-datasources.xml file has an entry for AM_DB.        		-DmigrateDB=true -Dcomponent=apim -DmigrateFromVersion=1.10.0

        To migrate the registry only. 
        This migrates the registry-related resources such as .rxt and Swagger definitions.

        You may notice the "Fault sequence migration from APIM 2.0.0 to 2.1.0 has started" log message in this step which is used for fault sequence migration. This migration is also done in this step.

        		-DmigrateReg=true -Dcomponent=apim -DmigrateFromVersion=1.10.0
        To migrate the file system only.
        This migrates the Synapse config files such as APIs that reside in the file system. Therefore, you must run this command on the Gateway node/s of a distributed WSO2 API Manager setup.        		-DmigrateFS=true -Dcomponent=apim -DmigrateFromVersion=1.10.0

        To migrate to the new throttling engine and generate throttle policies.
        This migrates Synapse config files, the API-M database with new throttle policies and generates throttle policies to the <API-M_2.6.0_HOME>/executionplans directory. Therefore, you must run this command against a node that has Synapse config files and the AM_DB. After the migration, copy the <API-M_2.6.0_HOME>/executionplans directory to the <API-M_2.6.0_HOME>/repository/deployment/server/executionplans directory of the Traffic Manager node.

        		-Dcomponent=apim -DmigrateFromVersion=1.10.0 -Doptions=migrateThrottling

        If you are using a clustered/distributed API Manager setup -

        • Run with the following options -DmigrateDB=true -DmigrateReg=true -Dcomponent=apim -DmigrateFromVersion=1.10.0 in the API Publisher node.

        • Run the -DmigrateFS=true -Dcomponent=apim -DmigrateFromVersion=1.10.0 options in the API Gateway node.

        Troubleshooting

        If you have enabled token encryption in your database, those consumer keys need to be decrypted as part of the database migration. If you encounter the following error, it means that the migration client has failed to decrypt some of the keys in the old database.

        ERROR {org.wso2.carbon.apimgt.migration.client.MigrateFrom19to110} -  Cannot decrypt consumer key : DRHbt68uSU4+7xtCEIzuf42CMaqXbNjYl3OYVJ0VL/H6EsFo8GBRaZGUhLHlTWIHzYrvoeOpb1YbauvRRIN/b6VqEd9m8HuYOIuLkkDd AM_APPLICATION_KEY_MAPPING table {org.wso2.carbon.apimgt.migration.client.MigrateFrom19to110}


        If this error occurs, by default, the migration client will terminate without updating databases in order to maintain database integrity. However, you can change this behavior by adding the following argument and running the WSO2 API-M migration client again from the beginning. Please note that the database is then updated with the keys where decryption was successful and failed keys are permanently deleted. 

        -DremoveDecryptionFailedKeysFromDB=true

        Expected Errors

        The following are some errors that you may come across. Do not get alarmed as these errors are to be expected, because you are yet to complete the migration process.

        • You may notice the following exception being thrown in the console when WSO2 API Manager 2.6.0 is started at this point,

          org.wso2.carbon.idp.mgt.IdentityProviderManagementException: Error occurred while retrieving Identity Provider information for tenant : carbon.super and Identity Provider name : LOCAL

          This is due to the fact that the IDP_METADATA table does not exist in the WSO2 API Manager database. The instructions given from step 8 onwards address the creation of the IDP_METADATA table after which this exception will no longer be thrown.

        • You may notice the following error during the first stage of running the WSO2 API Manager Migration Client.

          com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'WSO2AM_DB.AM_POLICY_APPLICATION' doesn't exist

          This error will get resolved after the first run of the migration client.

        • You may notice Gateway artifact deployment related errors.
          The following is one such exception that is thrown in the console when WSO2 API Manager 2.6.0 is started at this point.

          Error loading class : org.wso2.carbon.apimgt.usage.publisher.APIMgtResponseHandler - Class not found

          This error gets eliminated after executing the Gateway artifact migration script in step 6 .

        • You may also notice the following exceptions when WSO2 API Manager 2.6.0 is started at this point.

          com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'WSO2AM_DB.IDN_CLAIM_DIALECT' doesn't exist
          com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'WSO2AM_DB.IDN_OIDC_SCOPE' doesn't exist

          These errors will be resolved after following the instructions given under step 8 below.

  6. Run the respective migration script, based on your environment. 

    Run the apim200_to_apim260_gateway_artifact_migrator.sh script, as shown below, to migrate from WSO2 API Manager 2.0.0 to 2.6.0. 

    ./apim200_to_apim260_gateway_artifact_migrator.sh <API-definitions-path>

    <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.0.0 deployment, reside.

    The API definition paths <API-definition-path> are as follows:

    • Super Tenant - <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default

    • Tenant - <API-M_2.6.0_HOME>/repository/tenants

    Where, <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0. 

    Run the PowerShell script apim200_to_apim260_gateway_artifact_migrator.ps1 as follows:

    1. Open a Windows command prompt and type the following command.

      powershell

      A message about PowerShell appears, and the shell changes to PowerShell (PS).

    2. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.

      .\apim200_to_apim260_gateway_artifact_migrator.ps1 <API-definitions-path>

      <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.0.0 deployment, reside.

      • Super Tenant - <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default

      Where <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0.

    Run the PowerShell script apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1 as follows:

    1. Open a Windows command prompt and type the following command.

      powershell

      A message about PowerShell (PS) appears, and the shell changes to PS.

    2. Run the PowerShell script by passing the location of the Gateway artifacts that you need to migrate.

      .\apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1 <API-definitions-path>

      <API-definition-path> - This is the location where the WSO2 API-M 2.6.0 API definitions, which were copied from the API-M 2.0.0 deployment, reside.

      • Tenants - <API-M_2.6.0_HOME>/repository/tenants

      Where <API-M_2.6.0_HOME> can be, for example, /Users/user12/Documents/wso2am-2.6.0.

    It may take a considerable amount of time, which is proportionate to the number of artifacts, to complete the migration process.

    Troubleshooting

    Why do I get the following error - apim200_to_apim260_gateway_artifact_migrator.ps1 / apim200_to_apim260_gateway_artifact_migrator_for_tenants.ps1 cannot be loaded because the execution of scripts is disabled on this system?

    When running the apim200_to_apim260_gateway_artifact_migrator.ps1 script, if the execution process is aborted with the above error, it means that the execution of unknown scripts is disabled in the system. To overcome this issue and allow the execution of such scripts, run the following command in the terminal/command-line as the Administrator.

    Set-ExecutionPolicy RemoteSigned

  7. Upgrade the WSO2 API Manager database from version 2.0.0 to version 2.6.0.

    1. Download the apimgt-db-migration-scripts-2.0to2.6.zip and extract it.

    2. Execute the relevant database script, from the scripts that are provided in the extracted directory, on the WSO2AM_DB database.

  8. Upgrade the Identity component in WSO2 API Manager from version 5.2.0 to 5.7.0.

    As WSO2 API-M shares identity components with WSO2 IS, this step is necessary to upgrade those components (even if you are not using WSO2 IS as a Key Manager).

    1. Download the identity component migration resources and unzip it to a local directory.
      Navigate to the latest release tag and download the wso2is-migration-x.x.x.zip under Assets.
    2. Copy the migration-resources folder in the extracted folder to <API-M_2.6.0_HOME>.

    3. Open the migration-config.yaml file in the migration-resources directory and edit the currentVersion element to 5.2.0, as shown below.

      migrationEnable: "true"

currentVersion: "5.2.0"
migrateVersion: "5.7.0"

      Make sure you have enabled migration by setting the migrationEnable element to true as defined above.

    4. Remove the following entries from the migration-config.yaml file.

         -
    name: "EventPublisherMigrator"
    order: 11

      and

         -
    name: "ChallengeQuestionDataMigrator"
    order: 6
    parameters:
      schema: "identity"

    5. Copy the JAR (org.wso2.carbon.is.migration-x.x.x.jar) from the extracted folder to the <API-M_2.6.0_HOME>/repository/components/dropins directory.

    6. Copy the keystores (i.e., client-truststore.jks, wso2cabon.jks and any other custom JKS) used in the previous version and replace the existing keystores in the <API-M_2.6.0_HOME>/repository/resources/security directory

    7. Start API Manager 2.6.0 via the terminal to carry out the complete Identity component migration.

      sh wso2server.sh -Dmigrate -Dcomponent=identity
      wso2server.bat -Dmigrate -Dcomponent=identity

      If you run WSO2 API-M as a Windows Service when doing the identity component migration, then you need to add the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

      -Dmigrate -Dcomponent=identity

      Please note that depending on the number of records in the identity tables, this identity component migration will take a considerable amount of time to finish. Do not stop the server during the migration process and please wait until the migration process finish completely and server get started.

      Troubleshooting

      When running the above step if you encounter the following error message, please follow the steps in this section. Please note that this error could occur only if the identity tables contain a huge volume of data.

      Sample exception stack trace
      ERROR {org.wso2.carbon.registry.core.dataaccess.TransactionManager} -  Failed to start new registry transaction. {org.wso2.carbon.registry.core.dataaccess.TransactionManager} 
org.apache.tomcat.jdbc.pool.PoolExhaustedException: [pool-30-thread-11] Timeout: Pool empty. Unable to fetch a connection in 60 seconds, none available[size:50; busy:50; idle:0; 
lastwait:60000

      1. Change the value in <indexingFrequencyInSeconds> in <API-M_HOME>/repository/conf/registry.xml to a higher value (e.g., 10)

      2. Re-run the command above.

      Make sure to revert the change done in Step 1 , after the migration is complete

    8. After you have successfully completed the migration, stop the server and remove the following files and folders.

      • Remove the JAR (org.wso2.carbon.is.migration-x.x.x.jar) file, which is in the <API-M_2.6.0_HOME>/repository/components/dropins directory.

      • Remove the migration-resources directory, which is in the <API-M_2.6.0_HOME> directory.

      • If you ran WSO2 API-M as a Windows Service when doing the identity component migration , then you need to remove the following parameters in the command line arguments section (CMD_LINE_ARGS) of the wso2server.bat file.

        -Dmigrate -Dcomponent=identity

  9. You have to run the following migration client for migrating Access Control support for API Publisher, because Publisher Access Control is enabled by default in API Manager 2.6.0.

    1. Download  WSO2 API Manager Migration Client, extract and copy org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar (You can use the same JAR that downloaded in step 5 )  to the <API-M_HOME>/repository/components/dropins  directory.

    2. Start the WSO2 API-M server as follows:

      sh wso2server.sh -DmigrateAccessControl=true

  10. Preserve the case sensitive behavior for the migrated resources by adding the following property to the <API-M_HOME>/repository/conf/user-mgt.xml file under <AuthorizationManager> as follows:

    <AuthorizationManager class="org.wso2.carbon.user.core.authorization.JDBCAuthorizationManager">
	...
	<Property name="PreserveCaseForResources">false</Property>
</AuthorizationManager>

  11. Re-index the artifacts in the registry.

    1. Shut down WSO2 API Manager 2.6.0 (if you have already started it).

    2. Run the reg-index.sql script against the REG_DB database.

      Please note that depending on the number of records in the REG_LOG table, this script will take a considerable amount of time to finish. Do not stop the execution of script until it is completed.

    3. Add the tenantloader-1.0.jar to <API-M_2.6.0_HOME>/repository/components/dropins directory

    4. Rename the <lastAccessTimeLocation> element in the <API-M_2.6.0_HOME>/repository/conf/registry.xml file.

    5. If you use a clustered/distributed API Manager setup, change the file in the API Publisher node.
      For example, change the /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime registry path to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1  

    6. If the <API-M_2.6.0_HOME>/ solr directory exists, take a backup and thereafter delete it.

    7. Start the WSO2 API-M server.
    8. Stop the WSO2 API-M server and remove the tenantloader-1.0.jar from the <API-M_2.6.0_HOME>/repository/components/dropins directory. Make sure to remove the WSO2 API-M client migration jar (org.wso2.carbon.apimgt.migrate.client-2.6.x-1.jar) from the <API-M_2.6.0_HOME>/repository/components/dropins directory as well.

Step 3 - Optionally, migrate the statistics related data from WSO2 DAS to API Manager Analytics 2.6.0

This step is only required if you have WSO2 Data Analytics Server (WSO2 DAS) configured in your current deployment for analytics.

From WSO2 API Manager 2.0.0 onwards, statistics can be configured only for RDBMS, because the WSO2 API Manager 1.10.0 REST based analytics configurations no longer exists. Follow the instructions below to migrate statistics data from a previous versions of API Manager to WSO2 API-M 2.6.0. 

If you have configured analytics using RDBMS -

  1. Take a backup of the API Manager statistics DB (STAT_DB). 
  2. Execute the relevant DB script found in migration-scripts/110-200-migration/stat/ on the STAT_DB database that you configured in WSO2 DAS for WSO2 API-M 1.10.0.
    After executing the DB script, now, your STAT_DB is similar to the STAT_DB in WSO2 API-M 2.0.0.

  3. Directly migrate to WSO2 API-M 2.6.0 as mention in Step 3 - Optionally, migrate the configurations for WSO2 API-M Analytics, under the Upgrade from 2.5.0 to 2.6.0 tab.

    You may notice that the following exceptions are thrown in the console when migrating at this point. These exceptions occur because the following tables were introduced only after WSO2 API-M 2.0.0. Therefore, you can safely ignore these exceptions.

    com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'TestStatsDB_new.API_REQ_USER_BROW_SUMMARY' doesn't exist.

    com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'TestStatsDB_new.API_EXE_TME_SUMMARY' doesn't exist

    com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'TestStatsDB_new.API_REQ_GEO_LOC_SUMMARY' doesn't exist

If you configured analytics using the REST client in API-M 1.10.0 with DAS 3.0.x -

  1. Configure analytics using WSO2 API Manager 1.10.0 and WSO2 DAS 3.0.x with the RDBMS client based on the instructions in Publishing API Runtime Statistics Using RDBMS, which is in the WSO2 API-M 1.10.0 documentation.
  2. Wait for data to appear on the RDBMS and WSO2 API Manager statistics dashboard.

  3. Take a backup of the WSO2 API Manager statistics DB (STAT_DB).

  4. Execute the relevant DB script found in migration-scripts/110-200-migration/stat/ on the STAT_DB that you configured in WSO2 Data Analytics (WSO2 DAS) for WSO2 API Manager 1.10.0.
    After executing the DB script, now, your STAT_DB is similar to the STAT_DB in WSO2 API-M 2.0.0.
  5. Directly migrate to WSO2 API-M 2.6.0 as mention in Step 3 - Optionally, migrate the configurations for WSO2 API-M Analytics, under the Upgrade from 2.5.0 to 2.6.0 tab.

Step 4 - Restart the WSO2 API-M 2.6.0 server

sh wso2server.sh

wso2server.bat

Follow the instructions below to upgrade your WSO2 API Manager server from APIM 1.8.0/1.9.0/1.9.1 to 2.6.0. 

If you are using WSO2 Identity Server (WSO2 IS) as a Key Manager, follow the instructions in Upgrading from the Previous Release when WSO2 IS is the Key Manager.

Step 1 - Upgrade WSO2 API-M 1.8.0/1.9.0/1.9.1 to 2.0.0

It is not possible to directly upgrade from WSO2 API Manager 1.8.0/1.9.0/1.9.1 to 2.6.0.

Upgrade your current WSO2 API-M version (1.8.0/1.9.0/1.9.1) to WSO2 API-M 2.0.0 as explained in the WSO2 API-M 2.0.0 documentation.

Step 2 - Upgrade WSO2 API-M 2.0.0 to API-M 2.6.0

After you have successfully migrated your current WSO2 API-M version to 2.0.0, upgrade from API-M 2.0.0 to API-M 2.6.0. For more information, see Upgrading from 2.0.0 to 2.6.0.

This concludes the upgrade process.

Tip 1: The migration client that you use in this guide automatically migrates your tenants, workflows, external user stores, etc. to the upgraded environment. Therefore, there is no need to migrate them manually.

Tip 2: From 2.6.0 onwards, WSO2 API Manager is configured by default to trigger token clean up during token generation, token refreshing and token revocation. For more details, see Configuring API Manager for token cleanup. Therefore, when the state of the token ( TOKEN_STATE) is changed during any of the latter mentioned processes for tokens that were ACTIVE before the migration process and/or for tokens that will be generated after the migration process, by default, such tokens will be removed from the IDN_OAUTH2_ACCESS_TOKEN table and stored in an audit table. However, the old tokens which were already inactive, revoked or expired before the migration will not be cleaned by the same token cleanup process. Therefore, alternatively, after the migration, you could follow step 3 in the Using stored procedures for token cleanup section and use the given token clean up script to manually clean up the old inactive, revoked, and expired tokens from the IDN_OAUTH2_ACCESS_TOKEN table.

Tip 3: If you are using an SVN based deployment synchronizer, start with a clean SVN repository and point the new deployment nodes to the new SVN repository. In addition, you need to remove any existing .svn directories in the new deployment's <API-M_2.6.0_HOME>/repository/deployment/server/synapse-configs/default directory and the <API-M_2.6.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default directory before starting the servers. For more details, see Configuring Deployment Synchronization.



  • No labels
||