Upgrading from the Previous Release

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

Before you begin,

1. Stop all running API Manager server instances.
2. Download API Manager 1.7.0 from http://wso2.com/products/api-manager. 
   
3. Replace all the files in <APIM_1.7.0_HOME>/dbscripts/migration-1.6.0_to_1.7.0 folder with the files in this SVN location. This is because some of the scripts in the 1.7.0 distribution give migration issues. We have fixed this in APIM 1.8.0.

Upgrading the product databases

1. Back up the databases of your API Manager 1.6.0 server instance.
   

2. Go to <APIM_1.7.0_HOME>/dbscripts/migration-1.6.0_to_1.7.0 and run the database upgrade scripts on your old database. You must select the script corresponding to your database type. For example, if your database is MySQL, execute <APIM_1.7.0_HOME>/dbscripts/migration-1.6.0_to_1.7.0/mysql.sql on it. The script adds all the schema changes done to API Manager tables in the 1.7.0 release.

   Tip: Do not use the migration scripts that are bundled in your product distribution as they cause migration issues. These issues are fixed in the APIM 1.8.0 release.

3. Point the WSO2 Carbon Database (User Store and Registry) and API Manager Databases of your APIM 1.6.0 instance to APIM 1.7.0. (Configure the <APIM_1.7.0_HOME>/repository/datasource/master-datasources.xml file to point to the same databases configured in APIM 1.6.0)

Migrating the configurations

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

1. Open <APIM_1.7.0_HOME>/repository/conf/datasources/master-datasources.xml file and copy the datasource configurations for the following databases from the same file in the APIM 1.6.0 instance over to the 1.7.0 instance.

   • User store/s
   • Registry database
   • APIM databases

2. Move all your synapse configurations by copying and replacing the <APIM_1.6.0_HOME>/repository/deployment/server/synapse-config/default directory to the <APIM_1.7.0_HOME>/repository/deployment/server/synapse-config/default directory.

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

3. Copy the <APIM_1.7.0_HOME>/dbscripts/migration-1.6.0_to_1.7.0/api-migration directory to <APIM_1.7.0_HOME>. Once done, you have the <APIM_1.7.0_HOME>/api_migration directory path.

4. Add the following property to the <APIM_1.7.0_HOME>/api-migration/build.xml file.

   apim.home= Path to your APIM 1.7.0 distribution location (If you have a distributed setup, give the path to the Gateway node)

5. Go inside the api-migration directory and execute ant run. You should get a BUILD SUCCESSFUL message.

Upgrading APIM 1.6.0 to 1.7.0

1. Start the API Manager 1.7.0 and log in to its management console.

2. Select Extensions -> Artifact Types and click the View/Edit link associated with the API artifact type.
   
3. Replace the RXT file that opens in the management console with the content of the <APIM_1.7.0_HOME>/dbscripts/migration-1.6.0_to_1.7.0/rxt/api.rxt file.
4. Similarly, using the management console, replace the documentation.rxt file with the content of the <APIM_1.7.0_HOME>/dbscripts/migration-1.6.0_to_1.7.0/rxt/documentation.rxt file.

5. Copy the <APIM_1.7.0_HOME>/dbscripts/migration-1.6.0_to_1.7.0/swagger-resource-migration directory to <APIM_1.7.0_HOME>. Once done, you will have the <APIM_1.7.0_HOME>/swagger-resource-migration directory path.

6. Configure the <APIM_1.7.0_HOME>/swagger-resource-migration/build.xml file with the following properties:
   

   Property	Description
   registry.home	Path to the APIM distribution. In a distributed setup, give the API Publisher node's path.
   username	Username of the APIM server. For a tenant to log in, provide the tenant admin username.
   password	Password for the server. For a tenant to log in, provide the tenant admin password.
   host	IP of the running APIM server. In a distributed setup, give the host of the API Publisher node.
   port	Port of the running APIM server. In a distributed setup, give the port of the APIM Publisher node.
   version	Version of the APIM server.

7. Using the command line, go to the <APIM_1.7.0_HOME>/swagger-resource-migration folder and execute ant run. If the above configuration is successful, you get a BUILD SUCCESSFUL message. It modifies the structure of the Swagger content in the registry.

8. Copy the <APIM_1.7.0_HOME>/dbscripts/migration-1.6.0_to_1.7.0/doc-file-migration directory to <APIM_1.7.0_HOME>. Once done, you will have the <APIM_1.7.0_HOME>/doc-file-migration directory path.

9. Configure <APIM_1.7.0_HOME>/doc-file-migration/build.xml with the following properties.

   Property	Description
   registry.home	Path to the APIM distribution. In a distributed setup, give the API Publisher node's path.
   username	Username of the APIM server
   password	Password of the APIM server
   host	IP of the running APIM server. In a distributed setup, give the host of the API Publisher node.
   port	Port of the running APIM server. In a distributed setup, give the port of the APIM Publisher node.
   version	Version of the APIM server

10. Using the command line, go to the <APIM_1.7.0_HOME>/doc-file-migration folder and execute ant run. If the above configuration is successful, you get a BUILD SUCCESSFUL message.

11. Copy the contents from your previous <APIM_HOME>/repository/tenants directory to the same directory in the API Manager 1.7.0.
12. To upgrade the API and documentation RXT files, 
    

    1. Run the command sudo apt-get install xmlstarlet to install the xmlstarlet library. This is used for xml manipulation.

    2. Copy migrate.sh to the <APIM_1.7.0_HOME>/dbscripts/migration-1.6.0_to_1.7.0/rxt directory.
    3. Set the MySQL host, username, password and governance DB name in the migrate.sh script.

    4. Execute the script.

       Note that the script uses linux commands.

13. Download org.wso2.carbon.apimgt.migration and build a JAR file.
14. Place the JAR file in the <APIM_1.7.0_HOME>/repository/components/dropins folder.

15. Start the server with the -Dmigrate=1.6 command to run the 1.6.0 to 1.7.0 swagger and doc resource migrations.

    Upgrading external stores

16. If you have external stores configured under the <ExternalAPIStores> element in <APIM_1.6.0_HOME>/repository/conf/api-manager.xml file, follow the steps below:

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

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

    Upgrading Google analytics

17. If you have Google Analytics configured under <GoogleAnalyticsTracking> element in <APIM_1.6.0_HOME>/repository/conf/api-manager.xml file, follow the steps below:

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

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

    Upgrading workflows

18. If you have Workflows configured under <WorkFlowExtensions> element in <APIM_1.6.0_HOME>/repository/conf/api-manager.xml file, follow the steps below:

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

    2. Load /_system/governance/apimgt/applicationdata/workflow-extensions.xml resource in the registry browser UI, configure your workflows and save.