Upgrading from the Previous Release

The following steps illustrate how to upgrade App Manager 1.1.0 to 1.2.0. Product migrations steps are given based on configuration migration and server upgrade.

To upgrade from 1.0.0 to 1.2.0, follow the instructions on upgrading from the previous release for 1.0.0 and then follow the instructions below on upgrading the server to 1.2.0.

Migrating the configurations

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

Shut downApp Manager 1.1.0 if it is running.
Back up all the databases in your current App Manager deployment.
Back up the synapse configurations of all the tenants, including the carbon super tenant. The synapse configurations of the super tenant resides in the<APPM_1.1.0_HOME>/repository/deployment/server/synapse-configs/default directory. The synapse configurations of tenants can be found in the <APPM_1.1.0_HOME>/repository/tenants directory.
In a distributed/clustered setup, these synapse configurations are available in the App Gateway nodes.
Backup all the mobile binaries, images in <APPM_1.1.0>/repository/repository/resources/mobileapps/ folder.
Download App Manager 1.2.0 from http://wso2.com/products/app-manager/.
Open the <APPM_1.2.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 current App Manager instance already being used.
- User Store database
- Registry database
- App Manager database
- Social database
- Storage database

Refer to the configuration shown below in the <APPM_1.1.0_HOME>/repository/conf/registry.xml file and update the registry configuration in the <APPM_1.2.0_HOME>/repository/conf/registry.xml file accordingly.
In a distributed/clustered setup, do the following configuration update only in the Store and Publisher nodes.

<dbConfig name="govregistry">
  <dataSource>jdbc/WSO2REG_DB</dataSource>
</dbConfig>
<remoteInstance url="https://publisher.appm-wso2.com">
   <id>gov</id>
   <cacheId>user@jdbc:mysql://regdb.mysql-wso2.com:3306/regdb</cacheId>
   <dbConfig>govregistry</dbConfig>
   <readOnly>false</readOnly>
   <enableCache>true</enableCache>
   <registryRoot>/</registryRoot>
</remoteInstance>
<mount path="/_system/governance" overwrite="true">
   <instanceId>gov</instanceId>
   <targetPath>/_system/governance</targetPath>
</mount>
<mount path="/_system/config" overwrite="true">
   <instanceId>gov</instanceId>
   <targetPath>/_system/config</targetPath>
</mount>

Refer to the configuration shown below in the <APPM_1.1.0_HOME>/repository/conf/user-mgt.xml file and update the configuration in the <APPM_1.1.0_HOME>/repository/conf/user-mgt.xml file accordingly. Optionally, you can copy the configurations from the same file in the current App Manager instance already being used.
In a distributed/clustered setup, this particular configuration should be applied to all nodes (Store,Publisher and Gateway).
```
<configuration> 
...
    <Property name="dataSource">jdbc/WSO2UM_DB</Property>
</configuration>
...
<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
...
</UserStoreManager>
```

Refer to the following configurations in the <APPM_1.1.0_HOME>/repository/conf/app-manager.xml file and update those configurations in the <APPM_1.2.0_HOME>/repository/conf/app-manager.xml file.

AuthManager Configuration
In a distributed/clustered setup, this configuration should be applied to the Store, Publisher and Gateway nodes.

<AuthManager>
            <ServerURL>https://<IP of the IDP>:9443/services/</ServerURL>
        <Username>admin</Username>
            <Password>admin</Password>
</AuthManager>

APIGateway Configuration
In a distributed/clustered setup, this configuration should be applied to the Store, Publisher and Gateway nodes. In the Store and Gateway nodes, configuring the <GatewayEndpoint> property is mandatory. In the Publisher nodes, configuring the <ServerURL> property is mandatory.

<APIGateway>
    <Environments>
                <Environment type="hybrid">
                        ...
                        <ServerURL>https://<IP of the Gateway>:9443/services/</ServerURL>
                        <Username>admin</Username>
        <Password>admin</Password>
                        <GatewayEndpoint>http://<IP of the Gateway>:8280 ,https://<IP of the Gateway>:8243</GatewayEndpoint>
                </Environment>
        </Environments>
...
</APIGateway>

SSO Configuration
In a distributed/clustered setup, this configuration should be applied to the Store, Publisher and Gateway nodes.

<SSOConfiguration>
     <IdentityProviderUrl>
https:/<IP of the IDP>:9443/samlsso
    </IdentityProviderUrl>
   <Configurators>
            <Configurator>
                ...
                <parameters>
                    <providerURL>https:/<IP of the IDP>:9443</providerURL>
                    <username>admin</username>
                    <password>admin</password>
                </parameters>
        </Configurator>            	
        ...  	
    </Configurators>
</SSOConfiguration>

Mobile Application Binary Storage Configuration

If you are not having mobile applications in your environment, please skip this step
In a distributed setup, this configuration should be applied to Store, Publisher nodes. You need to open <APPM_1.1.0>/repository/deployment/server/jaggeryapps/publisher/extensions/mobileapp/config/mam-config.json and get the binary file storage location and configure the following in <APPM_1.2.0>/repository/conf/app-manager.xml with that particular location.
```
  <BinaryFileStorage>
       <AbsoluteLocation>{file-storage-location}</AbsoluteLocation>
  </BinaryFileStorage>
```

Analytics
If Webapp statistics are enabled in the <APIUsageTracking> section in the current setup, map and move those config element values to the <Analytics> configuration shown below.

<!--
    API usage tracker configuration used by the BAM data publisher and
    Google Analytics publisher in API gateway.
    -->
    <Analytics>
<UIActivityPublishDataSourceName>...</UIActivityPublishDataSourceName>
<UIActivityBAMPublishEnabled>false</UIActivityBAMPublishEnabled>
<Enabled>false</Enabled>
      <CacheStatsEnabled>false</CacheStatsEnabled>
 <PublisherClass>org.wso2.carbon.appmgt.usage.publisher.APIMgtUsageDataBridgeDataPublisher</PublisherClass>
<ThriftPort>7612</ThriftPort>
<BAMServerURL>tcp://localhost:7612/</BAMServerURL>
<BAMUsername>admin</BAMUsername>
       <BAMPassword>admin</BAMPassword>
<BAMEventStreams>....</BAMEventStreams>
<DataSourceName>jdbc/WSO2AM_STATS_DB</DataSourceName>
...
    </Analytics>

In App Manager 1.1.0, the <JDBCPersistenceManager> datasource configuration shown below can be found in both the <APPM_1.1.0>/repository/conf/security/application-authentication.xml file and the <APPM_1.1.0>/repository/conf/identity.xml file. However, in App Manager 1.2.0, this configuration has been moved to the <APPM_1.2.0_HOME>/repository/conf/identity/identity.xml file. Therefore, refer to the datasource configuration in the <APPM_1.1.0>/repository/conf/identity.xml file and update the JDBCPersistenceManager configuration in the <APPM_1.2.0_HOME>/repository/conf/identity/identity.xml file accordingly.
```
<JDBCPersistenceManager>
        <DataSource>
            
            <Name>jdbc/WSO2AM_DB</Name>
        </DataSource>
    </JDBCPersistenceManager>
```

Refer to <APPM_1.1.0_HOME>/repository/conf/social.xml and move the same configuration into <APPM_1.2.0_HOME>/repository/conf/social.xml. This config is to enable relevant database query adaptor in App Manager social components. Following is the query adaptor mapping with database type.

Database Type	Query adaptor class
h2	org.wso2.carbon.social.db.adapter.GenericQueryAdapter
My SQL	org.wso2.carbon.social.db.adapter.GenericQueryAdapter
MS SQL	org.wso2.carbon.social.db.adapter.MSSQLQueryAdapter

If clustering is enabled for a distributed setup, refer to the clustering configurations shown below in the <APPM_1.1.0_HOME>/repository/conf/axis2/axis2.xml file and update the <APPM_1.2.0_HOME>/repository/conf/axis2/axis2.xml file accordingly. In a distributed/clustered setup, refer to thePublisher,Store and Gateway axis2 configuration and update the new configuration.

<clustering class="org.wso2.carbon.core.clustering.hazelcast.HazelcastClusteringAgent" enable="true">
<parameter name="membershipScheme">wka</parameter>
<parameter name="domain">wso2.pub.store.domain</parameter>
<parameter name="localMemberHost">192.168.10.1</parameter>
<parameter name="localMemberPort">4000</parameter>
<members>
   <member>
       <hostName>192.168.10.2</hostName>
       <port>4000</port>
   </member>
</members>
</clustering>

Refer to the SSO configuration shown below in the <APPM_1.1.0_HOME>/repository/deployment/server/jaggeryapps/publisher/config/publisher.json file and map and move the configurations into the <APPM_1.2.0_HOME>/repository/deployment/server/jaggeryapps/publisher/config/publisher.json file. In a distributed/clustered deployment, perform this action in the Publisher nodes only.

"ssoConfiguration": {
        "enabled": true,
        "issuer": "publisher",
        "identityProviderURL": "https://localhost:9444/samlsso",
        "keyStorePassword": "wso2carbon",
        "identityAlias": "wso2carbon",
        "responseSigningEnabled": "true",
        "publisherAcs": "https://localhost:9446/publisher/acs",
        "keyStoreName": "/repository/resources/security/wso2carbon.jks"
}

Refer to the SSO configuration shown below in the <APPM_1.1.0_HOME>/repository/deployment/server/jaggeryapps/store/config/store.json file and map and move the configuration into the <APPM_1.2.0_HOME>/repository/deployment/server/jaggeryapps/store/config/store.json file. In a distributed/clustered setup, perform this action in the Store nodes only.

"ssoConfiguration": {
        "enabled": true,
        "issuer": "store",
        "identityProviderURL": "%https.host%/samlsso",
        "keyStorePassword": "wso2carbon",
        "identityAlias": "wso2carbon",
        "responseSigningEnabled": "true",
        "storeAcs" : "%https.host%/store/acs",
        "keyStoreName": "/repository/resources/security/wso2carbon.jks"
    },

Refer to SSO configuration below in the <APPM_1.1.0_HOME>/repository/deployment/server/jaggeryapps/social/config/social.json file and map and move the configuration into the <APPM_1.2.0_HOME>/repository/deployment/server/jaggeryapps/social/config/social.json file. In a distributed/clustered setup, perform this action in the Store nodes only.

"ssoConfiguration": {
        "enabled": true,
        "issuer": "social",
        "identityProviderURL": "%https.carbon.local.ip%/samlsso",
        "keyStorePassword": "wso2carbon",
        "identityAlias": "wso2carbon",
        "responseSigningEnabled": "true",
        "storeAcs" : "%https.host%/store/acs.jag",
        "keyStoreName": "/repository/resources/security/wso2carbon.jks"
    },

Check for any other configurations that were done for App Manager 1.1.0 based on your deployment and update the new deployment configurations according to the previous configurations. For example, refer to the app-manager.xml file, carbon.xml file, axis2.xml file, etc. in the <APPM_1.1.0_HOME>/repository/config directory and move those configurations into the same file in App Manager 1.2.0. For more information on configuring App Manager distributed deployments, see the App Manager clustering documentation.

In a distributed/clustered setup, complete the two steps given below only in the App Manager Gateway nodes.
Move all your synapse configurations, except the files mentioned below, by copying and replacing the <APPM_1.1.0_HOME>/repository/deployment/server/synapse-configs/default directory with the <APIM_1.2.0_HOME>/repository/deployment/server/synapse-configs/default directory.
- /api/_AuthorizeAPI_.xml
- /api/_RevokeAPI_.xml
- /api/_TokenAPI_.xml
- /api/_StatisticsAPI.xml
Similarly, move your tenant synapse configurations to App Manager 1.2.0. by copying and replacing the backed up tenant folders in the <APPM_1.1.0>/repository/tenants directory with the <APPM_1.2.0>/repository/tenants directory.
Move all the mobile application binary files stored in <APPM_1.1.0_HOME>/repository/resources/mobileapps to <APPM_1.2.0_HOME>/repository/resources/mobileapps location. If you are using a different storage location other than the default location, please perform this action in that particular location.

Upgrading the App Manager to 1.2.0

Stop all running App Manager server instances.
Make sure that you have backed up all the databases, mobile binaries and synapse configs as instructed in step 1 of the previous section.
Download and extract the WSO2 App Manager migration client resource archive.
Unzip wso2-appmgt-migration-client-1.2.x.zip.
Login to database server and execute SQL queries given in wso2-appmgt-migration-client-1.2.x/migration-scripts/dbscripts/constraints against the App Manager datasource. Please select the relevant sql script according to your database type.
ie : If My SQL/h2, use mysql-drop-fk.sql
If Ms SQL, use mssql-drop-fk.sql
Please note that you need to manually execute the first select query to get the constraint name in ‘APM_API_CONSUMER_APPS’ table and use the resulted constraint name in following Alter query
```
ALTER TABLE APM_API_CONSUMER_APPS DROP FOREIGN KEY <constraint_name>;
```
(This particular action is taken due to a primary key alteration done to IDN_OAUTH_CONSUMER_APPS table, during Identity Server migration. IDN_OAUTH_CONSUMER_APPS table's primary key has been used as a foreign key in APM_API_CONSUMER_APPS so that we need to drop the foreign key temporarily)
Copy the relevant database drivers to the <APPM_1.2.0_HOME>/repository/components/lib folder.
Download the WSO2 Identity Server migration client. This is required to migrate the Identity and User Store Database schemas that is used by App Manager. Unzip the downloaded file to the local file system where the wso2is-5.1.0-migration directory is created and do the following:
1. Copy the wso2is-5.1.0-migration/dbscripts/migration5.0.0_to_5.1.0 directory to the <APPM_1.2.0_HOME>/dbscripts directory.
2. Copy the wso2is-5.1.0-migration/dbscripts/identity/migration5.0.0SP1_to_5.1.0 directory and the wso2is-5.1.0-migration/dbscripts/identity/migration5.0.0_to_5.0.0SP1 directory to the <APPM_1.2.0_HOME>/dbscripts/identity directory.
3. Copy the wso2is-5.1.0-migration/dropins/org.wso2.carbon.is.migrate.client-5.1.0.jar file to the <APPM_1.2.0_HOME>/repository/components/dropins directory.
Before you run the migration client as given in the step below, open the <APPM_1.2.0_HOME>/repository/conf/datasources/master-datasources.xml file and set the <username> and <password> elements of the AM_DB JNDI table to that of a user who has permissions to alter tables in the database.
For example,
```
<datasource>
        ...
        <definition type="RDBMS">
            <configuration>
                ...
                <username>xxxxxx</username>
                <password>xxxxxx</password>
                ...
            </configuration>
         </definition>
</datasource>
```
After you are done running the migration client, you can switch these credentials back to a user with lesser privileges.
Start App Manager 1.2.0 with the -Dmigrate -Dcomponent=identity command line option to carry out the complete Identity and User Store DB migration. Alternatively, you can run it step by step by starting the server with the command line options given below in the following order.
- -DmigrateIdentityDB -Dcomponent=identity
- -DmigrateUMDB -Dcomponent=identity
- -DmigrateIdentityData -Dcomponent=identity
- -DmigrateIdentityDBFinalize -Dcomponent=identity
- -DmigrateUMData -Dcomponent=identity
After executing the Identity Server migration client database, registry resources are migrated.
Stop the server after identity migration.
Download WSO2-CARBON-PATCH-4.4.0-0686 and apply it to all the App Manager nodes by following the instructions given in the README.txt file inside.
If you are using any of the embedded h2 databases for WSO2AM_DB, WSO2UM_DB, WSO2REG_DB, JAGH2, or WSO2_SOCIAL_DB, please move those embedded databases into APPM 1.2.0. For that, go to <APPM_1.1.0_HOME>/repository/database folder and move the relevant database into <APPM_1.2.0_HOME>/repository/database folder (You can open to <APPM_1.1.0_HOME>/repository/conf/datasources/master-datasources.xml and get database configuration to figure out which databases are configured with embedded h2 database server)
Copy wso2-appmgt-migration-client-1.2.x/migration-scripts/dbscripts/appmgt/1.1.0-1.2.0-migration directory to the <APPM_1.2.0_HOME>/dbcripts/appmgt folder.
Copy wso2-appmgt-migration-client-1.2.x/org.wso2.carbon.appmgt.migrate.client-1.2.x.jar file to the <APPM_1.2.0_HOME>/repository/components/dropins folder.

Start App Manager 1.2.0 with the following command line options to migrate the database, registry and the file system all together or separately based on each profile.

Description	Command	Example
To migrate the database, registry and file system all together. This migrates the webapp related registry resources, databases and synapse configurations. Ideally, this migration command option is required for a standalone pack.	-Dmigrate=true -DmigrateToVersion=1.2.0	./wso2server.sh -Dmigrate=true -DmigrateToVersion=1.2.0
To migrate the database only. This migrates the WSO2AM_DB. Distributed setup In a distributed setup, perform this action in one of the Store/Publisher/Gateway nodes where the WSO2AM_DB is configured	-DmigrateDB=true -DmigrateToVersion=1.2.0	./wso2server.sh -DmigrateDB=true -DmigrateToVersion=1.2.0
To migrate the registry only. This migrates the registry resources only. Distributed setup In a distributed setup, perform this action in one of the Store/Publisher nodes where the registry is shared	-DmigrateReg=true -DmigrateToVersion=1.2.0	./wso2server.sh -DmigrateReg=true -DmigrateToVersion=1.2.0
To migrate the file system only. This migrates the Webapp API configuration files. Distributed setup In a distributed setup, perform this action in one of the Gateway nodes where the synapse configuration files are available.	-DmigrateFS=true -DmigrateToVersion=1.2.0	./wso2server.sh -DmigrateFS=true -DmigrateToVersion=1.2.0
To migrate active tenants only. Migrate active tenants only Optional: If you have any disabled/inactive tenants in your previous version of WSO2 App Manager that you do not want to bring forward to the next version, you can use DmigrateActiveTenantsOnly flag to do a complete or registry or file system based migration for active tenants only.	-Dmigrate=true -DmigrateToVersion=1.2.0 -DmigrateActiveTenantsOnly	./wso2server.sh -Dmigrate=true -DmigrateToVersion=1.2.0 -DmigrateActiveTenantsOnly

Do the following to re-index the artifacts in the registry:
1. Rename the <lastAccessTimeLocation> element in the <APPM_1.2.0_HOME>/repository/conf/registry.xml file. If you use a clustered/distributed App Manager setup, change the file in the 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 App Manager 1.2.0 server, back up and delete the <APPM_1.2.0_HOME>/solr directory.
Restart the server.
Login to admin console as the admin user and navigate to /_system/config/repository/components/org.wso2.carbon.registry/queries using registry browser. Then delete all the queries listed under "queries" collection (allTags,latest-apis,resource-by-tag,tag-summary and tagsByMediaTypeAndLifecycle). Likewise login to each tenant space and delete all the tag queries.

If you are using gateway applications with WSO2 Identity Provider(WSO2 IS), please continue with the below steps. If you are not using gateway applications or if you are having an external Identity Server as the Identity provider, please ignore following steps on Service Provider migration.
Login to carbon console of Identity Provider Node (WSO2 Identity Server)
Go to Identity > Service Providers in the left menu and select service provider list
Now you can see the list of available service providers
Select the service provider that you need to update and click 'Edit' button. (The service provider name is composed as {webapplication name}-{webapplication-version}, so that the corresponding service provider of a given webapp can be easily identified by the name)
You will see the Service provider detail page. Then click on 'Inbound Authentication Configuration'
Select on 'SAML2 Web SSO Configuration' under the 'Inbound Authentication Configuration'
Click on 'Edit' button
In App Manager 1.2.0, a postfix can be appended to Assertion Consumer URL. The postfix configuration is there in <APPM_1.2.0_HOME>/repository/conf/app-manager.xml. Under <SSOConfiguration>, you will find following configuration, where the postfix can be configured.
```
<SSOConfiguration>
       .........
        
        <ACSURLPostfix>appm/acs</ACSURLPostfix>
       .........
</SSOConfiguration>
```