Upgrading ViewsFlash

Upgrading to ViewsFlash 9 from versions 6 and higher

NEW: Detailed upgrade instructions at the end of this page. Read these general considerations first.

Summary: ViewsFlash does not coexist simultaneously with earlier releases. If you have two or more instances of ViewsFlash sharing the same database, shut down all instances before upgrading, and upgrade ViewsFlash on all instances. When you upgrade, all data is upgraded automatically. Backup the database before upgrading.

The upgrade process consists of reviewing the servlet parameters, shutting down the ViewsFlash application, upgrading the ViewsFlash application with the new ViewsFlash.war file, and bringing the application back up.

For upgrading from version 7 to 8, just upgrade the ViewsFlash.war file.

Click here if you are Upgrading from versions older than ViewsFlash 6.

Changes to be aware of before upgrading to ViewsFlash 8 from version 6:

Uploaded attachments are now stored in the database by default, rather than the file system, and attachments are copied from the file system to the database's VWFOBJECTS table automatically upon startup. To prevent this and continue with the legacy behavior of storing attachments in the file system, see Attachments for the exact servlet parameters to use.

When using Oracle as the ViewsFlash database, note the following change.

If you were using database=Oracle, Oracle9,Oracle10, or Oracle11, and you did not specify a databaseextension parameter, a databaseextension parameter of "OracleDatabaseExtension" was used by default. In ViewsFlash 7, a new default is used, namely: OracleDatabaseExtension, Oracle9DatabaseExtension,Oracle10DatabaseExtension, or Oracle11DatabaseExtension. The effect of this change is that a new column, ANSWERCLOB, of type CLOB, is added to the VWFDATA table. This column is used to store data from text fields, allowing storage of very large text fields automatically. Data that has already been stored in the VWFDATA table is automatically moved to the new column when necessary. To prevent this change and to use the legacy behavior, provide explicitly the servlet parameter:
databaseextension=OracleDatabaseExtension.
If the ViewsFlash application's database user has the right to CREATE and ALTER tables, the new column will be added automatically. Otherwise, create the new column manually using:
ALTER TABLE VWFDATA ADD ( ANSWERCLOB CLOB );

If the application's database user does not have the CREATE TABLE right, look at the appropriate *.sql files inside the WEB-INF/sql directory in ViewsFlash.war, and create the EXAMPLES_CAR_BRANDS table using the SQL DDL provided there before upgrading.

After downloading the ViewsFlash.war file, examine its WEB-INF/web.xml file and compare it to your deployed web.xml. If they are identical, you can simply redeploy the new war file. If you have made changes to your web.xml file, the easiest way to upgrade is to unpack the war file, replace the web.xml file with yours, repack the war file, and redeploy it. Alternatively, you can stop the application, save web.xml, redeploy the new war file, restore web.xml, and restart the application.

All out of the box Styles are upgraded automatically when you upgrade to ViewsFlash 7. Styles that have been customized will continue to work as before.

Step by step upgrade instructions

These notes are written for Tomcat 6 and 7, and they are easily adapted for any application servers have similar procedures.

Before you start

Read the Installation documentation to review the original deployment process. The Installation page in your current ViewsFlash's Help will give you the exact procedure that was used for its deployment.

In your browser go to the ViewsFlash application, logging in with a ViewsFlash administrator's credentials, and enter the Diagnose URL
ViewsFlash/servlet/vfadmin??Diagnose=1
as described in Installation, and save what it displays. At the end of the upgrade, you will want to compare it with the same command after the upgrade. The Diagnose URL is the definitive source for the actual servlet parameters that are being used in a deployed system.

Here is an example of some of the Diagnose output. Many lines have been removed for clarity:

    ViewsFlash 8.2 Build_8.2 / 802  02/26/2015 01:10 PM
...
    Initialization Parameters:
    Servlet initialization parameters:
    database=MySQL
    data=/etc/cogix/datatemp3
    dbstores=data|polls|results|styles|votes
    license=type=unlimited;bdb=y;bua=y;brs=y;bwp=y;vrs=5;who=Cogix;licensekey=(omitted)
    datasource=java:comp/env/cogix
    appsecurity=user
    apiattribute=com.cogix.vwf.api
    administrators=(not displayed)
    datareviewapi=true
    upload.maxsize=20000000
    propertiesfile=/etc/cogix/viewsflash.properties
...
    Checking data directory /etc/cogix/datatemp3
    - Directory exists.
    - Data directory successfully open for writing: /etc/cogix/datatemp3
...
    - Log file successfully written: /etc/cogix/datatemp3/viewsflash.log
...
    Web App Name: /ViewsFlash
...
    Checking database
    Driver  date 05/26/06 10:41  Binary data type MEDIUMBLOB JDBC Driver major version: 5 minor version: 1
    Database access class: com.cogix.vwf.MySQLNamedDataSource
    Normalized database class: com.cogix.vwf.MySQLDatabaseExtension@7c3d8cb

This information is necessary for the next steps.

The "data" directory located by the data= initializaiton parameter.
The viewsflash.properties file located by the propertiesfile= parameter.
The database schema whose JNDI data source is indicated by the datasource= parameter.
All files inside the exploded ViewsFlash application directory that were modified manually. If you don't have a record of them, use this procedure to find what was changed. Most common changes are web.xml and files added at the top level of the ViewsFlash directory.
The web.xml file in the exploded ViewsFlash web application file ViewsFlash/WEB-INF/web.xml.
The exploded ViewsFlash application's directory.
The most common case is that no changes have been made to the ViewsFlash application and you can just use the new ViewsFlash.war file without modifications.

Update web.xml in the exploded directory with any modifications made to web.xml in the previous deployment.
Copy any added or changed files to the new exploded directory that were modified in the previous deployment.
Modify viewsflash.properties if any new parameters are needed for the new release.
If your application server requires a packed ViewsFlash.war file for upgrading, repack the ViewsFlash.war file from the exploded directory.
Create a document with all the changes made to the ViewsFlash exploded directory for future reference.

To upgrade, there are several ways: in-place upgrade on the same application server. Follow the steps above and have the updated exploded ViewsFlashdirectory or the ViewsFlash.war file ready.

In place upgrade

If on a single server, use hot deployment. In Tomcat, copy the ViewsFlash.war file to Tomcat's webapps directory.
If on a Tomcat cluster, shut down all servers. Delete both the ViewsFlash.war file and the exploded ViewsFlash directory from Tomcat's webapps directory. Copy the new ViewsFlash.war file to the deployment directory and restart one server. After checking the new deployment, restart the other servers in the cluster. For other application servers, follow the recommended procedure for updating a web application throughout the cluster.

Checking the new deployment

With your browser, go the ViewsFlash home, usually myserver.com/ViewsFlash
If you get an error message, including a 404, something failed during deployment. Look in the system log (in Tomcat, logs/catalina.out), Also look at the viewsflash.log file, whose location was shown in the Diagnose command that was used during the preparation, above. Correct any errors mentioned in the logs and repeat the deployment.
Once the application is running, use the Diagnose=1 command and check it for errors. If you see a message about Styles need upgrading, a link will be provided to that; click on the link.
Compare the Initialization parameters section of the Diagnose display with the previous deployment. You should be able to explain any differences.
In the ViewsFlash Home page, click on Examples and complete each one. There should be no glitches anywhere.

Upgrade to a new server

Clone the application server, or create a new one if you prefer. If you want to change application servers, this is as good a time as any.
Assign an interim DNS to the new deployment and use it throughout.
Clone the database in the production system. Modify the JNDI datasource to point to the cloned database. BE CAREFUL that you don'tend up with the new ViewsFlash using the same database as the existing ViewsFlash. This can cause data loss which will require restoring the database in the production server. If using Oracle, make sure that the sequences VWFNOTIFICATIONSEQUENCE and VWFDATASEQUENCE are present in the cloned database, and set their values to a larger value than the value in the current database.
Deploy the modified ViewsFlash.war exploded directory or ViewsFlash.war file to the new application server.
On a clustered system, it may be easier to add additonal nodes to the cluster at this point, or you can wait.
Start up the new server and follow the Checking new deployment procedure. Correct any errors until successful.
You now have a clone of the production system running on a new server. Let users know and have them test their questionnaires on the new system until satisfied.
When ready:
- shut down the production servers
- shut down the test server
- change the JNDI datasource to point the production database
- Change DNS to point to the new server
- Start up the new server, which is now the production server.
- On a clustered system, if you not added clustered nodes earlier, do so now.
A simpler alternative, with less robust testing, is to deploy the new ViewsFlash to a new server using a different JNDI datasource that uses a new empty schema. Check to see that ViewsFlash works properly. Once it does, change JNDI datasource to the production data source and check everything again.

Find out what has changed

Explode the ViewsFlash.war file to a temporary directory
Use a directory comparison tool to compare this directory to the original exploded directory..
Files that are different will probably need to have the same modificaitons made to the new ViewsFlash exploded directory.
Files that exist only in the exploded directory will need to be copied to the new ViewsFlash exploded directory.
Create a document detailing this for future reference.

Next: Upgrading Style Templates