Upgrade

This section describes how to upgrade to the latest version of SuperWEB2 from an earlier version.

You must upgrade both SuperSERVER and SuperADMIN before upgrading to SuperWEB2. Learn more about upgrading SuperSERVER.

Step 1 - Plan for the Upgrade

In this release there have been a number of changes to the way SuperWEB2 is configured.

For example, a number of configuration options that were previously set in <tomcat_home>\webapps\webapi\WEB-INF\faces-config.xml and <tomcat_home>\webapps\webapi\WEB-INF\web.xml are now defined in a new configuration file, <tomcat_home>\webapps\webapi\WEB-INF\classes\configuration.properties.

There are other configuration adjustments that were previously set in the configuration files and which are now set in SuperADMIN.

When you upgrade to this release, it will not be possible to simply copy across the modified configuration files from your old version. After upgrading you will need to follow the new instructions to reapply any customisations or configuration adjustments that you need.

Before starting, it is a good idea to make a note of all the configuration adjustments you have made to your existing system. You can then check Changes to Configuration Options in this Release for details of how to reapply the customisations after you install the new version.

To avoid downtime, you may wish to leave your existing deployment running while you install the new release of SuperWEB2 on a new sever. This will allow users to continue to access your system while you complete the upgrade.

Once you have finished applying the relevant configuration adjustments to the new server you can then redirect users to the new version.

Step 2 - Backup Old SuperWEB2 Configuration

Although you will not be able to reuse the configuration files from your old version, you are recommended to backup these files before starting. If necessary, this will allow you to check any customisations that you had made to the old version, or roll back to the previous version if necessary.

The following files are the minimum subset that you should backup:

Any language customisations you have made to <tomcat_home>\webapps\webapi\WEB-INF\common_labels.properties and <tomcat_home>\webapps\webapi\WEB-INF\message.properties (and the corresponding versions for other languages)
Any custom UDF and TXDs saved in <tomcat_home>\webapps\webapi\WEB-INF\resources
Any HTML info pages saved in <tomcat_home>\webapps\webapi\info
Any customisations you have made to the metadata pages in <tomcat_home>\webapps\webapi\help
All files in <tomcat_home>\webapps\webapi\WEB-INF\data\.repository
<tomcat_home>\webapps\webapi\WEB-INF\classes\configuration.properties (only required if upgrading from 9.0 or above; this file was added in release 9.0, and will contain many of your configuration settings)
<tomcat_home>\webapps\webapi\WEB-INF\web.xml
<tomcat_home>\webapps\webapi\WEB-INF\faces-config.xml

You may wish to backup the whole of the <tomcat_home>\webapps\webapi directory just in case.

The location of <tomcat_home> will depend on the location where Tomcat is installed on your system. The default location for Space-Time Research deployments of Tomcat is C:\ProgramData\STR\SuperWEB2\Tomcat

Step 3 - Install SuperWEB2

Stop Tomcat if it is running.
Delete the following files and directories (some of these files may not exist on your system, depending on which version you are upgrading from):
- <tomcat_home>\work
- <tomcat_home>\lib\hsqldb-*.jar
- <tomcat_home>\lib\webservices-rt.jar
- <tomcat_home>\lib\spring-agent.jar
- <tomcat_home>\webapps\webapi
- <tomcat_home>\webapps\webapi.war
If applicable, prepare the User Data Repository for the upgrade by making sure that the SuperWEB2 user that writes to your external database has both ALTER and CREATE privileges over the tables in that database. If your database administrator will not allow the SuperWEB2 user to have ALTER and CREATE privileges, you will need to manually upgrade the databases. See the steps below for more information.

If you are not sure which user is configured for the connection to the external User Data Repository, check the details specified in <tomcat_home>\conf\server.xml

When you run SuperWEB2 it will automatically update any saved data in the User Data Repository to the latest version. This process is not reversible, so you may wish to backup your data from the external database first in case you ever need to revert to the previous version of SuperWEB2.
Extract the SuperWEB2 ZIP file.
Copy War Files\webapi.war from the extracted files to <tomcat_home>\webapps
Copy tomcatLibs\spring-agent.jar from the extracted files to <tomcat_home>\lib
Start Tomcat and verify that you can connect to SuperWEB2 in a web browser.

Step 4 - Reapply any Customisations

You will now need to reapply any customisations from your previous deployment. See Changes to Configuration Options in this Release for help with this step as many settings have moved between version 8 and version 9.

Do not simply copy your backed up configuration files across. The files have changed in this release, and some settings are now configured differently. You will need to recreate your customisations by following the new instructions.

If the version you are upgrading from is 9.0 or above, then you will need to reapply your changes to configuration.properties. It is important not to simply reuse your backup, as other settings may have been added to the file in this release.

Manual Upgrade of User Data Repository

If your database administrator will not allow the SuperWEB2 user to have CREATE TABLE and ALTER TABLE privileges, then you will need to manually upgrade the tables in the User Data Repository database.

If SuperWEB2 does not have the appropriate privileges, you will see an "insufficient privileges" error message similar to the following in the SW2.log file:

CODE

Caused by: java.sql.SQLException: ORA-01031: insufficient privileges
        at oracle.jdbc.driver.DatabaseError.throw.SQLException(DatabaseError.java:112)
        at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:331)
        at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:288)
        at oracle.jdbc.driver.T4C80all.receive(T4C80all.java:745)
        at oracle.jdbc.driver.T4CPreparedStatement.do0all8(T4CPreparedStatement.java:219)
        at oracle.jdbc.driver.T4CPreparedStatement.executeForRows(T4CPreparedStatement.java:970)
        at oracle.jdbc.driver.OracleStatement.doExecuteWithTimeout(OracleStatement.java:1190)
        at oracle.jdbc.driver.OraclePreparedStatement.executeInternal(OraclePreparedStatement.java:3370)
        at oracle.jdbc.driver.OraclePreparedStatement.executeUpdate(OraclePreparedStatement.java:3454)
        at org.apache.tomcat.dbcp.dbcp.DelegatingPreparedStatement.executeUpdate(DelegatingPreparedStatement.java:105)
        at org.apache.tomcat.dbcp.dbcp.DelegatingPreparedStatement.executeUpdate(DelegatingPreparedStatement.java:105)
        at org.eclipse.persistence.internal.databaseaccess.DatabaseAccessor.executeDirectNoSelect(DatabaseAccessor.java:842)

To resolve this:

Run Tomcat at least once so that the SuperWEB2 war file gets extracted.
Browse to the extracted files and locate <tomcat_home>\webapps\webapi\WEB-INF\classes\au\com\str\services\repository\dao\impl\sql\upgrade_9_0_0_<db>.sql (where <db> is the type of RDBMS you are using for the UDR).
Provide this file to your database administrator and ask them to execute the SQL commands to upgrade the databases to the correct version.

If you are upgrading from a version of SuperWEB2 prior to 8.0 then you will also need to ask your administrator to run <tomcat_home>\webapps\webapi\WEB-INF\classes\au\com\str\services\repository\dao\impl\sql\upgrade_8_0_1_<db>.sql (this should be run first, followed by the upgrade_9_0_0_<db>.sql script).
In addition, ask your database administrator to execute the following SQL (this sets the internal version number of the UDR database to the current version, version 5):
SQL
```
TRUNCATE TABLE SCHEMAINFO;
INSERT INTO SCHEMAINFO (ID, VERSION) VALUES (1, 5);
```

Step 5 - Advise Users that the Upgrade is Complete

Once you have finished reapplying any customisations, you can advise your users that the upgrade is complete. In some cases, users may need to manually refresh their browsers to see the latest version of SuperWEB2. This is because their web browser may have cached the resources from the previous version (such as the product logo and the stylesheets).

If users are still seeing the old look and feel of SuperWEB2, this can be resolved in most cases by pressing F5 to refresh the web browser.