Steps for manually installing ESS Version 7

Thursday, May 5, 2013

Copyright 2006, 2013 R.James Holton, All rights reserved.

 

 

This process is used to install ESS from the ESS-7.nnn.zip on a Web, application and database server.

 

To run ESS, you need to have a functioning application server such as Tomcat.  You need to have a functioning database such as MySQL.  In addition, you'll probably want to have a functioning Web server such as Apache.  If you have a Web server, and this is the best, you will need a conduit between your Web server and your Application server such as mod_jk or use proxy_ajp to force Apache to act as a proxy for Tomcat.  This allows you to address the Application server folders through your Web server URL or IP. Don't panic if you don't have these installed yet. See note 1 below.

Expenseservices.com uses, and has tested ESS on Linux and Window's stacks consisting of  Apache2, Tomcat, MySQL and conduits (mod_jk and proxy_ajp).

 

Note 1: If you don't have a stack that will support ESS already on your server, the easiest way to install the components for review is to get a stack installer from BitNami.org. BitNami provides TomcatStack (http://bitnami.org/stack/tomcatstack) which has all the necessary components required by ESS. There is a separate document in this documentation that shows you how to install BitNami's TomcatStack so it will run with ESS.  TomcatStack uses Apache as a proxy for Tomcat so all applications are installed under Tomcat and there is minimum configuration required. Here are some procedures that will allow you to install the Tomcat BitNami stack.


Note 2: We no longer distribute, through SourceForge.net, the SQL scripts and configuration files for Oracle.  If you want these items, you should contact "service@expenseservices.com".  We currently are distributing MySQL and MS SQL Server configuration files via SourceForge.net. The MySQL files are an inherent part of the release. The MS SQL Server files are available in the resources/msssql folder.

 

Note 3: We’ve also run ESS on IIS, JRun, ODBC.  A goal in ESS coding was to make it non-environment specific.

Note 4: Currently ESS needs the "AddDefaultCharset ISO-8859-1" set in the Apache httpd.conf file.  We plan on changing to UTF in future releases.

 

If you don’t understand the previous paragraphs, you should seek technical support.  The manual installation of ESS is not “hard,” but it does require a good degree of familiarity with your Web, application and database servers.  The instructions below will require you to create a significant number of folders and links. 

 

Follow these steps to install ESS once your servers have been setup:

 

  1. Unzip the contents of the ESS.{ver}.zip file into your home or a work folder (aka., {home}). Move the folder ess into the /var folder. If you have a Windows machine you should create a /var folder. It you decide not to have a /var folder, or call it something else, you can, but you will need to modify the MySQL dabase, specifically the XMLSYSTEM element row in the SYSTEM table to point to the location of the system.xml file. You also need to modify the contents of the system.xml file. It is simplier and better for support to have a /var folder (Note: The Bitnami Amazon Cloud instance I used does not come with unzip installed.  I was able to install the unzip package with “sudo aptitude install unzip”).
  2. If you are using a database other than MySQL or ODBC, you’ll need to copy your JDBC driver jar files to /var/ess/application/webapps/ess-app/WEB_INF/lib folder.  You'll also need to copy several other configuration files to the xmls folder. For more information consult the Readme.txt in the resources folder for your database. You can skip this step if you are using MySQL which is the default.
  3. Next, you need to create symbolic links from the server folders (apache, tomcat and mysql) to the appropriate application and data folders. Create these three links:
    • From Apache's htdocs folder, make ess => /var/ess/application/htdocs/ess, if using BitNami, or proxy_ajp make this link in Tomcat's webapps folder.
    • From Apache's htdocs folder, make receipts => /var/ess/application/htdocs/receipts, if using BitNami, or proxy_ajp make this link in Tomcat's webapps folder.  This folder needs to be writable by the Apache application.
    • From Tomcat's webapps folder, make ess-app => /var/ess/application/webapps/ess-app
    • From MySQL's data folder, make ess => /var/ess/data/ess
    • There are specific examples in the installation notes for creating symbolic links on each platform.

Consult  installation notes for syntax on various systems.

  1. The ‘@@strings@@’ in the configuration files represent specific addressing.  We want to replace the ‘@@strings@@’ with information that is valid for your installation.
  2. Edit the /var/ess/xmls/system.xml file to provide the correct information regarding your email system.
    • exp_email_address ( @@emailname@@ ) - The email account that will be used by ESS to send out workflow and informational messages. Example: expense@mycompany.com
    • smtp_address ( @@smtp@@ ) - This is the URL of the SMTP server that ESS will use to send out e-mail messages.  Example: mail.mycompany.com
    • smtp_domain= ( @@domain@@ ) - The general domain of your company.  Example: mycompany.com
    • pal_email_address = ( @@emailname@@ ) - The email account that will be used by ESS to send out workflow and informational messages. Example: expense@mycompany.com
    • dump_mail = ( @@emailname@@ ) - same as above.
  3. If you are supporting the acceptance of receipt scans by phone or email you need to set up a separate POP3 mailbox to act as a gateway in collecting the scans. Do not use the address that you send ESS mail from as this will cause confusion in handling incoming messages. To edit the gateway and POP3 elements for the gateway, in the configuration section of system.xml edit:
    • Gateway_interval – Interval in minutes that ESS will look for messages in the POP3 mail box.
    • Gateway_stop_time – Recommend setting to ‘No’.
    • Pop3_logon – The login ID to the POP3 mail box that serves as the gateway.
    • Pop3_password – POP3 password
    • Pop3_delete_messages – Normally set to ‘Yes’.  ‘No’ is used for debugging.
    • Pop3_address – Address of the POP3 server.
  4. Edit the /var/ess/application/webapps/ess-app/WEB-INF/web.xml file for the root user
    • @@dbuser@@ - login user for access to the database. Example: root
    • @@dbpassword@@ password used to access database. Example: MyPassword
    • It may be necessary to modify the port number used to access MySQL in the DBDatabase context-param. The current string being used is:

jdbc:mysql://localhost:3306/ess?zeroDateTimeBehavior=convertToNull

    • The number 3306 is the port number and should correspond to the port used when MySQL was set up. The MySQL port default is 3306.
    • If you are supporting the acceptance of receipt scans by phone or email, you may want to activate the ReceiptConduitLaunch listener class.  This will run a background task when Tomcat is started that is responsible for polling the email box associated with downloading the receipt scan files.  Remove the "comment-" characters from the beginning and ending name tags for listener that contains the ess.ReceiptConduitLaunch class to activate this feature. Consult the webFullVersion.xml file in the WEB-INF folder as to what an active ess.ReceiptConduitLaunch class element should look like.
  1. Edit the /var/ess/application/webapps/ess-app/WEB-INF/classes properties files for @@expensereport@@.  This should be set to the URL of the server that is running ESS. Currently there are two properties files. One is for English and the other is for French.
  2. The web.xml file also controls LDAP support. You should get the ESS application up and running independent of LDAP and then switch to LDAP. Consult the LDAP Integration document for setting LDAP up.
  3. Make sure that the security on /var/ess/data/ess allows it to be accessible to Tomcat.  In Linux this can be accomplish by setting the ess folder and its contents to the same owner and group as Tomcat (sudo chown -R owner:group /var/ess).  Also you may have to ensure that the data files are read and writable (sudo chmod 666 *)
  4. Restart the Tomcat server. (Under BitNami, use the ctlscript.sh restart function to do this)
  5. Test the reporter/approver login with one of the following three URLs:

o        http://{your server address}/ess/en/XLogin.html
login = reporter@expenseservices.com, password = password
(reporter in English)

o        http://{your server address}/ess/en/XLogin.html
login = approver@expenseservices.com, password = password
(reporter/approver in French)

o        http://{your server address}/ess/ess/Login.html
login = reporter@expenseservices.com, password = password
(Legacy)

[Note: Reporter's reports are send to Approver for approval]

  1. Test the audit login with the following URL:

o        http://{your server address}/ess/ess/Audit.html
Login = admin@expenseservices.com, password = password
(auditor in English)
(You can also access the audit and admin menu from the 'Admin' link on the reporter login)

====