Documentation

Contents

FOXopen Reference

We have provided the following downloads to help you learn and use FOXopen to create your own systems. Included is a training manual along with example FOX modules, reference manuals for all FOX commands and attributes, a set of files to help make a FOXopen system and Schematron files to help develop FOXopen modules using an XML IDE.

Reference Guides

Training Sheets

Business Process Training Sheets

Utilities


FOXopen Deployment & Set-Up

The steps below apply to version 4 of FOXopen. Instructions for version 5 are on our GitHub wiki

Introduction

This guide will take you through the FOXopen installation process, step-by-step, for a variety of environments.

You must take the following steps to install FOXopen. The key actions which must be performed at each step are also shown. Details are provided below. Before you begin, ensure you have downloaded the desired version of FOXopen from the SourceForge site. This guide pertains to the latest version.

  1. Set up an environment
  2. Deploy the FOXopen engine
    • Place the provided endorsed directory into the correct location (depending on application server).
    • Deploy the WAR file, setting the desired web context (recommended: 'engfxo')
    • Allocate at least 1GB of memory to the FOXopen engine.
  3. Set up the FOXopen database
    • Create tablespaces.
    • Use datapump to import the pre-built database.
    • Finalise the installation.
  4. Configure the resource master
    • Set the correct connect string for the FXO database.
  5. Configure the FOX engine
    • Generate an encryption key and save a copy.
    • Set the correct database connect string, username and password.
    • Set an internal password.
  6. Log in
  7. Customise the installation

Environment setup

FOXopen requires a Java Servlet 2.5 compliant application server (i.e. Apache Tomcat) running on Java 6 and Oracle database version 11.2.0.3 or above (Standard/Enterprise). These must both be installed and configured in your environment prior to the deployment of FOXopen.

Note: FOXopen has only been tested on fresh installations of Oracle database. Installing FOXopen on a pre-existing database may result in issues such as naming conflicts and is not recommended.

Hardware/OS

The minimum specification for one combined server (running the application server and database) is as follows:

Install Software

Note: FOXopen is available in for both Oracle Standard and Enterpise editions. Two separate datapump files are provided in the installation archive. Use the Enterprise edition if you require the FOXopen Spatial functionality.

Before installing FOXopen, the following software must also be installed and configured:

  1. Oracle Database. Install one of the following Oracle Database Servers:
    • Install Oracle Database 11g Release 2 (version 11.2.0.3 or above) - Standard One, Standard or Enterprise (for Spatial)
    • It is recommended that the latest available PSU from Oracle is applied.
    • The database character set should be AL32UTF8, and national character set AL16UTF16.
  2. Java Runtime Environment (JRE). FOXopen requires JRE version 6 or above. Your application server may require a later version, or a JDK to be installed (check the application server's documentation). Detect your JRE version and download the latest from the Oracle website.
  3. A Java Servlet 2.5 compliant (or above) application server. You may choose your own, but this guide only covers:
    • Apache Tomcat 6
    • Apache Tomcat 7 (recommended)
    • IBM Websphere Application Server 6
    • IBM Websphere Application Server 7
  4. For security reasons you should ensure your Java Runtime Environment and Application Server is upgraded to the latest available version.

Note that FOXopen has been tested and known to run on the following application servers:

Setup guides for all of these application servers are forthcoming.

App Server Setup and WAR Deployment

The FOXopen installation archive contains a directory called endorsed. This contains the XML APIs required for FOXopen to run. These files must be loaded by an application server's Class Loader before it loads any conflicting native classes. In order to achieve this, they need to be placed in an endorsed directory. See here for more information.

When the endorsed directory is in place, the provided WAR file can be deployed and configured.

If your application server is not listed here, please consult its documentation to establish where the endorsed directory should be placed, and how to deploy a WAR file. After deployment, this documentation assumes that your resulting web context containing FOXopen is called engfxo, but this is not a mandatory requirement.

IMPORTANT - Memory Requirements: It is highly recommended that JVM running FOXopen is allocated at least 1GB of memory, and ideally at least 1.5GB. Please consult the manual for your application server for guidance on how to increase the JVM's memory allocation.

Tomcat

  1. Install as per instructions provided by Apache. You may wish to change the default port from 8080 as this conflicts with the port Oracle uses to provide its HTTP interface.
  2. Set up the endorsed directory:
    • Tomcat 6 & 7: Create a directory called endorsed in Tomcat's installation root folder. Copy all the files from the supplied endorsed directory into this one.
  3. Restart Tomcat.
  4. Deploy the engfxo.war file by copying it to TOMCAT_ROOT\webapps. You can also use the Tomcat HTML manager console to deploy the WAR. If you do this, ensure you specify the Context Path as /engfxo. This document later assumes that FOXopen is running as this context.

IBM Websphere 7.0.0.9

  1. Navigate to WEBSPHERE_INSTALL_DIR/WebSphere/AppServer/java/jre/lib/endorsed and copy the contents of the supplied endorsed directory into this one.
  2. Go to the Integrated Solutions Console and log in (http://server-location:9043/ibm/console/login.do).
  3. Expand the Applications section on the left hand menu and click on New Application to choose a new Enterprise Application.
  4. Browse to the WAR file location either locally or remotely.
  5. Click next to get to the configuration options choosing the default selected Fast Path.
  6. Click next to keep the defaults on the first stage.
  7. Check the select box for the WAR in steps 2 and 3.
  8. On Stage 4, set the context root to /engfxo. Note that the preceding slash is required!
  9. Click Finish to install the application and click Save when the link appears.
  10. Go to the Applications section on the left hand menu, expand Application Types to click on WebSphere enterprise application
  11. Select the application you created (engfxo) and click Start if isn't running already.

IBM Websphere 6.1

  1. Go to the Integrated Solutions Console and log in (http://server-location:9060/ibm/console/login.do).
  2. Expand the Applications section on the left hand menu and click on Enterprise Applications.
  3. Click the Install button.
  4. Browse to the WAR file location either locally or remotely.
  5. Set the context root to /engfxo. Note that the preceding slash is required!
  6. Click Next to get to the Configuration Options
  7. Keep the default options on the first page, but check the select box for the WAR in steps 2 and 3.
  8. Click Finish to install the application and click Save when the link appears.
  9. Once installed, go back to the Enterprise Applications list and click on the new application.
  10. Click on Class loading and update detection in the Detail Properties section and select Classes loaded with application class loader first as the Class loader order and Save changes.
  11. Navigate to the directory on the file system to which WebSphere deployed the WAR file (locate this by searching the WebSphere install directory for a directory called engfxo.war). From here, go to engfxo.war/WEB-INF/lib.
  12. Copy all 4 files from the supplied endorsed directory into this one.
  13. Move the file classes12.jar from the FOXopen lib directory into the following location: WEBSPHERE_INSTALL_DIR/WebSphere/AppServer/lib/endorsed.
  14. Restart the WebSphere service.
    • In Windows (as admin): Start, Run, services.msc, right-click IBM WebSphere and click Restart.
    • In Linux (as a privileged user): enter service websphere stop. Wait for confirmation, then enter: service websphere start.
  15. Log back in to the Integrate Solutions Console.
  16. Go back to the Enterprise Applications list and select the application you created and click Start.

Note: The default port for an application running on WebSphere is 9060.

Create Database

The database should have already been setup as described above.

Initialisation Parameters

FOXopen has been tested with the following database parameters, although there should not be any issues if the defaults are used: 

plsql_code_type                      string   NATIVE
plsql_optimize_level                 integer  3
optimizer_capture_sql_plan_baselines boolean  TRUE
optimizer_features_enable            string   11.2.0.3
optimizer_secure_view_merging        boolean  FALSE
optimizer_use_sql_plan_baselines     boolean  TRUE
compatible                           string   11.2.0.3.0

Tablespaces

Create tablespaces with the following commands (or equivalent): 

ALTER SYSTEM SET db_create_file_dest='...' SCOPE=BOTH
/
 
CREATE TABLESPACE NOACCESS
/
CREATE TABLESPACE SAVEDTABLES
/
CREATE TABLESPACE TBSBLOB
/
CREATE TABLESPACE TBSCLOB
/
CREATE TABLESPACE TBSDATA
/
CREATE TABLESPACE TBSIDX
/

For Enterprise Edition the following are also required: 

CREATE TABLESPACE TBSGEODATA
/
CREATE TABLESPACE TBSGEOIDX
/

Import FOXopen

Copy foxref-standard.dmp or foxref-enterprise.dmp from the FOXopen installation archive to a suitable Oracle Directory. The default if not specified is DATA_PUMP_DIR; to find its location: 

SELECT directory_path
FROM   dba_directories
WHERE  directory_name = 'DATA_PUMP_DIR';

Next perform an import of the file: 

impdp system DUMPFILE=foxref.dmp KEEP_MASTER=NO LOGFILE=foxref.log FULL=YES

Check the resulting log file for any errors. A number of "ORA-39082: Object type ... created with compilation warnings" errors are expected at this stage.

Make grants to the new schemas on certain system packages: 

GRANT EXECUTE ON sys.dbms_alert TO securemgr
/
GRANT EXECUTE ON sys.dbms_crypto TO portalmgr, securemgr
/
GRANT EXECUTE ON sys.dbms_flashback TO reportmgr, xviewmgr
/
GRANT EXECUTE ON sys.dbms_lock TO appenv, bpmmgr, decmgr, portalmgr, xviewmgr
/
GRANT EXECUTE ON sys.dbms_monitor TO foxmgr
/
GRANT SELECT ON sys.dba_objects TO savemgr
/
GRANT SELECT ON sys.dba_source TO bpmmgr
/
GRANT SELECT ON sys.dba_tables TO savemgr
/
GRANT SELECT ON sys.v_$database TO reportmgr
/
GRANT SELECT ON sys.v_$instance TO foxmgr
/
GRANT SELECT ON sys.v_$mystat TO foxmgr
/
GRANT SELECT ON sys.v_$parameter TO foxmgr
/
GRANT SELECT ON sys.v_$process TO foxmgr
/
GRANT SELECT ON sys.v_$session TO foxmgr
/

Additionally for Enterprise Edition: 

GRANT EXECUTE ON sys.dbms_alert TO spatialmgr
/
GRANT INSERT ON mdsys.sdo_coord_axes TO spatialmgr
/
GRANT INSERT ON mdsys.sdo_coord_ref_system TO spatialmgr
/
GRANT INSERT ON mdsys.sdo_coord_sys TO spatialmgr
/

Recompile all code: 

SQL> @?/rdbms/admin/utlrp

Check that no objects are invalid: 

SELECT *
FROM   dba_objects
WHERE  STATUS != 'VALID'

Note that in Oracle Standard and Standard One Editions there may be invalid objects for the OLAP Option, even though it is only available for Enterprise Edition. To remove these objects, follow the instructions in Oracle Support articles 1362752.1 and 565773.1.

Configure the FOXopen Engine

The FOXopen Engine needs to be configured to allow it to connect to a database and retrieve its Resource Master document. The data entered in this stage will be encrypted with a 2048-bit RSA key and stored on the server's file system, in a subdirectory of the application server's USER HOME directory called '.fox'. To clear any settings entered in this step, you must remove this folder and restart the FOXopen engine.

For the purposes of this documentation, the FOX_URL is as follows:

http://<WEB_SERVER_ADDRESS>[:<PORT>]/<CONTEXT_PATH>/fox

Where:

For instance, FOX_URL/!LOGIN would be entered as:

http://<WEB_SERVER_ADDRESS>[:<PORT>]/<CONTEXT_PATH>/fox/!LOGIN

Logging In

Go to FOX_URL/!LOGIN.

On the login page, enter admin in the username and password fields. (note: This is a default login and is changed later)

Encryption Keys

You need to generate an encryption key with which to encrypt the configuration settings. You may either generate your own or have FOXopen generate one for you.

If you are generating your own 2048-bit RSA keys then go to FOX_URL/!SECURITY to enter the private key into the text area.

If you want keys generated for you then go to FOX_URL/!SECURITY/DEFAULT (case sensitive).
IMPORTANT: Copy all the text in the text area labeled 'Encryption Key' and save it into a local file for future re-configuration.

Click save to carry on.

Configuration

Go to FOX_URL/!CONFIGURE.

On this page, enter the following information for each field:

After clicking save FOXopen should display a page reading 'Saved configuration file!'

Status Check

The engine is now configured. You can check its status with the following steps:

Go to FOX_URL/!LOGIN and enter the new administrator username and password set in the previous step.

Go to FOX_URL/!STATUS after logging in successfully to verify that all configuration is complete and correct. If the RESOURCE MASTER displays as FAILED, this means the database connection could not be established. You will need to repeat the previous step and correct any errors.

Configure the Resource Master

The Resource Master is an XML document residing on the database from which the FOXopen engine retrieves most of its configuration information. At this point, the FOX Engine should have been configured with a database connection string so it is able to retrieve the Resource Master. Once the Resource Master is retrieved, the FOXopen engine will be able to configure its connection pool, retrieve and display modules, and generate documents.

The Resource Master is located in foxmgr.fox_resource_master. It is in the DATA column of the row with the name resource_master.

Server Groups

NOTE: The default settings in this part of the Resource Master will be sufficient to enable FOXopen to generate documents.

The Resource Master defines Server Groups (within the server-group-list element). A default installation of FOXopen provides one server group - FXO-SERVER-DOC. This is used to define servers which are used for PDF Document Generation. The default installation assumes that FOXopen has been deployed to a single application server which will handle all relevant tasks.

A Document Generation Server Group contains a document-server sub-element. This specifies the database connection and application mnemonic for the document generator (discussed below).

Servers are assigned to a server group within the server-list element, which maps an application server by its IP address or hostname to a server group. You can specify an IP with wildcards in the server_select_wildcard_name_or_ip element, i.e. 192.168.*.*.

Database List

The default installation of FOXopen provides one database - FXO.

IMPORTANT: The connect-descriptor for this database MUST to be configured to allow FOXopen to connect to your database. By default it points to a service called 'xe' running on localhost.

To update the connect descriptor without using a GUI tool, you can use the following SQL statement: 

UPDATE foxmgr.fox_resource_master
SET data =
   UPDATEXML(
    XMLTYPE(data)
  , '/*/database-list/database/connect-descriptor/text()'
  , '(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=&hostname)(PORT=&port)))
     (CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=&servicename)))'
  ).getClobVal()
WHERE name = 'resource_master'
/

Connect List

The connect-list provides FOXopen with information about how to connect to the database (i.e. schema names and passwords). The connect-key of a connect is referenced by other parts of the Resource Master. Three connections are provided:

If you change the passwords to any of these schemas, you must also update them in the Resource Master.

Applications

FOXopen allows you to specify multiple applications for a given FOX Engine. These allow you to specify numerous settings for FOXopen at a high level, including module storage tables, virus scanning, file upload options, etc. Please refer to the FOXopen manual for more information.

Updating the Resource Master

It is recommended that you use a GUI client such as Toad to edit the XML in the Resource Master. Once you have made your changes, you may need to tell the FOXopen Engine to refresh its cached copy of the Resource Master. To do this:

  1. Go to FOX_URL/!LOGIN (see Configuration section for the definition of FOX_URL)
  2. Enter the admin username and password you configured and log in
  3. Go to FOX_URL/!LOADMASTER
  4. Go to FOX_URL/!FLUSH

Logging In

At this point, FOXopen is fully configured and ready to run. The setup script will have created an administrator user. This allows you to enter the system and assert that modules are loading correctly.

To log in:

  1. Go to FOX_URL/fxo/LOGIN001L
  2. For Login Id enter 'admin@foxopen.net'
  3. For Password enter 'password12'
  4. Click the Login button. You should now see the Workbasket screen with a menu on the left-hand side.
  5. Click Contacts / Teams on the left-hand side menu.
  6. Select Directory DTI Super Users from the dropdown and click Search.
  7. In the table that appears, click Edit Resource.
  8. You can update this team to give your admin@foxopen.net user more privileges on the system. For more information, see the FOXopen manual.

If you experience FOXopen failing to load pages because of XML parsing errors as you try and perform these steps, it is likely you have not correctly set up your endorsed directory. Please consult the earlier part of this document which explains where you should place the endorsed directory within your application server.

Our website uses cookies. For more information or to opt out, see our cookie policy. This message will only be shown once. x