Servlet Parameter Reference |
ViewsFlash is a J2EE 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>
Servlet parameters can also be specified in the web.xml file, like this:
<init-param>
<param-name>name</param-name>
<param-value>value</param-value>
</init-param>
When deploying ViewsFlash in a distributed configuration, it is preferable to put all parameters in web.xml.
To modify web.xml, unpack the ViewsFlash.war file, modify web.xml, and repack the ViewsFlash.war file. The "jar" Java utility can be used for this purpose.
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 Cogix 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. |
| 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. |
| 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 |
| mail. | In addition, any parameters that start with "mail." will be used to initialize the JavaMail session for the smtp server. Example: mail.smpt.auth can be used when the mail server requires authentication. |
| 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. This can be useful when the ViewsFlash application runs behind a proxy server that translates URLs to internal URLs and the public servlet URL needs to be different. This option requires the showadminservleturl=true servlet parameter. |
| admin.viewsflashsecureservleturl | The URL for the secure ViewsFlash servlet. Specify only if the default value is incorrect. This option requires the showadminservleturl=true servlet parameter. |
| showadminservleturl | Set this parameter to true to make additional fields in the Administration visible and editable. Use this option when the ViewsFlash URLs are incorrect. Normally, quesionnaire URLs are the same as the application URL. When this parameter is used, questionnaire URLs are generated from the settings in the Administration page instead. When using a reverse proxy server, this option allows for the ViewsFlash application to work at a different URL and port. When the entire server runs only on https, use this parameter and configure the application Setup page URLs to use https. |
| usingsslproxy | Setting this parameter to true prevents the generation of certain HTTP headers that interfere with downloading files and reports in IE6. |
| 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 | |
| dbstores | Use dbstores=all to store questionnaire definitions, logs and other data on the database. Omiting this parameter will write the ViewsFlash logs to the file system, either in the data directory as viewsflash.log, or to the directory specified in the logpath parameter. |
| 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). |
| purge | Number of days after which unused .vote records, which are created when a questionnaire is partially filled out but not completed, are removed from the vwfobjects table. Default value is 0, which disables purging. |
| noreports | Set to true to disable reports on this server. A separate server without this setting will create reports in the background. |
| 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 must contain a CREATE TABLESPACE statement that is exectuted before executing a questionnaire's CREATE TABLE statement.
It can contain the string %1, which is replaced by a 7 digit random number. Examples: dbcreatetablespacestatement=CREATE TABLESPACE A%1 in MYPARTITION USING...(and other parameters, all on one line) will produce CREATE TABLESPACE A12345 IN MYPARTITION USING ... Do not use this parameter if using the same partition for all data tables; precreate the table space manually. In either case, use dbtablenamesuffix as described below to assign the table to a tablespace. |
| dbtablenamesuffix | If present, this clause will be inserted after the CREATE TABLE statement used to create a questionnaire's own table. Examples: dbtablenamesuffix=IN VFD.A%1 will produce CREATE TABLE xxxx (...) IN VFD.A12345 dbtablenamesuffix=IN MYTABLESPACE will produce CREATE TABLE xxxx (...) IN MYTABLESPACE |
| 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. |
| upload.maxsize | Specifies the maximum size of an uploaded document. The default value is 10,000,000. |
| upload.strictfilename | Specifies what characters are allowed in uploaded files. The default value is 1, which allows only letters, numbers, space, underscore and dash. A value of 0 makes does not allow file names that contain spaces. A value of 2 allows most characters, including Unicode, but still prevents these characters: \/:*"<>|~&?* |
| uploadtimeout | Specifies how long an upload form remains active, in minutes. The default is 5. |
| upload.directory | Points to a directory where the ViewsFlash application server has been granted file creation, directory creation, and read, write and delete access rights. In a single-server deployment, any directory can be used. In a clustered deployment, this directory must reside on a shared volume, so that attachments gathered from all servers are stored in the same directory and can be accessed by all nodes in the cluster. If this parameter is omitted, a subdirectory of the data directory is used. |
| 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 |