View source for Upgrading to Version 10.16

AgileApps upgrade program supports the following AgileApps server upgrades:

::For both Windows and Linux, you can upgrade to 10.16.0 from the following versions:
:::* Version 10.9.x
:::* Version 10.10.x
:::* Version 10.11.x
:::* Version 10.12.x
:::* Version 10.13.x
:::* Version 10.14.x
:::* Version 10.15.x

{{Note|<br> Post installing AgileApps 10.16, if you want to use the Integration Server, it doesn't start as expected.<br>
You may want to start the Integration Server using the webMethods Installer, perform the following step before starting the Integration Server.
:* Copy the ''ESAPI.properties'' file from the path '''{InstallDir}\IntegrationServer\instances\default\config\security\esapi''' to the path '''{InstallDir}\profiles\IS_default\configuration\tomcat\conf\RN\esapi'''}}

===Upgrade program===
AgileApps Cloud uses an upgrade program to update from an existing application server to the target application server.  
{{Note| 
:* 10.9, 10.10, 10.11, 10.12, 10.13, 10.14, 10.15 are the existing application servers.
:* 10.16 is the target application server.
:* You must start the Integration Server after installing AgileApps 10.16 using webMethods InstallerCopy ''ESAPI.properties'' file from the path '''{InstallDir}\IntegrationServer\instances\default\config\security\esapi''' to the path '''{InstallDir}\profiles\IS_default\configuration\tomcat\conf\RN\esapi'''.}}

====Highlights====
:* The upgrade program migrates the configuration changes from an existing application server to the target application server. Changes include the files like '''networking.properties, custom_wrapper.conf, log4j.properties, quartz.properties''' and so on. After the upgrade is complete, a report of the upgrade program is available at '''{install_dir}/aal-upgrade/upgrade/SummaryReport.txt'''.
:* The upgrade program takes a backup of the primary databases (db1000, db892085391, db766224774 & relationals) and tenant databases. Use these databases, if you have to revert AgileApps to the source environment that existed prior to this upgrade. To revert to the source environment, restore the backed up databases and restart the AgileApps server from the source environment. For example, if we have run this utility to upgrade from 10.15 (Source environment) to 10.16 (Target environment) and want to revert to 10.15, first restore the databases backed up from 10.15 which is the source environment and then restart the AgileApps server.
{{Note|If the 10.16 AgileApps server is running, ensure to stop this server before you revert to the source environment.}}
:* The program upgrades the primary database and database of the tenant to the target installation by running the required SQL patches.
:* The upgrade program migrates the custom JARs from an existing application server to the target application server by reading the '''‘_custom_libs’''' property available at '''{install_dir}/aal-upgrade/upgrade/upgrade_supported_configurations.txt''' file. 
{{Note|
* This upgrade utility program must be run on every application server and web server.
}}

====Prerequisites:====
:* Set a minimum value of 512 MB or more for '''max_allowed_packet''' property in '''my.cnf''' or '''my.cfg''' (MySQL configuration files) under '''[client]''', '''[mysqld]''' & '''[mysqldump]''' sections. 
:* Verify the privileges to access the source database with the username, password, host-name and port as mentioned in the '''com.softwareag.catalina.resource.pid-agileappsRN.properties''' file under the target application server. Use the following command to ensure that you have the database access:
::;mysqldump -u<DB_USER_NAME> -p<DB_PASSWORD> -h<DB_SERVER_HOST_NAME> -P<DB_PORT> db<DB_NUMBER> > db<DB_NUMBER>.sql
::For example: mysqldump -uthomas -pthomas -hvmaalind05 -P3306 db1108948326 > db1108948326.sql
:* You must have read, write and execute permissions to the target installation directory {install_dir}.
:* Ensure to restart the MySQL server, if you perform any configuration updates to MySQL.

====Upgrading to 10.16====
#Stop the existing application server.
#Install the 10.16 application server using SoftwareAG installer. For more information, see '''webMethods 10.5''' Installation documents available on Empower.
{{Important|
*Do not run the 10.16 application server after installation.
*After the installation, the 10.16 application server exists in parallel with the existing application server.
*Do not initiate the upgrade program.}}
:3. Create a new folder '''aal-upgrade''' in the installed 10.16 root directory '''{install_dir}'''.
:4. Extract '''upgrade.tar.gz''' available at '''{install_dir}/AgileApps/upgrade''' to the '''{install_dir}/aal-upgrade''' directory. The extracted folder consists of three files '''upgrade.sh, upgrade.jar, upgrade_supported_configurations.txt,''' and one folder '''db-upgrade-patches'''.
:5. Copy the MySQL connector jar based on your MySQL version and place it under {install_dir}/aal-upgrade/upgrade/libs directory.
{{Note|Ignore this step if the MySQL connector jar is already present in the said location.}}
:6. Provide executable permission to '''upgrade.sh''' file by using '''chmod''' command. For example, ''chmod 765 upgrade.sh''.
:7. Run the '''upgrade.sh''' file with mandatory parameters.

:: '''Mandatory parameters'''
:::A. '''--aal-path''' - provide the folder path of the existing application server. 
::::Example: '''--aal-path=/{install_dir}/aal-lab/AgileApps10.15'''
:::B. '''--aal-version''' - provide the version number of the target application server. 
::::Example: '''--aal-version=10.16'''
:::{{Note|If the aal-version number and the target application server number given in step 2 are not same, errors can occur.}}
:::C. '''--instance-name''' - provide the source-instance of the source application server and target-instance of the target application server. 
:::Syntax: '''--instance-name=<source_instance_name>:<target_instance_name>''', where instance-name is the profile name.
::::Example: '''--instance-name=IS_default_10.15:IS_default_10.16'''


:: '''Non-mandatory parameters'''
:::A. '''--aal-db-backup-folder {-DBF}''' - provide a path for backup of all the primary and tenant databases. 
::::Example: '''--aal-db-backup-folder=/{install_dir}/aal-lab/AgileApps10.15_DB_Backup'''
{{Note|If you do not use this option, ensure to manually take a back up of all the primary and tenant databases from the source environment before you perform the upgrade.}}
:::B. '''--remote-source {-RS}''' - provide this option if the source is installed on a remote machine. If you provide the RS parameter, then the upgrade program ignores the '''--aal-path''' from the mandatory parameter and a new source path is set.
::::Example: '''--remote-source=no|yes''' or '''--remote-source (~ yes)'''
{{Note|This parameter '''--remote-source {-RS}''' is not supported on the Windows version of AgileApps.}}

{{Note| 
*If the upgrade program finds RS parameter in the command then the upgrade program copies the required and related configurations from the remote machine to the local machine and upgrades the server. 
*The upgrade program uses Linux SCP command for connecting and transferring the source configurations. This requires you to provide the user credentials to access the remote machine.
*If the username has any special characters that have to be escaped, then you have to enter the username with the escaped character. For example, username '''eur\alsh''' should be entered as '''eur\\alsh'''.}}
::C. '''--enable-quartz {-Q}''' - This parameter enables quartz configuration in the target application server. This parameter includes the Import and Export configurations also. Do not provide this parameter, if you are using a different server or node for running the Quartz configuration.
:::Example: '''--enable-quartz=no|yes''' or '''--enable-quartz (~ yes)'''
::D. '''--ignore-db-upgrade {-IDU}''' - This parameter is for the environment with multiple nodes or servers connected to a centralized database server. Disable the database upgrade for target application server. 
:::Example: '''--ignore-db-upgrade=no|yes''' or '''--ignore-db-upgrade (~ yes)'''

:: '''Note:'''
::*Provide the value for the mandatory parameter separated by equal (=) character. For example, '''--aal-version=10.10''' 
::*Provide the non-mandatory parameters with values ‘yes’ or ‘no’ separated by equal (=) character. This Note is not valid for '''--aal-db-backup-folder  {-BDF}'''.
::*The values ‘yes’ and ‘no’ are not case sensitive. 
::*Syntax: {install_dir}/aal-upgrade/upgrade.sh mandatory-param1=val1 mandatory-param2=val2 mandatory-param3=val3 non-mandatory-param4 non-mandatory-param5 non-mandatory-param6. For example:  '''upgrade.sh --aal-path=/home/aal-lab/AgileApps10.14  --aal-version=10.15  --aal-db-backup-folder=/home/aal-lab/AgileApps10.14_DB_Backup''' 
::*In case of errors, look at the log messages available at '''upgrade.log''' file under '''aal-upgrade/upgrade/logs'''.

{{Important|
::*The upgrade utility program does not change the docs directory and temp directory paths of the target application server and points to the paths of the existing application server.
::*To change the path of docs directory and temp directory to a different location, go to Configure Service Settings.}}
:7. Copy the '''keystoreFile''' file from the existing application server to the target application server. The '''keystoreFile''' property is available at '''<EXISTING_10.x_INSTALL_DIR>/profiles/IS_{profile_name}/configuration/com.softwareag.platform.config.propsloader/com.softwareag.catalina.connector.https.pid-8284.properties'''.
:8. Copy the '''@secure.keystorePass''' value from the existing application server to the target application server. The '''@secure.keystorePass''' value is available at '''<EXISTING_10.x_INSTALL _DIR>/profiles/IS_{profile_name}/configuration/com.softwareag.platform.config.propsloader/com.softwareag.catalina.connector.https.pid-8284.properties'''.
:9. Start the 10.16 application server available at '''{install_dir}/profiles/IS_{profile_name}/bin/startup.sh''' 
:10. In case of errors, check:
::'''{install_dir}/profiles/IS_{profile_name}/logs/wrapper.log''' 
::'''{install_dir}/profiles/IS_{profile_name}/logs/relationals.log''' 
:11. For custom configuration, proceed to [[Configuring the Application Server]].

=====Considerations=====
::* This upgrade program reads the custom libraries like third-party JARs from the '''upgrade_supported_configurations.txt''' file available at '''{install_dir}/aal-upgrade/upgrade''' folder.
::* If you want to copy any custom library (jars) file from the existing application server to the target application server, then update '''_custom_libs''' property. If there are multiple jars, separate the jars with a comma. For example: '''_custom_libs=docx4j-3.3.0.jar,el-api.jar,ehcache-2.10.2.jar'''.
::* If '''--remote-source''' option is provided in the command, you must have the  permission to copy the configuration files from the existing application server present on the remote machine.
::* This program is designed to upgrade a single AgileApps server or multiple AgileApps servers (web servers or application servers) in a cluster which are pointing to the single centralized database (MySQL) server. While running the upgrade program, ensure that you always point to the source database and do not point to any newly installed database.
::* This program assumes that there are no changes in the service domain during the upgrade. However, if there are any such requirements, then this is considered as a manual process. The below mentioned SQL scripts can be followed to change the service domain immediately after running the upgrade program but before starting the target application server.
:::(a)
::::<syntaxhighlight lang="java" enclose="div">
 - Update db892085391.NETWORK_ISV_SETTINGS set service_domain_3 = '<NEW_DOMAIN_WITH_PREFIX>' ;
</syntaxhighlight>
:::(b) If you have any prefix in the domain name, like '''sag.agileappscloud.eu''' (here sag is a service domain prefix), this implies the subdomain is enabled. Otherwise, follow next point (point C).
::::<syntaxhighlight lang="java" enclose="div">
 - UPDATE db892085391.NETWORK_ISV_SETTINGS set service_domain_prefix = '<DOMAIN_PREFIX>' ;
 - UPDATE db892085391.NETWORK_ISV_SETTINGS set service_domain = '<DOMAIN_WITHOUT_PREFIX>' ;
 - UPDATE relationals.NETWORK_CUSTOMER set service_domain = replace(service_domain,'<OLD_DOMAIN_WITHOUT_PREFIX>','<NEW_DOMAIN_WITHOUT_PREFIX>');
 - UPDATE db892085391.NETWORK_8c5b349851c041a28d19277a12dee8f0 set portal_service_domain = replace(portal_service_domain , '<OLD_DOMAIN_WITHOUT_PREFIX>','<NEW_DOMAIN_WITHOUT_PREFIX>');
</syntaxhighlight>
:::(c) If you do not have any prefix in the domain name, this implies the subdomain is not enabled.
::::<syntaxhighlight lang="java" enclose="div">
 - UPDATE db892085391.NETWORK_ISV_SETTINGS set service_domain = '<NEW_DOMAIN_WITH_PREFIX>' ;
</syntaxhighlight>
:::(d)
::::<syntaxhighlight lang="java" enclose="div">
 - UPDATE relationals.NETWORK_GLOBAL_PROPERTIES set assets_domain = '<NEW_DOMAIN_WITH_PREFIX>';
</syntaxhighlight>
::* This program does not copy the SSL certificate and its username and password from the existing application server to the target application server and must be done manually, if required.