Installation and Deployment

Let us discuss the basics of getting started with eXFORMA including the installation and configuration of your eXFORMA software. Topics for this chapter include:

  • Requirements Checklist
  • Installing and Configuring the Database
  • Installing eXFORMA
  • Configuring eXFORMA and you application server (JBoss or Weblogic)  within your network

To complete an eXFORMA installation you will require the following:

  1. Database export file or Database Scripts (provided by GroveWare)
  2. Server Hardware (Database and App Server can be on same or separate machines)
  3. eXFORMA Install Files
  4. Java JDK or JRE version + (eXFORMA can run on JDK 1.5, but some features require JDK 1.6 to support)
  5. Administrative access to both application server and database.

This document assumes that Java is already installed and preconfigured on the hosting hardware or that the Administrator capable of installing and configuring Java. However, to make things easier for clients GroveWare packages JDK.1.6.0_29 (for Windows, or 1.6.0_34 for Linux) with all of its install files.

This guide provides only details relating to the installation or restoring of the database and the installation and configuration of eXFORMA.

Installing/Restoring the Database

Depending on whether or not you’re installing a brand new instance or migrating an existing instance of eXFORMA from a GroveWare demo your instructions for configuring the database will be different.

In a typical situation GroveWare may have already generated your forms, uploaded users and configured workflow and reports within our own development environment. There is a working version of the application but it is being hosted temporarily on one of GroveWare’s development servers and now it’s time to bring the application ‘in house’. There are two options in this situation, GroveWare can export the forms, workflow and reporting templates in separate files. These files can be re-imported through the eXFORMA interface, but in most cases especially with workflow, they will need re-configuration to work within a new environment. The second option is GroveWare can provide a complete Database Extract which can then be imported directly within the new hosting environment without any additional configuration.

Migrating an Existing Database Instance

This option is the choice of most clients, based on its simplicity and the lack of additional configurations required to get the application up and running.

The exact steps to migrate an existing database instance can vary by database type but the general idea is the same for each. GroveWare recommends using the import/export function associated with most database management tools. This can be done by using the import/export option within most tools and then locating the export file (.SQL, .MDF, .DMP, etc.) provided to you by GroveWare. The tool will do all of the work, GroveWare will provide a check file for comparison with the total number of tables, and records.

Installing a New Database Instance

In some cases users may want to install their own clean version of eXFORMA for training or development purposes. GroveWare can provide a series of scripts for creating a new database. Scripts are available for MySQL, MSSQL, and Oracle. These scripts will create a new base instance of the eXFORMA database and provide two user accounts, an Administrator account called ‘root’ and an End-User account called ‘user’. For more information about using scripts and run sequences review the ‘read me’ file which accompanies the script package.

Installing eXFORMA and JBoss

Like with the database there are two options when it comes to installing eXFORMA and JBoss; migrating an existing instance or installing a new one. Which option you choose will depend on the situation. If GroveWare has already done some development work for you then migrating an existing instance is the only way to retain the configuration and not have to do it all over again. If you just want to install a basic package, then the default version of eXFORMA provided in the install package is the other way to proceed.

Note: eXFORMA requires the disabling of User Access Controls (UAC) and Administrator Access when installing on Windows Server 2008 R2. For more information and instructions for disabling UAC please read section 2.3 User Access Control.

Migrating an Existing eXFORMA Instance

GroveWare will provide a .ZIP package which contains a folder called eXFORMA. Extract the folder and copy the contents to the installation folder path of your choosing. GroveWare usually recommends c:\GroveWare or c:\eXFORMA as a suggested file path. The application was “pre-installed” so all of the folders have been set-up and pre-extracted so at this point the installation part of the process is complete. We can now move on to configuring the application for proper use.

Installing a New Instance of eXFORMA

To install a new instance of eXFORMA locate and run setup.exe in the install package provided. This install wizard will walk you through the process of extracting and installing the eXFORMA application. Just follow the prompts on the screen and provide the information required. The install wizard will take care of many of the configurations as well so you may be able to skip some of the topics in the next section.

User Access Control

To run JBoss normally when installing on Windows Server 2008 R2, it is necessary to disable User Account Control (UAC). Instructions are as follows:

  1. Open the Local Security Policy (Start -> Administrative Tools -> Local Security Policy)
  2. Expand the Local Polices folder
  3. Click on the Security Options folder
  4. Scroll down, and locate the family of settings beginning with ‘User Account Control’
  5. Focus on: User Account Control: Behavior of the elevation prompt for administrator.  Double click and set to: Elevate without prompting.
  6. Restart you Windows Server 2008R2 computer.
  7. Install and Run the eXFORMA application with Administrator’s rights.

Configuring eXFORMA and JBoss

Now that eXFORMA and JBoss are installed there are some configurations that need to be completed to ensure the application runs correctly. These configurations include:

  • Connecting eXFORMA to the Database
  • Configuring eXFORMA and JBoss run ports and Firewall Requirements
  • Configuring eXFORMA and JBoss for SSL/HTTPS
  • Securing JMX and Web Consoles
  • Setting Environment Variables
  • Installing the License File
  • Installing the eXFORMA Service

Connecting eXFORMA to the Database

In the folder \eXFORMA\jboss-4.0.5.GA\server\default\deploy\ there will be a file called oracle-ds.xml, mysql-ds.xml or mssql-ds.xml depending on the database you are using. This is the datasource configuration file for the application. Open this file in an editor and adjust it appropriately for your environment. Specifically, the fields for <connection-url>, <username> and <password> to access the database need to be updated.

Configuring eXFORMA and JBoss Ports – Firewall Requirements

Traffic is always initiated by clients from WAN or the Internet on ports TCP/80, and TCP/443. Network firewalls only allow TCP/80 and TCP/443 to the web front-end/application server virtual IP address. JBOSS SSL wrapper listens for traffic on port TCP/8443 by default. Therefore, in addition to port filtering on TCP/80 and TCP/443, hosting firewalls should also redirect all TCP/443 to TCP/8443. Traffic between the web front-end and the back-end database will flow through the standard JDBC ports, i.e. TCP/1433, TCP/1521, or TCP/3306.

To change the default ports for eXFORMA and JBoss locate the file server.xml in the install folder under …\eXFORMA\jboss-4.0.5.GA\server\default\deploy\jbossweb-tomcat55.sar\. Open the file server.xml and locate the following section of code near the top:

<Service name="jboss.web" className="org.jboss.web.tomcat.tc5.StandardService">
 <!-- A HTTP/1.1 Connector on port 8080 -->
<Connector port="8080" address="${jboss.bind.address}" maxThreads="250" strategy="ms" maxHttpHeaderSize="8192"  emptySessionPath="true" enableLookups="false" redirectPort="8443" acceptCount="100"  connectionTimeout="20000" disableUploadTimeout="true"/>

Simply adjust the “bolded/highlighted” code to configure JBoss to run on a different port and then restart eXFORMA.


In the tomcat folder, edit server.xml and comment out the HTTP Connector which displays the port (usually 80 or 8080). If you comment out this section, the HTTP access will be disabled and the only connector available will be the SSL connector (which is just below the HTTP connector section).

For HTTPS you also require an SSL key file called server.keystore.

Securing the JMX and Web Consoles

Both the jmx-console and web-console are standard servlet 2.3 deployments and can be secured using J2EE role-based security. Both also have a skeleton setup to allow one to easily enable security using username/password/role mappings found in the jmx-console.war and web-console.war deployments in the corresponding WEB-INF/classes and files.

The security setup is based on two pieces, the standard WEB-INF/web.xml servlet URI-to-role specification and the WEB-INF/jboss-web.xml specification of the JAAS configuration which defines how authentication and role mapping is performed.

To secure the JMX Console using a username/password file

  • Locate the jmx-console.war directory. This will normally be in the default/deploy directory.
  • Edit WEB-INF/web.xml and uncomment the security-constraint block.
  • Edit server/default/conf/props/ and server/default/conf/props/ and change the users and passwords to what you desire. The format for this is (username=password) and (username = roles).They will need the JBossAdmin role specified in the web.xml file to run the JMX Console.
  • Edit WEB-INF/jboss-web.xml and uncomment the security-domain block. The security-domain value of jmx-console maps is declared in the login-config.xml JAAS configuration file which defines how authentication and authorization is done.

To secure the Web Console

The process to secure the web console is similar to securing the JMX console. In the default/deploy directory of your JBoss eXFORMA installation, locate management/web-console.war and make the same changes as above to WEB-INF/web.xml, WEB-INF/jboss-web.xml and the users/groups properties file.

Setting Environment Variables

eXFORMA needs three (3) environment variables to be set in the Windows environment. The three variables are EXFORMA_PREFS_HOME, JBOSS_HOME, and JAVA_HOME. The variables should be set to file paths as follows:

EXFORMA_PREFS_HOME = the file path to find the ‘prefs’ folder in eforma home. ie.C:\GroveWare\eforma_home JBOSS_HOME = the file path to the root folder of JBoss ie. C:\GroveWare\jboss-4.0.5.GA JAVA_HOME = the file path to the folder containing bin\java.exe ie. C:\Java\jdk1.6.0_20

Installing the License File

The license file has likely been pre-installed for you by GroveWare as part of their pre-configuration. If it has not been installed or you encountered a problem the license key for the application can be found the folder ‘license’ found here ..\eforma_home\license. To update your license or to install a new one, simply replace the one found in license folder with the one provided to you by your GroveWare representative.

Running eXFORMA as a Service or in Console Mode

eXFORMA can be started in console mode by running the file run.bat found in the JBoss bin folder ..\jboss-4.0.5.GA\bin.

Optionally, eXFORMA can also be installed as a service and configured to launch automatically with Windows. Install the eXFORMA Service by launching the file %JBOSS_HOME%\bin\installService.bat. eXFORMA will then be available under Windows Services.

Installing and Configuring eXFORMA for WebLogic

This section highlights the steps necessary to deploy eXFORMA for WebLogic. It assumes that the datasource for eXFORMA is already created and configured.

Start by creating a new data source within the Oracle Application Server. This can be done by selecting the ‘JDBC’ node from ‘Services’ within the base_domain and then selecting ‘Data Sources’.

Click the ‘New” Button to create a new data source connection. Input a JDBC data source name and the JNDI Name you would like to assign to it.

Note: for pre-configuration purposes it is required that the JNDI Name be set to “jdbc/EFormaDS” as shown in the image below. Select the Database type.


Click ‘Next’ and then click ‘Next’ again. Input the connection string in the ‘Create a New JDBC Data Source’ page and click ‘Next’. Test the Data Source to make sure that it works then select ‘Finish’ to complete the Data Source configuration.

Click the data source you just created (ie. eformaDSOracle) and select the ‘Targets’ tab. Check the box ‘AdminServer’ and click “Save”


Configure Authentication Provider


A plug-in file for the authentication provider called ‘authentication-plugin.jar’ has been provided. Copy this file to the …\base_domain\lib folder.

Within the Oracle application server management console, select ‘Security Realms’ on left panel and click ‘myrealm’.


Select the ‘Providers’ tab.


Click the ‘new’ button to enter a new provider. Input a provider name and select ‘CustomDBMSAuthenticator’ in type dropdown list. Then click the ‘ok’ button.


Click the newly created provider (ie.- eformaDBAuth) and select ‘SUFFICIENT’ in  the ‘Control Flag’ dropdown list, then click the ‘Save’ button.

Select the ‘Provider Specific’ tab. Input the data source name created earlier and in the ‘Plugin Class Name’ field enter the following:  “com.GroveWare.common.appsrv.weblogic.DBMSAuthenticatorPlugin”

Then click ‘Save’ button.


Select DefaultAuthenticator, change its Control Flag from ‘REQUIRED’ to ‘SUFFICIENT’.


Select the ‘Messaging’ node under ‘Services’ in the left panel. Then select ‘JMS Servers’ on the right. Create a new JMS server (ie- eformaJMSSvr). Leave the ‘Persistent Store’ as ‘none’.  Configure its target as ‘AdminServer’.

Select ‘JMS Module’ from the ‘Messaging’ node. Create a new JMS System Module (ie. eformaJMSModule). Check ‘AdminServer’ as its target. Go into this newly created JMS System Module and create a new Subdeployment in the ‘Subdepolyments’ tab (ie. eformaJMS) and configure as shown below.


Create two Queue and one Topic JMS resource as shown in the picture below.


Restart the domain.

Contact Form Powered By :