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

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

The following information describes how to upgrade your API Manager server from the previous release, which is APIM 1.8.0. To upgrade from a version older than 1.8.0, start from the doc that was released immediately after your current release and upgrade incrementally. 

Table of Contents

Migration scripts location:


Migrating the configurations

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

  1. Back up the databases in your API Manager instances and synapse configs in of all the tenants, including the super tenant.
    You find the synapse configs in <APIM_1.8.0_HOME>/repository/deployment/server/synapse-config/default. For the synapse configurations of tenants, look in <APIM_1.8.0_HOME>/repository/tenants/<tenant_id>/deployment/server/synapse-config/default
    If you use a clustered/distributed API Manager setup, back up the configs in the API Gateway node.

  2. Download the API Manager 1.9.0 from
  3. Open the <APIM_1.9.0_HOME>/repository/conf/datasources/master-datasources.xml file  file and provide the datasource configurations for the following databases. You can copy the configurations from the same file in the API Manager 1.8.0 instance.

    • User Store
    • Registry database
    • API Manager Databases
  4. Edit the registry configurations in the the <APIM_1.9.0_HOME>/repository/config/registry.xml and  and the user database in the <APIMthe <APIM_1.9.0_HOME>/repository/conf/user-mgt.xml file file.

  5. Download the API Manager 1.9.0 from  
  6. Move all your synapse configurations by copying and replacing replacing <APIM_1.8.0_HOME>/repository/deployment/server/synapse-config/default directory to  directory to <APIM_1.9.0_HOME>/repository/deployment/server/synapse-config/default directory.  directory.


    NOTE: Do not replace the _TokenAPI_.xml_RevokeAPI_.xml and _AuthorizeAPI_.xml files in


    the /default/api sub directory unless you use a custom token endpoint. 



    If you changed the default URLs in AuthorizeAPI.xml and TokenAPI.xml files, do not replace them when copying. They are application-specific APIs.

Upgrading APIM 1.8.0 to 1.9.0

  1. They are application-specific APIs.


    When you move the synapse configs, you must copy and replace the files. Make sure you do not delete any existing files in the <APIM_1.9.0_HOME>/repository/deployment/server/synapse-config/default directory, such as the _cors_request_handler.xml.

    This causes errors such as {org.apache.synapse.mediators.base.SequenceMediator} - Sequence named Value {name ='null', keyValue ='_cors_request_handler_'} cannot be found {org.apache.synapse.mediators.base.SequenceMediator}.

Upgrading the API Manager from 1.8.0 to 1.9.0 

  1. Stop all running API Manager server instances.
  2. Back
  3. Make sure you backed up all the databases

  4. of your API Manager 1.8.0 server instance.Download WSO2 API
  5. and synapse configs as instructed in step 1 of the previous section.

  6. Download the WSO2 API Manager Migration Client v1.9.X.

  7. Before you run the migration client, open the <APIM_1.9.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,

    Code Block
            <definition type="RDBMS">
  8. If the API Manager is running, restart it for the changes to take effect.
  9. Extract
  10. and find the jar (
  11. the file you downloaded in the previous step and do the following:
    1. Copy the org.wso2.carbon.apimgt.migrate.client-1.9.
  12. 0
    1. X.jar
  13. ) and copy it into 
    1.  file to <APIM_1.9.0_HOME>/repository/components/dropins. If you use a clustered/distributed API Manager setup, copy the JAR file to all nodes.
    2. Copy the migration-script
  14. folder
    1.  folder into <APIM_1.9.0_HOME>/
  15. Change
    1. . If you use a clustered/distributed API Manager setup, copy the migration-script folder to the node that hosts your database.
  16. If you are not using the MySQL database with the API Manager, change the query inside <APIM_1.9.0_HOME>/migration-scripts/18-19-migration/drop-fk.sql

  17. according
  18.  according to your database type. The scripts for each database type

  19. NoteThe default
  20. are given below:

    Database typeScript
    MySQLNo changes are required as the default drop-fk.sql
  21. file
  22.  file already contains
  23. sql
  24. the scripts for
  25. mysql and if you use mysql no need to do the 6th step
  26. MySQL.
  27. If you are running on
  28. H2
  29. change the query in drop-fk.sql to, 
  30. SELECT DISTINCT constraint_name FROM information_schema.constraints WHERE table_name = 'AM_APP_KEY_DOMAIN_MAPPING';
  31. For Oracle 
  32. OracleSELECT
  34. constraint_name FROM user_cons_columns WHERE table_name = 'AM_APP_KEY_DOMAIN_MAPPING'
  35. ;  
  36. GROUP BY constraint_name HAVING COUNT(constraint_name) = 1;
  37. For
  38. MS SQL
  39. Server 
  41. For Postgresql 
  42. Postgresql

    SELECT CONSTRAINT_NAME FROM information_schema.constraint_table_usage WHERE TABLE_NAME = 'AM_APP_KEY_DOMAIN_MAPPING';

  43. Start the API Manager 1.9.0 with the following command-line options to migrate the database, registry and the file system together or separately.


    If you have a multitenant API Manager setup, copy the contents from your previous <APIM_HOME>/repository/tenants directory to the same directory in the API Manager 1.9.0 (do not replace the _TokenAPI_.xml_RevokeAPI_.xml and _AuthorizeAPI_.xml files in the /default/api sub directory) before you start the server with the following commands.

    To migrate the database, registry and file system together, at the same time. Ideally, you use this to migrate a standalone pack.-Dmigrate=true  -DmigrateToVersion=1.9
  44. for database, registry and file system migrations. If you need to perform single resource migrations you can use the following commands. If you already run -Dmigrate=1.9 , you do not need to run the following commands
    1. For database migrations  run -DmigrateDB=1.9
    2. For registry migrations  run -DmigrateReg=1.9
    3. For file system migrations  run -DmigrateFS=1.9

    Please note that if you run -Dmigrate=1.9, it migrates all the resources including databases, registry and file system.

  45. To migrate the database only. This migrates the AM_DB database. Please ensure that the <APIM_PUBLISHER>/repository/conf/datasources/master-datasources.xml file has an entry for AM_DB.-DmigrateDB=true  -DmigrateToVersion=1.9
    To migrate the registry only. This migrates the registry-related resources such as .rxt and swagger definitions.-DmigrateReg=true  -DmigrateToVersion=1.9
    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 APIM setup. -DmigrateFS=true  -DmigrateToVersion=1.9

    Tip: Make sure you do not delete any new files added in <APIM_1.9.0or If you get an 'artifact not found' exception


    Tip: If you are using a standalone API Manager setup, you can migrate all the resources together with the -Dmigrate=true -DmigrateToVersion=1.9 command, or perform single-resource migrations using the other commands separately. If you execute -Dmigrate=true -DmigrateToVersion=1.9, you do not need to execute the rest of the commands.


    Tip: If you are using a clustered/distributed API Manager setup, runwith the following options -DmigrateDB=true -DmigrateReg=true -DmigrateToVersion=1.9 in the API Publisher node and the -DmigrateFS=true  -DmigrateToVersion=1.9 options in the API Gateway node.

    Optionally, to migrate the API stats DB, use the following options when running the API Publisher node: -DmigrateStats=true -DmigrateToVersion=1.9 when running on the API Publisher node.

  46. Log in to the Management Console of the API Manager and select Extensions -> Artifact Types menu.
    Image Added

  47. Click the Delete link associated with the api artifact type. This removes the reference to the old api artifact type, allowing the latest type to be automatically loaded when the server is restarted.
    Image Added
  48. Do the following to re-index the artifacts in the registry

  49. , perform the two steps given below.a)
  50. :

    1. Rename the

  51. lastAccessTimeLocation
    1. <lastAccessTimeLocation> element in the <APIM_1.9.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

  52. to
    1. to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1. 

  53. b)
    1. Shut down

  54. AM
    1. the API Manager 1.9.0,

  55. backup
    1. back up and delete the <APIM_1.9.0_HOME>/

  56. repository/conf/
    1. solr directory and restart the server.

     For a cluster

  1. If you use a cluster/distributed setup, then you need to copy the migration client to particular node and run -DmigrateDB=1.9 to migrate databases, -DmigrateReg=1.9 to migrate registry, -DmigrateFS=1.9 to migrate file system. You only need to copy migration-script folder into the node which hosts your databases

         Upgrading tenants


  1. Copy the contents from your previous <APIM_HOME>/repository/tenants directory to the same directory in the API Manager 1.9.0. Do not replace the _TokenAPI_.xml, _RevokeAPI_.xml and _AuthorizeAPI_.xml files in the /default/api sub directory.
  2. Start the server

Upgrading external stores


If you have external stores configured in the registry, follow the steps below:

  1. Log in to APIM 1.9.0 management console and click the Resources -> Browse menu.

  2. Load the /_system/governance/apimgt/externalstores/external-api-stores.xml resource in the registry browser UI, configure your external stores and save.

Upgrading Google analytics


If you have Google Analytics configured in the registry, follow the steps below:

  1. Log in to APIM 1.9.0 management console and go to Resources -> Browse menu.

  2. Load the /_system/governance/apimgt/statistics/ga-config.xml resource in the registry browser UI, configure the Google analytics and save.

Upgrading workflows

If you have Workflows configured in the registry, follow the steps below:


Log in to APIM 1.9.0 management console and go to Resources -> Browse menu.


This concludes the upgrade process.


Tip: If you are using a clustered/distributed API Manager setup, note that all config file changes must be done in the API Gateway node.


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


Tip: If you are using WSO2 BAM with the APIM, be sure to change the versions of the existing APIM statistics-related stream definitions of BAM in the <APIM_HOME>/repository/conf/api-manager.xml file. You also have to change the BAM Hive scripts accordingly.