This documentation is for WSO2 API Manager 1.9.0 View documentation for the latest release.
Page Comparison - Upgrading from the Previous Release (v.43 vs v.44) - API Manager 1.9.0 - WSO2 Documentation

Versions Compared

Key

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

...

  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 http://wso2.com/products/api-manager/.
  3. Open the <APIM_1.9.0_HOME>/repository/conf/datasources/master-datasources.xml 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 <APIM_1.9.0_HOME>/repository/config/registry.xml and the user database in the <APIM_1.9.0_HOME>/repository/conf/user-mgt.xml file.

  5. Move all your synapse configurations by copying and replacing <APIM_1.8.0_HOME>/repository/deployment/server/synapse-config/default directory to <APIM_1.9.0_HOME>/repository/deployment/server/synapse-config/default directory.

    Warning

    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. They are application-specific APIs.

Upgrading the API Manager from 1.8.0 to 1.9.0

...

  1. Stop all running 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. Download WSO2 API Migration Client v1.9.0.

  4. Extract the file you downloaded in the previous step and do the following:
    1. Copy the org.wso2.carbon.apimgt.migrate.client-1.9.0.jar 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 folder into <APIM_1.9.0_HOME>/. If you use a clustered/distributed API Manager setup, copy the migration-script folder to the node that hosts your database.
  5. 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 according to your database type. The scripts for each database type are given in the table below:

    Database typeScript
    MySQLNo changes are required as the default drop-fk.sql file already contains the scripts for MySQL.
    H2SELECT DISTINCT constraint_name FROM information_schema.constraints WHERE table_name = 'AM_APP_KEY_DOMAIN_MAPPING';
    ALTER TABLE AM_APP_KEY_DOMAIN_MAPPING DROP CONSTRAINT <temp_key_name>;
    OracleSELECT DISTINCT constraint_name FROM user_cons_columns WHERE table_name = 'AM_APP_KEY_DOMAIN_MAPPING';
    ALTER TABLE AM_APP_KEY_DOMAIN_MAPPING DROP CONSTRAINT <temp_key_name>;
    MS SQL ServerSELECT CONSTRAINT_NAME FROM INFORMATION_SCHEMA.CONSTRAINT_COLUMN_USAGE WHERE TABLE_NAME = 'AM_APP_KEY_DOMAIN_MAPPING' AND COLUMN_NAME='CONSUMER_KEY'; 
    ALTER TABLE AM_APP_KEY_DOMAIN_MAPPING DROP CONSTRAINT <temp_key_name>;
    Postgresql

    SELECT CONSTRAINT_NAME FROM information_schema.constraint_table_usage WHERE TABLE_NAME = 'AM_APP_KEY_DOMAIN_MAPPING';
    ALTER TABLE AM_APP_KEY_DOMAIN_MAPPING DROP CONSTRAINT <temp_key_name>;

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

    Warning

    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-Dmigrate=1.9
    To migrate the database only-DmigrateDB=1.9
    To migrate the registry only-DmigrateReg=1.9
    To migrate the file system only-DmigrateFS=1.9
    Tip

    Tip: You can migrate all the resources together with the -Dmigrate=1.9 command or perform single resource migrations using the other commands separately. If you execute -Dmigrate=1.9, you do not need to execute the rest.

    Tip

    Tip: If you are using a clustered/distributed API Manager setup, run -DmigrateDB=1.9 in the node where you have the database, -DmigrateReg=1.9 in the API Publisher and -DmigrateFS=1.9 in the API Gateway.

  7. Do the following to re-index the artifacts in the registry:

    1. Rename the <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 to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1

    2. Shut down the API Manager 1.9.0, back up and delete the <APIM_1.9.0_HOME>/repository/conf/solr directory and restart the server.

This concludes the upgrade process. Depending on your setup, do the following migrations as well:

Tip

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.

Migrating tenants

If you have multiple tenants added to your API Manager instance, follow the steps below to migrate tenant configurations. 

  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

Migrating 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.

Migrating 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.

Migrating workflows

If you have Workflows 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/applicationdata/workflow-extensions.xml resource in the registry browser UI, configure your workflows and save.