Servlet Parameter Reference |
ViewsFlash is a web application. Some of its functionality is controlled by servlet parameters. These can be provided as init-param entries in its web.xml file, or in a viewsflash.properties file where they take the form name=value. The viewsflash.properties file is located at the location specified in web.xml, which is by default set to /etc/cogix/viewsflash.properties:
<init-param>
<param-name>propertiesfile</param-name>
<param-value>/etc/cogix/viewsflash.properties</param-value>
</init-param>
To modify web.xml, unpack the ViewsFlash.war file, modify web.xml, and repack the ViewsFlash.war file.
This section is divided into Commonly Used and Rarely Used sections. It's safe to avoid the latter section unless there's some unusual trouble that cannot be fixed by modifying the commonly used parameters.
| Required | See Installation |
| data | Directory where to store ViewsFlash files |
| license | Licensing Key. Without one, ViewsFlash will expire after 30 days, and each screen will include an "Evaluation Copy" message. Note that ViewsFlash 5 requires new license keys; older license keys will not work. Contact sales@cogix.com for a new key. |
| When running with a database using a data source | See Installation and Using a database |
| database | One of these: Oracle, Oracle9, Oracle10, Oracle11, DB2, MSSQL, MySQL |
| datasource | The name of a JNDI data source. |
| When using application security | See Application security |
| appsecurity | Usually appsecurity=user |
| administrators | A comma-separated list of user
IDs and roles; the roles are prefixed by an @ sign. If the logged in
user ID matches any of those on the list, or if the logged in user is in
any of the roles, they are granted the rights to access all portions of
the ViewsFlash application. Example: peter.ustinov,rhonda.fleming,@viewsflashusers |
| When running without a database | |
| backupdir | Directory where ViewsFlash stores *.bak files. For best performance, put it on the same drive as ViewsFlash, or turn this option off in the Administration page. Default is the data directory. |
| logpath | A directory for recording ViewsFlash logs. Default is the data directory. |
| txtpath | A directory for recording .txt files that capture votes or surveys, one entry per line. Default is the data directory. |
| votedir | A directory for storing temporary information during multi-page voting. Highly recommended under heavy loads. Default is the data directory. |
| logrequests | Set to 1 to log every http request to the ViewsFlash log. Set to 2 to also log every database access. Useful for debugging, but log can get very large. Default is 0. |
| strictinit | If set to 1, all servlet parameters are checked for correct spelling. If any are misspelled, the servlet will refuse to run with an UnavailableException. Default is 0. When using this, if you want to disable other servlet parameters, prefix them with a ~ and strictinit will regard them as valid, but will ignore them. |
| confirmwrite | If set to 1, whenever an .html file is written to the file system (such as a poll fragment), ViewsFlash will make sure the write succeeded. |
| Other application security techniques | |
| admintimeoutminutes | Passwords will need to be reentered after the given minutes. This guards against people who walk away from their computers while using ViewsFlash. Default is 60. |
| adminport | Port for administrative functions; should be behind a firewall for maximum protection. Default is no protection - any administration request can come on any port. |
| apiport | Port for inter-application communication. When used, the Web Services API commands are only available on this port, which should be behind a firewall for maximum protection. By default, this port is set to a non-existant port. |
| apiattribute | Attribute for inter-application communication. Web Services
API commands issued in JSP pages with a RequestDispatcher must set this attribute in
the HttpRequest to a Long value with the current time. Requests that are missing this attribute
will be denied. JSP pages provided by Cogix, such as i18n.jsp, expect this parameter to be set to: apiatttribute=com.cogix.vwf.api By default, this parameter is not set, and using the Web Services API from JSP pages is disabled. See How to use the Web Services API. |
| notifyport | In a Master/Satellite configuration, this port is used on the Master only and specifies the port to use to send synchronization messages to the Satellites. Default is 80. |
| securesurveyport | For questionnaires that specify use SSL, if a port other than the default 443 is desired, use this parameter |
| normalsurveyport | To use a port other than 80 for questionnaire URLs, use this parameter |
| adminpw | When not using Container Security, this parameter provides password to restrict access to the administrative functions. Each place can also have its own password. |
| extravulnerabilitychecks | When set to true, application page forms include an additional security token to validate that each form submitted is unique. Note that when using this parameter users cannot use the technique of opening up two application windows to work on different parts of the application at the same time. |
| On Satellite machines in a Master/Satellite Architecture only. In a Peer Architecture use Database Parameters instead. | |
| masterurl |
Required. The complete URL and port of the Master ViewsFlash server. E.g., http://yourcompany.com:8888/servlet/viewsflash If not present, then this server is the Master. |
| logpath | Required. A directory on the satellite's local file system for writing an Administrator log. Useful to see what's going on when Master goes down. |
| flushtime | Number of milliseconds in a poll after which the Master should be updated with the latest results from an active poll. Also used to flush database results. Default is 15000. |
| flushvotes | Number of votes in a poll after which the Master should be updated. Default is 1000. |
| flushsize | Number of bytes of untransmitted data in a poll after which the Master should be updated. Defaults is 50000. |
| refreshresultstime | When returning live results, current tallies are fetched from the Master. Specify here the number of milliseconds between refreshes. If not specified, the Satellite's results are not correct and you must redirect the visitor's browser with the history parameter to a page that uses the Web Services API to show the current results from the master. Redirecting is by far the most scalable approach. |
| Web Application parameters |
|
| webappname | When installed as a web application, normally ViewsFlash can guess its web application name automatically. If it does not, use this parameter to set it. /ViewsFlash is the normal name, except in WebSphere Portal. |
| appwebroot | Normally, ViewsFlash will automatically find the "document root" by discovering the location that corresponds to the URI "/". If this fails, set this parameter to that location. |
| usedefaultcharacterencoding | A few application servers (like Dynamo 7) interpret charset when receiving requests. If a questionnaire's Language page does not work, set this parameter to true to prevent ViewsFlash from decoding request parameters and form submissions. |
| Setup page parameters can be enterd as servlet parameters rather than entering them through the Setup page. |
|
| admin.name | ViewsFlash Administrator name |
| admn.emailto | His or her email address for receiving ViewsFlash emails |
| admin.emailfrom | His or her from email address to identify the messages |
| admin.emailreplyto | His or her reply-to address for receiving replies |
| admin.smtp.host | Host name for the smtp server that handles outgoing email |
| admin.smtp.username | If the smtp server requires authentication, provide the username |
| admin.smtp.password | and the password |
| admin.viewsflashapplicationurl | The URL for the ViewsFlash application. Specify only if the default value is incorrect. Example: http://www.yourcomany.com/ViewsFlash. |
| admin.viewsflashservleturl | The URL for the ViewsFlash servlet. Specify only if the default value is incorrect. To make this option visible in the Setup page, use the showadminservleturl=true servlet parameter. |
| admin.viewsflashsecureservleturl | The URL for the secure ViewsFlash servlet. Specify only if the default value is incorrect. To make this option visible in the Setup page, use the showadminservleturl=true servlet parameter. |
| admin.pollroot | When not using a database, the directory where HTML files should be written. Specify only if the default value is incorrect. Example: /opt/virtual/yourcompany/ViewsFlash |
| admin.usersendemail | Allows sending email. Default true. Set to false to disable. |
| admin.emailerroralerts | Notify administrator of error conditions by email. Default true. Set to false to disable. |
| admin.cookiedomain | Cookie domain for ViewsFlash cookies. |
| Environmental parameters |
|
| servletserver | Allows ViewsFlash to be named something other than /servlet/viewsflash. For example, if set to /cgi-bin/Polling, then you can use http://mycompany.com/cgi-bin/Polling/viewsflash. |
| servletpath | If the application server does not support getServletPath(), or if you are using 'servletserver' above, set this parameter to "viewsflash". (Very rare). |
| servletrequestinputstream | ViewsFlash versions before 3.0 parsed the servlet input stream, rather than using getParameterNames(). Set this parameter to "1" to revert to parsing the servlet input stream instead. |
| realpath | If the application server does not support ServletContext.getRealPath("/") in the HttpServlet.init() method, set this parameter to the equivalent of the hosting web server's root directory. Omit the trailing / or \. |
| referer | If the application server does not set the usual REFERER header, use this parameter to specify the name of the header that serves this purpose. (Very rare). |
| hostipaddress | Use this parameter to tell ViewsFlash its IP address. ViewsFlash normally determines the IP address of its machine by using getLocalHost(). Sometimes this returns 127.0.0.1, which is not useful. This is also useful when the machine has more than one IP address. |
| Database parameters | |
| notificationinterval | In a distributed database configuration, each instance checks for new events at this interval, in milliseconds. Default is 5,000. If not running in a distributed database configuration, you can set this value quite large (1000000 - one million) to reduce the load on the database a little bit. |
| instanceid | In a distributed database configuration, this parameter is used to identify each instance. If omitted, a random number is assigned. These instance ID's are used in the application logs to identify the instance that is writing to the log. You can assign a number on your own to make the log easier to read; note that if you do, it must be unique for each instance. Failure to make instanceid unique can result in inconsistent instances; for example, one instance could think that a poll is open, while another one doesn't. |
| storeflushtime | Number of milliseconds before saving a poll's tallied results to database. Default is 000 (no delay). |
| refreshresultstime | In a distributed database configuration, this parameter indicates how often to retrieve the current live results from the database. The default value is 3,000 milliseconds. A very small value will increase system load significantly. |
| dbmaxvarchar | The largest size of a VARCHAR type allowed. Default is 2000. If setting dbcharwidthmultiplier greater than 1, we recommend changing this to 4000. |
| dbcharwidthmultiplier | The maximum number of characters required to express one Unicode character. If the database will only store ISO-8859-1 characters, this value is 1 (the default). If the database must store other kinds of characters, we recommend setting this parameter to 3 to support the UTF8 character set and setting dbmaxvarchar (above) to 4000. |
| dbtablenameprefix | If present, this string will be prepended to the name of every table used by ViewsFlash. For example, COGIX. will use tables such as COGIX.VWFOBJECTS. Note that the trailing period must be entered explicitly. |
| dbcreatetablespacestatement | If present, this string contains a DDL CREATE TABLESPACE statement that is exectuted before creating a questionnaire's CREATE TABLE statement. It may contain the string %1, which is replaced by a 7 digit random number. Example: dbcreatetablespacestatement=CREATE TABLESPACE A%1 in VFD USING...(and other parameters, all on one line) used by ViewsFlash. For example, dbtablenamesuffix= IN MY.OBJECTS (note the space after the equal sign) will use tables such as VWFOBJECTS IN MY.OBJECTS. |
| dbcreatetablespacestatement | If present, this clause will be inserted after the table name in the DDL CREATE TABLE statement used to create a questionnaire's own table. Example:
dbcreatetablespacestatement= IN VFD.A%1 This parameter is often used with dbcreatetablespacestatement, above |
| database | Name of the Java class to use for database storage. Example: Oracle, Oracle9, Oracle10, MSSQL, MySQL, DB2. The actual class name is created by prepending "com.cogix.vwf" if not present, and appending "NamedDataSource" if the name does not include "DataSource". So, Oracle becomes com.cogix.vwf.OracleNamedDataSource. |
| databaseextension | Name of the Java class to use for writing responses to a single, normalized table. Example is OracleDatabaseExtension. By default, this parameter is assumed to be XXXDataBaseExtension,
where XXX is Oracle, MSSQL, etc. |
| normalizedtype | Some normalized database drivers use this parameter to specify what type to use for storing the data element, which is normally set to VARCHAR. |
| Saving data parameters | |
| save.text | Set to false to prohibit saving questionnaire data in the file system |
| save.table | Set to false to prohibit saving questionnaire data in its own database table. Use this when the database user should not be granted the right to create, alter and drop tables. |
| save.normalized | Set to false to prohibit saving questionnaire data in the common, normalized table VWFDATA. |
| Database error recovery parameters | |
| dbretryinterval | After a database failure, wait this number of milliseconds before retrying. Default is 30,000 milliseconds. |
| dbretries | After a database failure, retry this number of times. Each retry generates an error log entry and an administrator e-mail. Defaults is 100. |
| dbignorevendorcodes |
The dbignorevendorcodes parameter suppresses database retries for the specified database vendor error codes. Enter this parameter as a list of integers, separated by commas, omitting leading zeroes. For example, dbignorevendorcodes=1401 will disable retries for Oracle error code ORA-01401, caused by attempting to store a non-numeric value in a numeric field. |
| dbignoresqlstatecodes | The dbignoresqlstatecodes parameter suppresses database retries for the
specified 5 character standard XOpen SQLState codes. Enter this parameter
as a list of 5 character SQLState codes, separated by commas, including
leading zeroes. For example, dbignoresqlstatecodes=23000 will disable retries for XOpen SQLState code 23000 (Integrity constraint violation), a more generic form of ORA-01401. |
| Java Extensibility more info | |
| publishnotifierextension | Name of the Java class to invoke after a publishing change. Example is com.cogix.vwf.PublishNotifierExtension |
| votenotifierextension | Name of the Java class to invoke after a valid vote is cast. Example is com.cogix.vwf.VoteNotifierExtension |
| requestnotifierextension |
Name of the Java class to invoke after a request is scanned. Example is com.cogix.vwf.atgRequestNotifier This requires servlet API 2.2. If application fails to boot with a NoSuchMethod
exception, try disabling this parameter to nothing with: |
| webcasteventextension | Name of the Java class to invoke when a webcast poll or survey event happens. Example is com.cogix.vwf.WebCastEventExtension. |
| Miscellaneous | |
| errorinterval | Controls the interval, in seconds, used to calculate whether a repetitive log entry should be suppressed. |
| writehtmltodisk | When using a database, setting this option to 1 enables options in the place Settings page that allow writing HTML to disk. |
| webcast | Setting this option to 1 enables the Webcast features. |
| datareviewapi=true | Enables the data review and modification API. |
| appcharset=UTF-8 | Defines the application's default character set. Useful when the native
locale is not English. For example, GB2312 is useful in mainland China. appcharset=UTF-8 is the default |
| dbdatabaseconnectionclass | Deprecated: use database instead |
| dbservername | Deprecated: use datasource instead |
| polladjustment | Set to true to enable the legacy Options/Bulk Vote, Remove Entries, and Set Rank polling functions which are disabled by default as of ViewsFlash 6. |
| Staging parameters | |
| exportby,exportusersecurity, exportdir,importby,importdir |
See Staging |