Installing ViewsFlash

If you are upgrading from an earlier version, see Upgrading for a detailed guide.

For architecture and in-depth discussion of all installation and deployment issues, see System Administration.
For detailed database information, see Using a database.
For detailed information on application security, see Application Security.
For a simple initial development deployment this section is usually sufficient.

For how to deploy the Cogix Survey portlet in Liferay, WebSphere, Vignette or Liferay portals, read these instructions as a general guideline, and then follow the specific instructions provided at www.cogix.com for that portal in the JSR 168 section.

Deployment complexity depends on whether a database will be used now and whether application secutiry will be used now. Both can be added after initial deployment. Without a database, email invitations and staging are disabled. Without application security, weak password protection is used.

Easy Express Installation. For a quick evaluation, all you need to do is:

Create a Data Source in your application server, and assign it the name "ViewsFlash". If you are in a big hurry, you can omit this step and data will be stored in the file system in a temp directory, but note that all data is erased when your app server restarts.
Download ViewsFlash.war and install it in your application server
Check the application server logs for a successful installation or error messages.
Go to http://yourserver.com/ViewsFlash and continue from there
This is the equivalent of a normal Full Installation with a data= parameter set to the application server's temp directory, no license key (each page will include an "Evaluation Copy" message), no application security, database= derived from a Data Source named "viewsFlash". If any of these defaults are not acceptable, then you must follow the instructions below.

Full installation

Download ViewsFlash.war
If using a database, configure a Data Source in the application server and optionally create the ViewsFlash tables
If using application security, implement the security constraint roles defined in WEB-INF/web.xml
Provide ViewsFlash with servlet parameters in a viewsflash.properties file or in WEB-INF/web.xml
Deploy ViewsFlash.war application in the application server
Check for successful installation
Perform additional setup tasks
Troubleshoot

Before deployment, print this page and gather the information needed using the worksheet below. Use this information to prepare ViewsFlash servlet parameters, and then deploy the application.

Step by step procedure

If you haven't already done so, fill out the download request form at www.cogix.com, and download the ViewsFlash.war at the link provided in the return e-mail. Use the java JAR utility to expland ViewsFlash.war to a temporary directory for examination or open the file with a utility such as WinZip.
Identify and create a data directory on the application server file system for the ViewsFlash application. The application server must have read/write/create rights to the directory. and write its full path in the data parameter of the worksheet. In a Windows server, start with the drive letter, like this: C:/cogix/data, using the exact capitalization of the directories.
If you have received a license key, note it. If you don't have one, it can be added later; without a license key, the application will stop running in 30 days, and pages will contain an "Evaluation Copy" message. To get an evaluation key, contact Cogix.
(If using a database) Enter in the worksheet the name that corresponds to your database. For additional information for your database and your application server, see Database specific information.

(If using a database) The database must be available as a named datasource in the application server. The data source should use Connection Pooling and auto-commit. It does not need to use XA Transactions. The database user associated with the datasource should, if possible, have the right to create, modify and delete tables. If this is the case, there is no need to create the ViewsFlash tables in advance. If this is not permitted, usually for security reasons, then the tables must be created before deploying ViewsFlash, using the SQL scripts provided in the appropriate directory in WEB-INF/sql in the expanded ViewsFlash.war file. Write the name of the JDBC Data Source in the datasource parameter of the worksheet. If you plan to deploy without a database now and to add the database later, see Using a Database.
Different application servers use different naming conventions. The following table shows a sample JNDI data source name and its corresponding servlet parameter:

Application server	JNDI data source name	datasource= parameter
WebSphere	MyDB	MyDB
WebLogic	MyDB	MyDB
Tomcat	jdbc/MyDB	java:comp/env/jdbc/MyDB
JBoss	MyDB	java:/MyDB

(If using application security) Review and modify the security constraint elements in WEB-INF/web.xml, especially the security roles. These roles may need to be mapped to other roles or groups, depending on your application server. In WebSphere, ViewsFlashRespondent is usually mapped to the All Authenticated group. In Weblogic, review and modify the WEB-INF/weblogic.xml file.
Use the appsecurity=user parameter, and also enter an administrators= parameter that lists the names and/or roles of users who are the designated ViewsFlash application administrators; these users grant and delegate access rights.
(If not using application security) Enter an adminpw= parameter, which will be used by the ViewsFlash administrator to enter the application. Individual users will be able to create their own passwords to protect their own application areas.
The Servlet Parameter Reference section explains less commonly used parameters.
Having compiled the worksheet with servlet parameters, provide them to the ViewsFlash application in one of these three ways:
a) Create a viewsflash.properties file at /etc/cogix, like this one, and fill in the values.
Each line has a property name and a property value, separated by an equals sign. Lines with a # are comments.
In a Windows server, this file must be on the same drive as the application server, at \etc\cogix\viewsflash.properties

b) If it is not possible to use /etc/cogix, create the viewsflash.properties file in another directory and enter its location in the propertiesfile init-parameter in WEB-INF/web.xml.

c) Do not use a viewsflash.properties file at all, and enter each servlet parameters as an init-parameter in WEB-INF/web.xml.
Remove the propertiesfile init-parameter, and enter each parameter as an init-param element in the viewsflash servlet element.
Example:
<servlet>
  <servlet-name>viewsflash</servlet-name>
  <servlet-class>com.cogix.vwf.viewsflash</servlet-class>
      <init-param>
        <param-name>data</param-name>
        <param-value>/var/cogix</param-value>
      </init-param>
      <init-param>
        <param-name>license</param-name>
        <param-value>type=unlimited;exp=...rest of the license key</param-value>
      </init-param>
... more init-param elements ...
<load-on-startup>1</load-on-startup>
</servlet>
If any changes have been made to web.xml, weblogic.xml, or portlet.xml (in portals only), make an archival copy of the changed files and repack the ViewsFlash.war file using the Java JAR utility. The archived files will be needed when upgrading ViewsFlash to new versions. For detailed instructions on how to unpack and repack the ViewsFlash.war file, see Modifying the ViewsFlash.war file.
Weblogic users only: review and modify, if appropriate, the WEB-INF\weblogic.xml file.
Note that If servlet parameters specify that ViewsFlash is running on a database, ViewsFlash can be deployed as a war file. If they do not, ViewsFlash must be deployed as an exploded war file.
Deploy the ViewsFlash.war file in the application server as a Web Application. Once installation is complete, start the application in your application server.

Print this page and use the following worksheet to gather all needed information in one place.

ViewsFlash servlet parameters for a typical production configuration, using a database and application security:

Parameter	Fill with	Examples	Value to use
data=	Directory for ViewsFlash data. This parameter is required.	/etc/cogix/data /var/cogix C:/etc/cogix/data
license=	Get a license key from Cogix. Can be added after initial deployment. ViewsFlash 5 requires license keys in a new format.	license=....
datasource=	JNDI name of data source	mysource java:comp/env/jdbc/mysource
If using application security:
appsecurity=	user	user
administrators=	User ID's and roles of ViewsFlash application administrators	jmacarthy,@ViewsFlashAdministrator
If not using application security:
adminpw=	A password to identify the application administrator.	p@ssw0rd

Post deployment configuration and troubleshooting

It is very important to verify correct installation before proceeding. Check all of the following:
The application server's administrative console should show that the application started successfully.
Look for "ViewsFlash" in the application server logs. There should be no error messages.
Look for a file "viewsflash.log" in the directory specified in the data parameter. There should be no error messages in this log.
Typically, error messages in any of the above will be caused, most often, by database connectivity or permissions.

If any errors are found, stop the ViewsFlash application, modify parameters or adjust application server settings as required, and start the ViewsFlash application again.
Once no errors are found in the logs, go to one of these two URLs:

If application security is enabled with appsecurity=user, use this URL and log in:
http://yourserver.com/ViewsFlash/servlet/vfadmin?Diagnose=1

If application security is not enabled, use this URL, and log in with the password provided in adminpw:
http://yourserver.com/ViewsFlash/servlet/viewsflash?Diagnose=1

If successful, the bottom of he diagnostic display should say:

Installation successful.
Click here to continue with Administration and Setup.

If there are error messages instead, correct them, restart the ViewsFlash application in the application server, and try the ?Diagnose=1 command again.
Once no errors are shown by Diagnose=1, click on the Administration and Setup link, and fill out the entries in the Administration page that follows.
The application is now installed.
Review all pages in the Default place and in the Default questionnaire and modify them if needed. For example, to make the default language direction right to left, unlock the Default questionnaire, modify the Language page, publish the Default questionnaire and lock it again.
If using User Security (appsecurity=user), the Administrator needs to become familiar with creating places and managing their Access Rights.

Next: Modifying the ViewsFlash.war file