Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Section
Column
width0px

 

These steps are required when you convert from a demo/trial server installation to a production installation.

Tip

While you are demo-ing you do not need to do the Database Setup steps discussed below.

Your  server requires an SQL database for storing users and form submissions. The follow following SQL databases have been certified:

The server may function with other SQL database types but only the above set has been certified.

Warning
  • The default HSQLDB is ONLY sufficient for demo/trial versions of . All production users MUST switch their software to a production quality database.
  • You cannot migrate the data (user, roles, applications) automatically from HSQL to your production database. See this topic for the manual procedure details.

The following steps describe how to change the underlying database from the demo/trial HSQLDB to a production quality SQL database. The database configuration file frevvo.xml is located in <frevvo-home>/frevvo/tomcat/conf/Catalina/localhost directory.

Column
width240px

On This page:

Table of Contents
maxLevel1
 

Select your database type

...

Code Block
<!-- 
		HSQLDB Resource 
	<Parameter name="org.quartz.jobStore.driverDelegateClass" value="org.quartz.impl.jdbcjobstore.HSQLDBDelegate" override="false"/>	
	<Resource auth="Container"
		type="javax.sql.DataSource"
		name="jdbc/frevvoDS"
		driverClassName="org.hsqldb.jdbcDriver"
		username="sa"
		password=""
		url="jdbc:hsqldb:file:${catalina.home}/../data/db/forms"
		maxActive="200"
		maxIdle="20"
		maxWait="10000"
		validationQuery="select 1 from INFORMATION_SCHEMA.SYSTEM_USERS"
		testOnBorrow="true"
		testOnIdle="true"
		timeBetweenEvictionRunsMillis="10000"
		removeAbandoned="true"
		logAbandoned="true"/>
	
	<Parameter name="org.quartz.jobStore.driverDelegateClass" value="org.quartz.impl.jdbcjobstore.HSQLDBDelegate" override="false"/>	
	-->

Next, uncomment the pair of definitions for your database. Ex: if you are using SQL server, uncomment the definition for SQLSERVER Resource. Save the changes.

Code Block
  <!-- 
		SQLSERVER Resource
 -->		
	   <Parameter name="org.quartz.jobStore.driverDelegateClass" value="org.quartz.impl.jdbcjobstore.MSSQLDelegate" override="false"/>			
       <Resource auth="Container"
		maxActive="200"
		maxIdle="20"
		maxWait="10000"
		validationQuery="select 1"
		testOnBorrow="true"
		testOnIdle="true"
		timeBetweenEvictionRunsMillis="10000"
		removeAbandoned="true"
		logAbandoned="true"
		name="jdbc/frevvoDS"
		driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
		username="root"
		password=""
		type="javax.sql.DataSource"
		url="jdbc:sqlserver://localhost:1433;databaseName=frevvo;"/>
	
	<Parameter name="org.quartz.jobStore.driverDelegateClass" value="org.quartz.impl.jdbcjobstore.MSSQLDelegate" override="false"/>			
	
Note

There is now a parameter for org.quartz.jobStore.driverDelegateClass which is automatically configured for MySQL, SQL and Oracle databases. 

...

If the delegate property is explicitly set, it will override the automatic selection.

Configure the frevvo database

Note

The frevvo database below must be created with UTF-8 encoding.

For the frevvo your selected database type in frevvo.xml:

  1. Locate the frevvoDS data source url parameter :url=and decide on a name for the frevvo database. For the SQL Server it would look like this: "url="jdbc:sqlserver://localhost:1433;databaseName=frevvo". You can change the name "frevvo" to whatever you wish, "" for example. But it must match the database name you create in your SQL server. See verify configure the connection Url below.
  2. Create a UTF-8 encoded database "frevvo" (assuming you left the url parameter database name as the default) in your SQL server
  3. Set the frevvoDS data source url parameter to your database server. See configure the connection Url below.
  4. Set the frevvoDS data source parameters username and password password parameters to a user that has read and write permissions to the "" the frevvo database.
  5. The frevvo database setup is now complete.  will create all the necessary table upon tables upon startup.
Info

Where did the SQL scripts go? The server no longer needs the SQL scripts that used to be in <frevvo installdir>\frevvo\data\sql. The server automatically creates the necessary tables at first startup.

...

Configure the Connection Url

Configuration of the connection Url is key to successfully connect the  server to your database. Consult your DBA to assist with connection issues.

For the data source frevvoDS your selected database type in frevvo.xml:

1) verify that the "url" parameter is pointing to the correct Set the frevvoDS data source url parameter to your database server. If  and the database server are collocated "localhost" may be fine. The Url url parameters depend on the database type and installation choices made when your DBA installed your database software. Consult your DBA for the correct connection values. For example, SQL server installed on a non-default port and running on a machine named e00sca will require that you add a port number and host name to the Url. For example:

Code Block
<url>jdbc:jtdsurl="jdbc:sqlserver://e00sca:59377/frevvo</url>;databaseName=frevvo;"

As of SQL 2000, Microsoft SQL allows installation of multiple SQL named instances. If your SQL server was installed this way you must use the instance parameter. For example if you database instance was named xyzzy:

Code Block
<url>jdbc:jtds:url="jdbc:sqlserver://e00sca:59377/;databaseName=frevvo;instance=xyzzy</url>xyzzy"

2) Verify that the user and password required to connect to the frevvo database are correct.
3) Make sure that the user configured in the data sources has permissions to read and write to the frevvo databases.database.

Info

If you are using SQL Server, it is recommended that you append the sendStringParametersAsUnicode property with a value of false to your database connection URL. This property will improve performance. You can find more information about this property on this Microsoft website. If you do not see the property, when configuring the Connection URL to your database, add it.

Code Block
url="jdbc:sqlserver://localhost:1433;databaseName=frevvo;sendStringParametersAsUnicode=false"/> 

Non Standard Databases

If you are trying a different database type and do not see an example in frevvo.xml for  your for your database, you can create a new data source entry. Hibernate supports the following dialects however  has only been certified to run with a subset of these databases. For additional dialects see Hibernate documentation. 

...

Code Block
ALTER DATABASE frevvo CHARACTER SET utf8 COLLATE utf8_unicode_ci;
ALTER TABLE `frevvo16089`.`formsubmission` CHARACTER SET utf8 COLLATE utf8_unicode_ci; 

 

Install a JDBC Driver

's submission and user databases rely database relies on the JDBC API. You can use any relational database as long as you have a JDBC driver for that database, however. See the list of certified databases. If you choose a database that's not in this list you do so at your own risk.

...

The  download package comes with several pre-installed drivers. Look in <frevvo-home>/tomcat/lib and you will see (among other jar files) the following pre-installed driver jar files:

...

For example, the HSQLDB.jar file is located in WEB-INF/lib in the frevvo.war.

If you don't find what you need pre-installed you will need to locate a driver compatible to your database. Usually you can download your driver from the internet. Try one of these locations

...

The <frevvo-home>\tomcat\logs\frevvo.log file will report an error if you do not copy the JDBC driver to lib directory. The verbiage may differ depending on the driver and database. For example, the error for MySQL is "Cannot load JDBC driver class 'com.mysql.jdbc.Driver". Starting without the correct jdbc driver displays an HTTP 404 error. Coying Copying the correct jdbc driver to the <frevvo-home>/tomcat/lib directory should resolve the issue.

...

It is also appropriate to copy the driver into any location that is in the CLASSPATH of your servlet container. In a tomcat installation another location would be <CATALINA_HOME>/lib.

Changing the frevvo database naming and escaping conventions

In specific situations, your organization may require a certain naming convention for database objects (all uppercase, or at most 32 chars, or a specific name escaping convention) and the good news is that It is possible to change some of these parameters in  by setting a couple of specific web context parameters.

Note

However, the bad news is that this is not completely supported by at this point. The main reason is that we cannot guarantee that all the existing functionality that we test before each release will work correctly for a given database when any of these settings is changed.

Note also that the following settings affect only the frevvoDS database schema (and not the userDS schema) and that any changes to these settings will force  to create a schema that is different than the pre-generated scripts found in frevvo/data/sql/forms-*.sql when the schema is initially empty (you have to start from an empty schema).

How can you make sure that all database object names are uppercase or lowercase? You can affect this by  editing the frevvo/tomcat/conf/Catalina/localhost/frevvo.xml and adding the following parameter:

Code Block
<Parameter name="teneo.naming.strategy" value="uppercase" override="false" />

How can you make sure that all database object names have a max length (e.g. Oracle specifies a max of 32 chars)? You can affect this by  editing the frevvo/tomcat/conf/Catalina/localhost/frevvo.xml and adding the following parameter:

Code Block
<Parameter name="teneo.naming.max_sql_name_length" value="30" override="false" />

How can you specify a custom name escape character? You can affect this by  editing the frevvo/tomcat/conf/Catalina/localhost/frevvo.xml and adding the following parameter:

Code Block
<Parameter name="teneo.naming.sql_name_escape_character" value="" override="false" />

 

Moving the forms database

Note

Typically you should not need to move the forms database as these instructions only apply to 's built-in HSQLDB which should not be used for production use.

This information applies ONLY to the pre-installed demo database HSQLDB. When using the  tomcat bundle installation and the default configuration settings, the forms and users database is written to the <frevvo-home>\data\db directory. You may wish to locate the databases outside of <frevvo-home>. To do this:

  1. Edit <frevvo-home>\tomcat\conf\Catalina\localhost\frevvo.xml
  2. You will see two data source definitions for each database type. jdbc/frevvoDS is the form submissions database. jdbc/usersDS is for the user database.
  3. Configure the HSQLDB jdbc/frevvoDS Resource
  4. Change url="jdbc:hsqldb:file:${catalina.home}/../data/db/forms" to an absolute directory e.g. url="jdbc:hsqldb:file:c:\tmp\frevvo-data\forms"
  5. Configure the HSQLDB jdbc/userDS Resource
  6. Change url="jdbc:hsqldb:file:${catalina.home}/../data/db/users" to an absolute directory e.g. url="jdbc:hsqldb:file:c:\tmp\frevvo-data\users"
Note

Failure to configure this resource correctly will cause issues trying to create new forms, view submissions and submit forms.

 

...

Transferring Your frevvo Data from HSQL to a Production Database

The bundle includes an HSQL embedded database. If you use the HSQL database during your trial period, you cannot migrate the data (user, roles, applications) automatically from HSQL to your production database. Once your production database is in place, you must manually: 

  1. Create the tenants.
  2. Use bulk transfer of users to move your users/roles to the tenant.
  3. Download and upload the applications from designer user accounts in the trial database to the designer users in the new database.