If you are upgrading from an earlier version, see
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.
- 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
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:
||JNDI data source name
- (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.
<param-value>type=unlimited;exp=...rest of the license key</param-value>
... more init-param elements ...
- 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:
||Value to use
||Directory for ViewsFlash data.
This parameter is required.
||Get a license key from Cogix. Can be added after initial deployment.
ViewsFlash 5 requires license keys in a new format.
||JNDI name of data source
|If using application
||User ID's and roles of ViewsFlash application administrators
|If not using application security:
||A password to identify the application administrator.
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
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
- 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:
If application security is not enabled, use this URL, and log in with the
password provided in adminpw:
If successful, the bottom of he diagnostic display should say:
Click here to continue with Administration and
If there are error messages instead, correct them, restart the ViewsFlash
application in the application server, and try the ?Diagnose=1 command
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.
Modifying the ViewsFlash.war file