Steps for manually installing ESS

Thursday, April 30, 2009

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

 

(Obsolete - Use Manual Installation Procedures Version 7)

 

This process is used to install ESS on a Web and application server.  It is assumed that Web, application and database servers have been already set up and a conduit exists between the Web and application servers.  Expenseservices.com uses, and has tested ESS on a LAMP stack consisting of  Apache2, Tomcat, MySQL and the conduit connector-j. 

 

Note: There are various installers on the ESS project site (SourceForge.net, expense-ss) that will install the ESS software for you.  Older versions will also install Apache, Tomcat and MySQL (i.e., a LAMP stack) for you.  If you do not have servers setup on the machine that you want to use, one trick is to install an older version of ESS that will install the LAMP stack for you and install the newest version of ESS on top of that.

Note: We no longer distribute, through SourceForge.net, the SQL scripts and configuration files for MS SQL Server.  If you want this item, you should contact "service@expenseservices.com".  We currently are distributing MySQL and Oracle via SourceForge.net.

 

To run ESS, you need to have a functioning Application server such as Tomcat, JRun, etc.  You need to have a functioning database such as MySQL, MS SQL Server, or Oracle.  In addition, you may have a functioning Web server such as Apache or IIS.  If you have a Web server, and this is the best, you should have a conduit between your Web server and your Application server such as connector-j.  This allows you to address the Application server folders through your Web server URL or IP.

 

If you don’t understand the previous paragraph, 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 so I suggest that you use a UI to do this work, however, if you’re hard core you can use the command line.  The copying below consists of copying folders and files to a working directory and then to your various servers.  When a folder or single file is to be copied, the simple name will be used.  When the entire contents of the folder is to be copied, but not the folder itself, an asterisks [*] is used.

 

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

 

  1. Create a working folder.  Lets call it “workingESS
  2. With the Release and workingESS, perform the following folder creations and copies from your release download folder or CD:
    1. Copy the release webapps folder into workingESS
    2. Copy the release htdocs folder into workingESS
    3. Create  a ess folder in the workingESS folder
    4. Copy the release configuration/shared/xmls folder into workingESS/ess 
    5. Copy the release configuration/mysql/xmls/* files into workingESS/ess/xmls.  This is based on your database server being MySQL.  If  you are using Oracle, use the corresponding oracle folder for these instructions.
    6. Copy the release configuration/mysql/web.xml file to workingESS/webapps/ess-app/WEB-INF folder.  
    7. Create folder workingESS/ess/xmlr
    8. Create folder workingESS/ess/xmlu
    9. Create folder workingESS/ess/dbconfig
    10. Create folder workingESS/ess/eod
    11. Create folder workingESS/ess/reports
    12. Copy the release database/mysql folder to workingESS/ess/dbconfig.  (See explanation in e.)
  3. If you are using a database other than MySQL or ODBC, you’ll need to copy in your JDBC driver jar files to workingESS/webapps/ess-app/WEB-INF/lib/.  For more information consult the Readme.txt in the release folder.
  4. At this point, you should make a backup copy of your workingESS folder.  You’ll be modifying some of the files.  You are also done using the release folder for now.
  5. The @@strings@@ in the configuration files represent specific addressing.  We want to replace the @@stings@@ with information that is valid for your installation.  Please consult the “Information Required for Installation” section in the Readme.txt file to see what information is needed.  Also consult the examples in the Readme.txt to get an idea of various configuration possibilities.  The following @@strings@@ will need to be replaced.  Step 6 specifies which files contain which @@strings@@.  The @@strings@@ that we will be replacing are:
    1. @@appserver@@ - This is the URL or IP for the application server.  If you are using a conduit, it will be the same as your Web server.  Examples: https://expense.mycompany.com, http://192.168.0.2:8080, http://localhost.
    2. @@dbconnection@@ - This is the JDBC driver connection string that is used to connection to your database.  Depending on the database that you use, this string will vary.  Please consult the Readme.txt file and the ESS Installation Information in the ERaaS administration link (www.expenseservices.com) for more information.  Also consult the web.xml files in the mysql/oracle configuration folders. Example: jdbc:mysql://localhost:3306/ess?zeroDateTimeBehavior=convertToNull
    3. @@dbpassword@@ password used to access database. Example: MyPassword
    4. @@dbuser@@ - login user for access to the database. Example: root
    5. @@domain@@ - The general domain of your company.  Example: mycompany.com
    6. @@emailname@@ - The email account that will be used by ESS to send out workflow and informational messages. Example: expense@mycompany.com
    7. @@essfolder@@ - The name of the ess folder you will use to hold configs and user’s personal data.  This corresponds to the workingESS/ess folder.  Examples are c:/ess or c:/something/ess for Windows or /var/ess for Linux or Unix.
    8. @@receipts@@ - This is the physical location of the receipts folder under either html or htdocs.  Examples: c:\inetpub\wwwroot\receipts, c:/ess/apache2/htdocs/receipts or /var/www/htdocs/receipts
    9. @@smtp@@ - This is the URL of the SMTP server that ESS will use to send out e-mail messages.  Example: mail.mycompany.com
    10. @@webfolder@@ - This is the physical location of the ess folder under either html or htdocs.  Examples: c:\inetpub\wwwroot\ess, c:/ess/apache2/htdocs/ess or /var/www/htdocs/ess
    11. @@webserver@@ - This is the URL or IP for the application server.  If you are using a conduit, it will be the same as your Web server.  Examples: https://expense.mycompany.com, http://192.168.0.66, http://localhost.
  6. @@strings@@ occur in various files.  The following files contain @@strings@@ with indicated number of occurances:
    1. workingESS/webapps/ess-app/WEB-INF/web.xml

                                                               i.      @@dbconnection@@ (1)

                                                             ii.      @@dbpassword@@ (1)

                                                            iii.      @@dbuser@@ (1)

    1. workingESS/ess/dbconfig/mysql/master.sql 

                                                               i.      @@domain@@ (4)

                                                             ii.      @@essfolder@@ (1)

    1. workingESS/ess/xmls/rules.xml

                                                               i.      @@webserver@@  (2)

    1. workingESS/ess/xmls/security.xml

                                                               i.      @@domain@@ (6)

    1. workingESS/ess/xmls/Status.xml

                                                               i.      @@webserver@@ (1)

    1. workingESS/ess/xmls/system.xml

                                                               i.      @@appserver@@ (4)

                                                             ii.      @@dbconnection@@ (1)

                                                            iii.      @@domain@@ (3)

                                                           iv.      @@emailname@@ (2)

                                                             v.      @@essfolder@@ (18)

                                                           vi.      @@receipts@@ (1)

                                                          vii.      @@smtp@@ (1)

                                                        viii.      @@webfolder@@ (1)

                                                           ix.      @@webserver@@ (5)

  1. Replace the @@strings@@  in the above files.  If you have a generic replace utility, you might want to consider using it as it will come in useful in the event that you have to redo your setup. 
  2. Stop your Web and application servers.
  3. Copy the contents of the folders you have created to their corresponding folders on your system:
    1. Copy workingESS/webapps/ess-app folder to your application server’s application directory.  In Tomcat this is the webapps directory.
    2. Copy the workingESS/htdocs/ess folder to  your html or hdtocs folder under your Web server.  If you are not using a Web server, copy this folder to the ess-app folder.
    3. Copy the workingESS/ess folder so that it has the same name as specified by @@essfolder@@.  Examples are c:\ess or /var/ess.  Note: The folders xmls, xmlr, etc. should be in the folder specified as the @@essfolder@@ replacement.
    4. Create the receipts folder in the place that you specified above.  Make sure this folder can receipt FTP transfers from a user and is addressable by a browser with a webserver plus /receipts URL.
    5. Review the security of the setup.  Make sure that you and your system administrators are comfortable with the setup.  Users will need to be able to upload files to the receipts folder.  You may decide to use a symbolic link of shortcut for this.
  4. Log into your database server and create the ‘ess’ database.  The following steps cover installing the database in MySQL.  You’ll need to modify these steps if you are using a different database.  Also, the database service needs to running to complete this process.  Here are the steps:
    1. Logon to the MySQL database as the root user.
    2. Create the database with create database ess. This step creates the database.
    3. Select the ess database: use ess.
    4. Run the MASTER.SQL with the source command.  Examples:  source c:/ess/dbconfig/mysql/master.sql or \. /var/ess/dbconfig/mysql/MASTER.SQL – This script will create the tables with default data.
  5. If you are using Oracle you should have a DBA create the database for you.  There is a MASTER.SQL script available in the database/oracle folder of the release.  Your DBA probably has rules they follow regarding users, security and schemas.
  6. Restart your applications and Web servers (in this order).  You should now be able to login to ESS with the following links:
    1. @@webserver@@/ess/ess/Login.html – This takes you into the reporter and approver set of screens.  Example: https://expenseservices.com/ess/ess/Login.html
    2. @@webserver@@/ess/ess/AuditLogin.html – This takes you into the audit and payment set of screens
    3. Use admin@@@domain@@, replacing @@domain@@ with your company’s domain, to log into either module.  The initial password is ‘password.’  You can get a list of the default users by going to the audit module and using the User File: User Primary’ screens.  Enter a ‘0’ into the ‘Personnel number’ field at the bottom and click the “Show list based on personnel number string’ at the bottom of the screen.
    4. The other users are reporter, approver and auditor with your @@domain@@ replacement.  Their password is password.  Look at their menus and you can also use the admin account to change menus (1 – 5 suggested).
  7. If you are using Oracle you will need to replace the webapps/ess-app/ajax EssProfile.jsp and AuditProfile.jsp files with the ones found in the workingESS/database/ajax_oracle folder.
  8. There is a backup user called backup@expenseservices.com with the password “password”.  Once you are able to log in as other users, you can disable this profile.

###