Installing ViewsFlash

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 self-contained setup.exe Windows evaluation download, see these instructions.

For how to deploy the Cogix Survey portlet in WebSphere, Weblogic, Sun, 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.

Installation summary:

• 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

1. 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.
2. 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.
3. 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.
4. (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.
   
5. (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
   JRun	MyDB	MyDB
   Tomcat 5.5, 6	jdbc/MyDB	java:comp/env/jdbc/MyDB
   JBoss	MyDB	java:/MyDB

6. (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.
7. The Servlet Parameter Reference section explains less commonly used parameters.
8. 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>
   
9. 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.
10. 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.
11. 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. You can also use this sample viewsflash.properties file.

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

Post deployment configuration and troubleshooting

1. 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.
2. 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.
   
   PORTAL USERS: If you are using a portal, specially WebSphere, the ViewsFlash application URL may different. Go into the portal, install the Survey portlet, log in as a survey portlet administrator, and go to the Configure mode, and click on the Survey Setup link. This will open up a window where you can enter the Diagnose command. Bookmark that page for easy access.
3. The application is now installed.
4. 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.
5. 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