Getting Started

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. Before you begin, ensure you have downloaded the desired version of FOXopen from the SourceForge site.

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. Run scripts
   • Change the value for DB_CREATE_FILE_DEST.
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 J2EE compliant application server (i.e. Apache Tomcat, IBM Websphere) and an Oracle database (version 10g or above). These must both be installed and configured in your environment prior to the deployment of FOXopen.

Note: FOXopen has only been tested on clean installations of Oracle 10g XE and Oracle 11g. Installing FOXopen on a non-clean database may result in issues such as naming conflicts and is not recommended.

Hardware/OS

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

• CPU: 2 GHz single-core Intel or AMD opteron Dual core 2 GHz 64 bit
• Disk space: 10 GB
• Memory: 2 GB
• OS: Windows, 2003/XP/Vista or Linux (Kernel 2.6 or later)

Install Software

Before installing FOXopen, make sure the following components are installed in the following order and working:

1. Oracle Database. Install one of the following Oracle Database Servers:
   • Oracle Database 10g Release 2
   • Oracle Server 10g: Express Edition
   • Oracle Database 11g Release 2
2. Java Virtual Machine. FOXopen requires JVM 1.4 or above. Your application server may require a later version, or a JDK to be installed (check the application server's documentation). Detect your JVM version and download the latest from here.
3. A J2EE 1.4 compliant (or above) application server. You may choose your own, but this guide only covers:
   • Apache Tomcat 5.5
   • Apache Tomcat 6
   • IBM Websphere Application Server 6
   • IBM Websphere Application Server 7

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

• Oracle Application Server 10g
• GlassFish 3
• Oracle WebLogic 10

Setup guides for 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.

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: Create a directory called endorsed in Tomcat's installation root folder. Copy all the files from the supplied endorsed directory into this. On Windows, by default, the Tomcat root folder is: C:\Program Files\Apache Software Foundation\Tomcat 6.0.
   • Tomcat 5.5: Navigate to TOMCAT_ROOT\common\endorsed, where TOMCAT_ROOT is Tomcat's installation root folder. Copy all the files from the supplied endorsed directory into this one.
3. Restart Tomcat.
   • Windows (admin): Start, Run, services.msc. Right click either Apache Tomcat 6 or Apache Tomcat and click Restart.
   • Linux (privileged user): enter service tomcat stop or service tomcat6 stop (depending on your version). Wait for confirmation, then enter: service tomcat6 start or service tomcat start.
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.

Run Scripts

The FOXopen installation file contains 2 SQL scripts, FOXopen_Install_Part1.sql and FOXopen_Install_Part2.sql. These scripts will run all the necessary DDL and DML on the database to allow FOXopen to run.

The scripts are designed to be run using Oracle's SQL*Plus. They may require alterations if you wish to run them with a different client. SQL*Plus will exit immediately if it encounters an error running any statement.

You must run the scripts as SYS, connected as SYSDBA. The following example shows how to run the script from SQL*Plus at the command line, with the output redirected to a file called output.txt (assuming your command line environment variables are set so the sqlplus executable can be located):

 sqlplus "sys/<password>@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=<hostname>)(PORT=<port>)))(CONNECT_DATA=(SERVICE_NAME=<service name>))) as sysdba" @FOXopen_Install_Part<num>.sql > output.txt
	

FOXopen_Install_Part1.sql

This script creates the necessary tablespaces and database schemas for FOXopen.

For convenience, the tablespaces created by the script will be automatically managed by Oracle. This may not be desirable in your environment. If this is the case, you should edit this file so that the tablespaces are given appropriate definitions.

After running this script, examine the output from SQL*Plus. The script will check that all users have been correctly granted their required roles and privileges and output warning messages if not. You should not proceed to running Part2 until Part1 runs with no errors.

FOXopen_Install_Part2.sql

This script will create all the required database objects for FOXopen. It also contains statements which insert various components which FOX requires to run. You do not need to edit this file.

The script will output a series of guidance messages when it completes. Examine these messages as you may need to make minor alterations to your database configuration to optimise it for FOXopen. In particular, by default FOXopen will create a large connection pool, which may exceed the number of simultaneous connections permitted by the processes system variable. This may result in you being unable to connect to the database whilst the FOXopen Engine is running. The script output advises how to alter the variable if necessary.

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 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:

• WEB_SERVER_ADDRESS is the address or hostname of the FOXopen server
• PORT is an OPTIONAL colon-prefixed port number
• CONTEXT_PATH is the context path specified while deploying the WAR file (or the name of the war file if when deploying there wasn't a context path option)

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 the characters/numbers from the image where it asks for it and admin into the login field. (note: This is a default password and is changed later)

If the CAPTCHA and password were both correct then a page with the text 'Login success.' will be displayed and you can continue. If 'Login failed.' is displayed then click the back button and try again.

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:

• Encryption Key - the 2048 bit encryption key from the previous screen.
• DB Connect String - An Oracle database connection string pointing to the desired database. I.e. (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=<hostname>)(PORT=1521)))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=<service name>)))
• Connect Key enter FXO/foxmgr. This is a reference to a connection defined in the Resource Master (see that section for more information).
• DB Username - enter 'foxmgr'. This is the schema which FOX will connect to initially.
• DB Password - enter the password for the previous schema. By default this is 'password'.
• Release Info - enter a desired server release i.e. '[development]'.
• Application Name - enter a desired application name i.e. 'FOXOPENr4.04.01'.
• Status - select Development or Production. This controls internal engine-wide settings such as Track size.
• FOX Service List leave this blank, or enter a comma-separated list of FOX services (see the FOXopen manual).
• Internal PW - enter the password for future use with !LOGIN (note: You can't keep this as admin)
• Confirm Internal PW - confirm the above password.

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 text in the CAPTCHA image and the new internal 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.

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:

• FXO/documents - a connection to decmgr (the schema which provides access to document generation). This is used by the FXO-SERVER-DOC server group.
• FXO/appenv - a connection to appenv (by default, the FOXopen module processing engine connects as this schema and runs all database access code through it).
• FXO/foxmgr - a connection to foxmgr (the FOXopen engine connects as this schema to retrieve its configuration information and access logging tables). You will have referenced this connection in the engine configuration stage.

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 password you configured and the CAPTCHA text.
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.

Customise the installation

A standard FOXopen installation is provided with a skeletal package for FOX User authentication - SECUREMGR.AUTHENTICATION. It is highly recommended that the package is edited to suit your needs. At the very least, it is recommended that you implement some form of encryption on the SECUREMGR.WEB_USER_ACCOUNT_HISTORIES table in order to conceal user's passwords. The simplest way to do this is to provide a full implementation for the function SECUREMGR.AUTHENTICATION.ENCRYPT_PASSWORD.

FOX requires the following subprograms in the AUTHENTICATION package. Further details are provided below:

• session_create
• session_verify
• session_end
• check_password
• encrypt_password
• generate_user_dom

You can override the package FOX uses for authentication by changing the <authentication-package> value in the FOX Resource Master, but you will also need to ensure that the SECUREMGR.REGISTRATION package correctly references your new authentication package.

Failing to provide a package which conforms to the stated specification will prevent any FOX pages from loading.

session_create

FUNCTION session_create(
	  p_origin_client_info IN VARCHAR2
	, p_application_display_name IN WEB_USER_SESSIONS.LAST_APPLICATION%TYPE
	, p_login_id IN WEB_USER_ACCOUNT_HISTORIES.LOGIN_ID%TYPE
	, p_password IN VARCHAR2
	, po_create_status OUT VARCHAR2
	, po_create_message OUT VARCHAR2
	) RETURN WEB_USER_SESSIONS.WUS_ID%TYPE;
	

The FOXopen engine uses this function to create a session when a user logs in using the fm:user-login command in a Fox Module. The engine will provide:

• p_origin_client_info - the IP address of the application server processing the request, and the IP address of the user, in this format: IP=<server ip>, REMOTE-ADDR=<client ip>.
• p_application_display_name - information about the app mnemonic and FOX module which has sent the request.
• p_login_id - the login ID (i.e. username) of the login attempt.
• p_password - the unencrypted password of the login attempt.

The FOXopen engine expects:

• po_create_status to be one of three values - VALID, INVALID or EXPIRED. Only a VALID session will log the user in to the FOXopen engine.
• po_create_message - a message provided for auditing purposes.
• The function to return a session ID.

session_verify

FUNCTION session_verify(
	  p_origin_client_info IN VARCHAR2
	, p_application_display_name IN WEB_USER_SESSIONS.LAST_APPLICATION%TYPE
	, p_session_id IN VARCHAR2
	, po_wua_id OUT WEB_USER_ACCOUNT_MASTER.WUA_ID%TYPE
	, po_verify_status OUT VARCHAR2 -- VALID, EXPIRED (+message), INVALID(+message)
	, po_verify_message OUT VARCHAR2
	, p_login_id IN VARCHAR2 DEFAULT NULL
	, p_password IN VARCHAR2 DEFAULT NULL
	, p_verify_user IN VARCHAR2 DEFAULT NULL
	) RETURN WEB_USER_SESSIONS.WUS_ID%TYPE
	

FOXopen will use this function to verify that the session identified by p_session_id is still valid. The engine provides:

• p_origin_client_info - the client info as for session_create.
• p_application_display_name - the application info as for session_create.
• p_session_id - the session ID which FOX is verifying.
• p_login_id - the login ID as for session_create.
• p_password - the password as for session_create
• p_verify_user - 'true' or 'false' (null = false) - indicates that FOX wishes the API to match the session to the provided login id and password.

FOXopen expects:

• po_wua_id - the WUA (Web User Account) ID associated with the login ID which is logged in to this session.
• po_verify_status - either VALID, INVALID or EXPIRED. INVALID or EXPIRED will cause FOX to un-authenticate the user.
• po_verify_message - a message for auditing purposes.
• The function to return the session ID of the verified session.

session_end

PROCEDURE session_end (
	  p_origin_client_info IN VARCHAR2
	, p_application_display_name IN WEB_USER_SESSIONS.LAST_APPLICATION%TYPE
	, p_instigating_wua_id IN WEB_USER_ACCOUNT_MASTER.WUA_ID%TYPE
	, p_wua_id IN WEB_USER_ACCOUNT_MASTER.WUA_ID%TYPE
	, p_session_id IN WEB_USER_SESSIONS.WUS_ID%TYPE
	, po_end_status OUT VARCHAR2
	, po_end_message OUT VARCHAR2
	)
	

The FOXopen engine will use this procedure to terminate a session when a FOX module calls the fm:user-logout command. It provides:

• p_origin_client_info - the client info as for session_create.
• p_application_display_name - the application info as for session_create.
• p_instigating_wua_id - the ID of the Web User Account which is attempting to close the session.
• p_wua_id - the ID of the Web User Account which is logged in with the session.
• p_session_id - the session ID which FOX is ending.

FOXopen expects:

• po_verify_status - either VALID or INVALID to indicated success or failure.
• po_verify_message - a message for auditing purposes.

encrypt_password

FUNCTION encrypt_password(
	  p_wua_id WEB_USER_ACCOUNT_MASTER.WUA_ID%TYPE
	, p_password VARCHAR2)
	RETURN VARCHAR2
	

This is not used by the Engine directly, but is used by other parts of the AUTHENTICATION package.

The function should return the encrypted form of the password provided in plain text by p_password for the Web User Account p_wua_id.

check_password

FUNCTION check_password(
	  p_wua_id WEB_USER_ACCOUNT_MASTER.WUA_ID%TYPE,
	  p_password VARCHAR2,
	  fail_on_retries BOOLEAN
	) RETURN BOOLEAN
	

This is not used by the Engine directly, but is used by other parts of the AUTHENTICATION package.

The function will return true if the plaintext password provided by p_password is correct for the given p_wua_id, and false otherwise. The fail_on_retries parameter can be used to optionally increment a "retry counter", locking the given account after a certain amount of failed verification attempts.

generate_user_dom

FUNCTION generate_user_dom(
	  p_session_id VARCHAR2
	, p_wua_id NUMBER DEFAULT null
	, p_csv_system_privs VARCHAR2
	, p_csv_urefs VARCHAR2
	, p_csv_uref_types VARCHAR2 --not used - legacy
	, p_csv_uref_privs VARCHAR2
	, po_csv_privs OUT VARCHAR2
	) RETURN XMLTYPE
	

The FOXopen engine will call this function when it needs to create the :{user} DOM; an internal DOM used by FOX to provide modules with information about the logged-in user. The engine provides the function with the following parameters:

• p_session_id - the session ID which it is using to generate the user DOM.
• p_wua_id - the WUA ID for the logged-in user. If this parameter is NULL, no user is logged in, and a DOM representing a guest user should be returned.
• p_csv_system_privs - a CSV list of system privileges, or '*' (representing all known system privileges). If the user has been granted these privileges, they should be returned as described below. See the documentation of the SECURITY subsystem for more information.
• p_csv_urefs - a CSV list of UREFs provided by the fm:security-scope command. See the command documentation for more information.
• p_csv_uref_types - a CSV list of UREF Types provided by the fm:security-scope command. See the command documentation for more information.
• p_csv_uref_privs - a CSV list of UREF privileges provided by the fm:security-scope command. See the command documentation for more information.

This function must return a valid XML DOM with a root element name of <USER>. It must also use po_csv_privs to return a CSV List of privileges which the given user or session has. These are used in evaluating the security rules defined in the <fm:security> section of FOX Modules. It is also highly recommended that those privileges appear in the DOM itself, as many modules provided by FOXopen will be reliant on their existence. Privileges should appear in the DOM in the following format:

 <USER>
	   ...
	   <PORTAL_PRIVILEGES>
	     <PRIVLEGE NAME="PRIVILEGE_NAME"/>
	     <PRIVLEGE NAME="PRIVILEGE_NAME"/>
	     ...
	   </PORTAL_PRIVILEGES>
	 </USER>
	

Note that this requirement is not validated by the FOX Engine.

The engine also requires that the DOM contain the following elements within the <USER> element:

• <WUA_ID> - the user's web user account ID
• <LOGIN_ID> - the user's web login ID (for auditing)
• <FULL_NAME> - the user's full name (for auditing)

FOXopen is an open source initiative donated by the UK's Department of Energy & Climate Change.
DECC have made FOXopen open source in line with UK government policy and with EU open source directives.