This documentation is for WSO2 API Manager 2.2.0. View documentation for the latest release.

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

The following information describes how to upgrade your API Manager server from APIM 1.8.0/1.9.0/1.9.1/1.10.0/2.0.0/2.1.0 to 2.2.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.

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

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

Before you begin...

Configuring the registry.xml file

Note that you have to do the configurations listed below in all nodes in a distributed deployment.

  1. Open the <APIM_HOME>/repository/conf/registry.xml file and find the following section.

    <handler class="org.wso2.carbon.apimgt.impl.handlers.CustomAPIIndexHandler"> 
    	<filter class = "org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher"> 
    		<property name="mediaType">application/vnd.wso2-api+xml</property> 
    	</filter>
    </handler>
  2. Replace the code found in the previous step with the following.

    <handler class="org.wso2.carbon.registry.indexing.IndexingHandler">
    	<filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher">
                    <property name="mediaType">application/vnd.wso2-api+xml</property>
            </filter>
    </handler>
  3. Comment or remove the following.

    <indexer class="org.wso2.carbon.apimgt.impl.indexing.indexer.CustomAPIIndexer" mediaTypeRegEx="application/vnd.wso2-api\+xml" profiles ="default,api-store,api-publisher"/>
Configuring the usr-mgt.xml file
  1. Open the <API-M_HOME>/repository/conf/registry.xml file and add the PreserveCaseForResources property under the AuthorizationManager section.

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

    These changes will take effect once you re-index and restart the server. You do not need to it since you will re-index and restart in Step 2 - 4, below.

Step 1 - Migrate the configurations 

Step 1.1 - Migrate the API Manager configurations

Do not copy entire configuration files from the current version of API Manager to the new one, as some configuration files (for example, 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 super tenant.
    You find the synapse configs of the super tenant in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory. 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.2.0 from https://wso2.com/api-management/.
  3. Open the <API-M_2.2.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 already being used.

    • User Store
    • Registry database/s
    • API Manager databases
    • Statistics database (If statistics are configured)
  4. Edit the registry configurations in the <API-M_2.2.0_MANAGER_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.2.0_MANAGER_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, except the files mentioned below, by copying and replacing the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory to the <API-M_2.2.0_MANAGER_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.2.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, please merge them to the corresponding files in 2.2.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.2.0_MANAGER_HOME>/repository/tenants directory.

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

    _auth_failure_handler_.xml
    _build_.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
    _token_fault_.xml

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

Step 1.2 - Migrate the configurations for the API-M Analytics profile

Follow the steps below to migrate the configurations required to run the API-M Analytics profile for WSO2 API-M 2.2.0 when you are upgrading from APIM Analytics 2.0.0.

These steps are required only if the database type configured with the API-M Analytics profile is either H2 or MySQL.

  1. Download WSO2 API Manager Analytics 2.2.0 from here.
  2. If you want to connect your WSO2 API Manager Analytics 2.2.0 installation to the same databases that were used with your API Manager Analytics 2.1.0 installation, edit the configurations in the <API-M_ANALYTICS_2.2.0_HOME>/repository/conf/analytics/rdbms-config.xml file, similar to the configurations in the same file of your WSO2 API Manager Analytics 2.1.0 installation.
  3. Replace the Statistics DB (STAT_DB) configurations in the <API-M_ANALYTICS_2.2.0_HOME>/repository/conf/stats-datasources.xml file with the configurations in the same file of your WSO2 API Manager Analytics 2.1.0 Installation.

Step 2 - Upgrade API Manager to 2.2.0

  1. Stop all running WSO2 API Manager server instances.
  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_apim220_gateway_artifact_migrator.sh  script, as shown below, to migrate from API Manager 2.1.0 to 2.2.0. 

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

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

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

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

    • Tenant - <API-M_2.2.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default

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

    Run the PowerShell script ( apim210_to_apim220_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 PS.

    2. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.
      You can do this in the home directory of the existing API-M 2.0.0 installation.

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

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

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

      • Tenant - <API-M_2.2.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default

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

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

    Troubleshooting

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

    When running the apim210_to_apim220_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. To re-index the artifacts in the registry,

    1. Rename the <lastAccessTimeLocation> element in the <API-M_2.2.0_HOME>/repository/conf/registry.xml file. 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

    2. Shut down API Manager 2.2.0 if you have already started it, backup, and delete the <API-M_2.2.0_HOME>/ solr directory, if it exists.

  5. Upgrade the API Manager database from version 2.1.0 to version 2.2.0.

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

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

  6. Upgrade the Identity component in WSO2 API Manager from version 5.3.0 to 5.5.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 in 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.2.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.5.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. From the extracted folder, copy the JAR (org.wso2.carbon.is.migration-x.x.x.jar) to the <API-M_2.2.0_HOME>/ repository/components/dropins directory.

    6. Copy and replace the keystores used in the previous version to the <API-M_2.2.0_HOME>/repository/resources/security directory.

    7. Start API Manager 2.2.0 with the command line option -Dmigrate -Dcomponent=identity to carry out the complete Identity component migration.

  7. Download the Access Control Migration Client from here. Add the jar file to the <API-M_HOME>/repository/components/dropins directory.
  8. Start the server. The sample command is given below. Note that this command should be executed only in the Publisher node.

    sh wso2server.sh -DmigrateAccessControl=true

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. There is no need to migrate them manually.

Tip 2: 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. Also, any existing .svn directories in the new deployment's <API-M_2.2.0_HOME>/repository/deployment/server/synapse-configs/default directory and the <API-M_2.2.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default directory should be removed before starting the servers. For more details, see Configuring Deployment Synchronization.

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

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

Before you begin...

Configuring the registry.xml file

Note that you have to do the configurations listed below in all nodes in a distributed deployment.

  1. Open the <APIM_HOME>/repository/conf/registry.xml file and find the following section.

    <handler class="org.wso2.carbon.apimgt.impl.handlers.CustomAPIIndexHandler"> 
    	<filter class = "org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher"> 
    		<property name="mediaType">application/vnd.wso2-api+xml</property> 
    	</filter>
    </handler>
  2. Replace the code found in the previous step with the following.

    <handler class="org.wso2.carbon.registry.indexing.IndexingHandler">
    	<filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher">
                    <property name="mediaType">application/vnd.wso2-api+xml</property>
            </filter>
    </handler>
  3. Comment or remove the following.

    <indexer class="org.wso2.carbon.apimgt.impl.indexing.indexer.CustomAPIIndexer" mediaTypeRegEx="application/vnd.wso2-api\+xml" profiles ="default,api-store,api-publisher"/>

Configuring the usr-mgt.xml file
  1. Open the <API-M_HOME>/repository/conf/registry.xml file and add the PreserveCaseForResources property under the AuthorizationManager section.

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

    These changes will take effect once you re-index and restart the server. You do not need to it since you will re-index and restart in Step 2 - 4, below.

Step 1 - Migrate the configurations 

Step 1.1 - Migrate the API Manager configurations

Do not copy entire configuration files from the current version of API Manager to the new one, as some configuration files (for example, 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 super tenant.
    You find the synapse configs of the super tenant in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory. 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.2.0 from https://wso2.com/api-management/.
  3. Open the <API-M_2.2.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 already being used.

    • User Store
    • Registry database/s
    • API Manager databases
    • Statistics database (if statistics are configured)
  4. Edit the registry configurations in the <API-M_2.2.0_MANAGER_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.2.0_MANAGER_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, except the files mentioned below, by copying and replacing the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory in the <API-M_2.2.0_MANAGER_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.2.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, please merge them to the corresponding files in 2.2.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.2.0_MANAGER_HOME>/repository/tenants directory.

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

    _auth_failure_handler_.xml
    _build_.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
    _token_fault_.xml

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

Step 1.2 - Migrate the configurations for the API-M Analytics profile

Follow the steps below to migrate the configurations required to run the API-M Analytics profile for WSO2 API-M 2.2.0 when you are upgrading from APIM Analytics 2.1.0.

These steps are required only if the database type configured with the APIM Analytics profile is either H2 or MySQL.

  1. Download WSO2 API Manager Analytics 2.2.0 from here.
  2. Replace the Analytics database configurations in the <API-M_ANALYTICS_2.2.0_HOME>/repository/conf/datasources/analytics-datasources.xml file with the configurations in the same file of your WSO2 API Manager Analytics 2.1.0 Installation
  3. Replace the Statistics DB (STAT_DB) configurations in the <API-M_ANALYTICS_2.2.0_HOME>/repository/conf/datasources/stats-datasources.xml file with the configurations in the same file of your WSO2 API Manager Analytics 2.1.0 Installation.

Step 2 - Upgrade API Manager to 2.2.0

  1. Stop all running WSO2 API Manager server instances.
  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_apim220_gateway_artifact_migrator.sh script, as shown below, to migrate from API Manager 2.0.0 to 2.2.0. 

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

    <API-definition-path> - This is the location where the WSO2 API-M 2.2.0 API definitions, which are 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.2.0_HOME>/repository/deployment/server/synapse-configs/default

    • Tenant - <API-M_2.2.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default

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

    Run the PowerShell script ( apim200_to_apim220_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 PS.

    2. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.
      You can do this in the home directory of the existing API-M 2.0.0 installation.

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

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

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

      • Tenant - <API-M_2.2.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default

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

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

    Troubleshooting

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

    When running the apim200_to_apim220_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. Do the following to re-index the artifacts in the registry:

    1. Rename the <lastAccessTimeLocation> element in the <API-M_2.2.0_HOME>/repository/conf/registry.xml file. 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

    2. Shut down API Manager 2.2.0 if you have already started it, backup, and delete the <API-M_2.2.0_HOME>/ solr directory, if it exists.

  5. Upgrade the API Manager database from version 2.0.0 to version 2.2.0.

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

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

  6. Upgrade the Identity component in WSO2 API Manager from version 5.2.0 to 5.5.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 in 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.2.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.5.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. From the extracted folder, copy the JAR (org.wso2.carbon.is.migration-x.x.x.jar) to the <API-M_2.2.0_HOME>/repository/components/dropins directory.

    6. Copy and replace the keystores used in the previous version to the <API-M_2.2.0_HOME>/repository/resources/security directory.

    7. Start API Manager 2.2.0 with the command line option -Dmigrate -Dcomponent=identity to carry out the complete Identity component migration.

  7. Download the Access Control Migration Client from here. Add the jar file to the <API-M_HOME>/repository/components/dropins directory.
  8. Start the server. The sample command is given below. Note that this command should be executed only in the Publisher node.

    sh wso2server.sh -DmigrateAccessControl=true

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. There is no need to migrate them manually.

Tip 2: 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. Also, any existing .svn directories in the new deployment's <API-M_2.2.0_HOME>/repository/deployment/server/synapse-configs/default directory and the <API-M_2.2.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default directory should be removed before starting the servers. For more details, see Configuring Deployment Synchronization.

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

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

Before you begin...

Configuring the registry.xml file

Note that you have to do the configurations listed below in all nodes in a distributed deployment.

  1. Open the <APIM_HOME>/repository/conf/registry.xml file and find the following section.

    <handler class="org.wso2.carbon.apimgt.impl.handlers.CustomAPIIndexHandler"> 
    	<filter class = "org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher"> 
    		<property name="mediaType">application/vnd.wso2-api+xml</property> 
    	</filter>
    </handler>
  2. Replace the code found in the previous step with the following.

    <handler class="org.wso2.carbon.registry.indexing.IndexingHandler">
    	<filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher">
                    <property name="mediaType">application/vnd.wso2-api+xml</property>
            </filter>
    </handler>
  3. Comment or remove the following.

    <indexer class="org.wso2.carbon.apimgt.impl.indexing.indexer.CustomAPIIndexer" mediaTypeRegEx="application/vnd.wso2-api\+xml" profiles ="default,api-store,api-publisher"/>

Configuring the usr-mgt.xml file
  1. Open the <API-M_HOME>/repository/conf/registry.xml file and add the PreserveCaseForResources property under the AuthorizationManager section.

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

    These changes will take effect once you re-index and restart the server. You do not need to it since you will re-index and restart in Step 2 - 4, below.

Step 1.1 - Migrate the API Manager configurations

Do not copy entire configuration files from the current version of API Manager to the new one, as some configuration files (for example, 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 super tenant.
    You find the synapse configs of the super tenant in the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory. 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.2.0 from http://wso2.com/api-management/.
  3. Open the <API-M_2.2.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 already being used.

    • User Store
    • Registry database/s
    • API Manager databases
    • Statistics database (if statistics are configured)
  4. Edit the registry configurations in the <API-M_2.2.0_MANAGER_HOME>/repository/conf/registry.xml file and the user database in the <API-M_2.2.0_MANAGER_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, except the files mentioned below, by copying and replacing the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default directory to the <API-M_2.2.0_MANAGER_HOME>/repository/deployment/server/synapse-configs/default. 

    NOTE: Do not replace the files listed below from the <CURRENT_API-M_HOME>/repository/deployment/server/synapse-configs/default folder to APIM 2.2.0. These are application-specific APIs and sequences. If you made any custom changes to the files below, please merge them to the corresponding files in 2.2.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.2.0_MANAGER_HOME>/repository/tenants directory.

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

    _auth_failure_handler_.xml
    _build_.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
    _token_fault_.xml

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

Step 1.2 - Migrate the statistics related data from WSO2 DAS to API Manager Analytics

From WSO2 API Manager 2.0.0 onwards, statistics can be configured only for RDBMS since the API Manager 1.10.0 REST based analytic configuration no longer exists. This section walks you through how to migrate statistics data from previous versions of API Manager to 2.2.0. 

If you have configured analytics using RDBMS,

  1. Take a backup of the API Manager statistics DB. 
  2. Add the API Manager statistics DB as a datasource in WSO2 API Manager Analytics.

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

  1. Configure analytics using API Manager 1.10.0 and DAS 3.0.x with the RDBMS client, according to the instructions in Publishing API Runtime Statistics Using RDBMS.
  2. Wait for data to appear on the RDBMS and API Manager statistics dashboard.
  3. Replace the Statistics DB (STAT_DB) configurations configured in WSO2 DAS for API Manager 1.10.0, in the
    <API-M_ANALYTICS_2.2.0_HOME>/repository/conf/stats-datasources.xml file.

Finally, execute the relevant db script found in migration-scripts/110-200-migration/stat/ on the STAT_DB.

Once done, configure analytics in API Manager 2.2.0 according to the instructions in Configuring APIM Analytics.

Step 2 - Upgrade API Manager to 2.2.0

  1. Stop all running WSO2 API Manager server instances.
  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.2.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.

    For 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 in a local directory.
      Navigate to the latest release tag and download the wso2is-migration-x.x.x.zip under Assets.
    2. Copy the unzipped folder it to the <API-M_HOME>/dbscripts/identity directory.
      Copying the DB scripts is optional, as it is done for reference purposes to indicate the version to which you have upgraded your APIM IS component.
    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_DB
      wso2is-migration-x.x.x/migration-resources/5.2.0/dbscripts/step1/um UM_DBThis script includes insert operations and some index creation scripts against the UM_CLAIM table, which are required in order for you to upgrade from your previous API-M version to API-M 2.0.0.

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

  5. Upgrade the Identity component in WSO2 API Manager from version 5.2.0 to 5.3.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).

    It is important to complete the WSO2 API Manager Identity component related migration from version 5.2.0 to 5.3.0 first, before carrying out the WSO2 API-M migration from WSO2 1.10.0 to WSO2 API-M 2.0.0 to avoid the following error.
    com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'WSO2AM_DB.IDN_CLAIM_DIALECT' doesn't exist

    1. Download the 5.2.0 to 5.3.0 migration DB scripts from here.
    2. Unzip and find the correct DB script in the <MIGRATION_SCRIPT_HOME>/wso2is-5.3.0-migration/dbscripts/identity/migration-5.2.0_to_5.3.0 directory.
    3. Manually execute the corresponding DB script against the WSO2AM_DB database.
    4. Copy the /wso2is-5.3.0-migration/dropins/org.wso2.carbon.is.migrate.client-5.3.0.jar file into the <APIM_2.2.0_HOME>/repository/components/dropins directory.

    5. Start API Manager 2.2.0 with the command line option -Dmigrate -Dcomponent=identity to carry out the complete Identity and User Store DB migration.
  6. Download and extract the WSO2 API Manager Migration Client and do the following to upgrade your version of WSO2 API Manager to 2.0.0:

    Note that this is an intermediary step to upgrade the version from 1.10.0 to 2.0.0.


    1. Copy the org.wso2.carbon.apimgt.migrate.client-2.0.X.jar file to the <API-M_2.2.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.2.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.2.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.-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 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_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_HOME>/executionplans directory to the 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 and 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 see the error below, it means that the migration client has failed to decrypt some of the keys in the old database.
        TID: [-1234] [] [2016-04-11 08:27:16,249] 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 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, since you are yet to complete the migration process.

        • You may notice the following exception being thrown in the console when API Manager 2.2.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 API Manager database. The instructions given from step 9 onwards address the creation of the IDP_METADATA table after which this exception will no longer be thrown.

        • 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.2.0 is started at this point.

          Error loading class : org.wso2.carbon.apimgt.usage.publisher.APIMgtFaultHandler - Class not found {org.apache.synapse.config.xml.ClassMediatorFactory}

          These errors get eliminated after executing the Gateway artifact migration script in step 7.

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

    Run the apim200_to_apim220_gateway_artifact_migrator.sh script, as shown below, to migrate from API Manager 2.0.0 to 2.2.0. 

    You need to run this script for the super tenant path and for each of the tenant paths.

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

    <API-definition-path> - This is the location where the WSO2 API-M 2.2.0 API definitions reside.

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

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

    • Tenant - <API-M_2.2.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default

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

    Run the PowerShell script ( apim200_to_apim220_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 PS.

    2. Run the PowerShell script by passing the location of the gateway artifacts that you need to migrate.
      You can do this in the home directory of the existing API-M 2.0.0 installation.

      You need to run this script for the super tenant path and for each of the tenant paths.

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

      <API-definition-path> - This is the location where the WSO2 API-M 2.2.0 API definitions reside.

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

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

      • Tenant - <API-M_2.2.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default

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

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

    Troubleshooting

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

    When running the apim200_to_apim220_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
  8. Do the following to re-index the artifacts in the registry:

    1. Rename the <lastAccessTimeLocation> element in the <API-M_2.2.0_HOME>/repository /conf/registry.xml file. 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.

    2. Shut down API Manager 2.2.0, backup, and delete the <API-M_2.2.0_HOME>/solr directory.

  9. Upgrade the API Manager database from version 2.1.0 to version 2.2.0.

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

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

  10. Upgrade the Identity component in WSO2 API Manager from version 5.3.0 to 5.5.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 in 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.2.0_HOME>.
    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.5.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. From the extracted folder, copy the JAR (org.wso2.carbon.is.migration-x.x.x.jar) to the <API-M_2.2.0_HOME>/repository/components/dropins directory.

    6. Copy and replace the keystores used in the previous version to the <API-M_2.2.0_HOME>/repository/resources/security directory.

    7. Start API Manager 2.2.0 with the command line option -Dmigrate -Dcomponent=identity to carry out the complete Identity component migration.

  11. Download the Access Control Migration Client from here. Add the jar file to the <API-M_HOME>/repository/components/dropins directory.
  12. Start the server. The sample command is given below. Note that this command should be executed only in the Publisher node.

    sh wso2server.sh -DmigrateAccessControl=true

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. There is no need to migrate them manually.

Tip 2: 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. Also, any existing .svn directories in the new deployment's <API-M_2.2.0_HOME>/repository/deployment/server/synapse-configs/default directory and the <API-M_2.2.0_HOME>/repository/tenants/<tenant-id>/synapse-configs/default directory should be removed before starting the servers. For more details, see Configuring Deployment Synchronization.

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

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

Before you begin...

Configuring the registry.xml file

Note that you have to do the configurations listed below in all nodes in a distributed deployment.

  1. Open the <APIM_HOME>/repository/conf/registry.xml file and find the following section.

    <handler class="org.wso2.carbon.apimgt.impl.handlers.CustomAPIIndexHandler"> 
    	<filter class = "org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher"> 
    		<property name="mediaType">application/vnd.wso2-api+xml</property> 
    	</filter>
    </handler>
  2. Replace the code found in the previous step with the following.

    <handler class="org.wso2.carbon.registry.indexing.IndexingHandler">
    	<filter class="org.wso2.carbon.registry.core.jdbc.handlers.filters.MediaTypeMatcher">
                    <property name="mediaType">application/vnd.wso2-api+xml</property>
            </filter>
    </handler>
  3. Comment or remove the following.

    <indexer class="org.wso2.carbon.apimgt.impl.indexing.indexer.CustomAPIIndexer" mediaTypeRegEx="application/vnd.wso2-api\+xml" profiles ="default,api-store,api-publisher"/>

Configuring the usr-mgt.xml file
  1. Open the <API-M_HOME>/repository/conf/registry.xml file and add the PreserveCaseForResources property under the AuthorizationManager section.

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

    These changes will take effect once you re-index and restart the server. You do not need to it since you will re-index and restart in Step 2 - 4, below.

Step 1 - Upgrade WSO2 API Manager 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.2.0.

Upgrade your current WSO2 API-M version (1.8.0/1.9.0/1.9.1) to WSO2 API-M 2.0.0.

Step 2 - Upgrade WSO2 API Manager to 2.2.0

After you have successfully migrated your current WSO2 API-M version to 2.2.0, upgrade from API-M 2.0.0 to API-M 2.2.0. For more information, click below:

Upgrading from API-M 2.0.0 to API-M 2.2.0


  1. Download the Access Control Migration Client from here. Add the jar file to the <API-M_HOME>/repository/components/dropins directory.
  2. Start the server. The sample command is given below. Note that this command should be executed only in the Publisher node.

    sh wso2server.sh -DmigrateAccessControl=true

This concludes the upgrade process.

  • No labels