EDM Installation and Setup

This document contains instructions for installing EDM at both a central site, and a remote site. At central sites, the system is typically installed on a web server so users can access it from a web browser. If the web server is visible over the internet, users can access it from anywhere they have an Internet . At remote locations, the system is usually installed in standalone mode without a web server. Standalone mode allows users to access the system without installing a web server but it can only be used in single-user installations. The standalone mode does not support multiple users because it does not synchronize changes to cached system data among multiple users.

Table of Contents

Typical Lab Installation

A typical lab system has one central system and one remote system that can be on the same PC or a difference PC from the central system. To install EDM for a lab test, follow the directions in each of the following sections:

  1. Installing Central System

  2. Installing Remote System

  3. Creating Central Tables

  4. Requesting Data from Remote Sites

Installing Central System

The system has been tested with the Apache Tomcat Servlet Container version 6.x, 7.x and 8.x. Note that the application being maintained by the system, such as the POS system, does not have to be installed on the server. If you already have the Apache Tomcat Web Server installed, you will need to set it's folder in the setup batch file before continuing.

To install the central system, take the following steps:

  1. Run the executable file that begins with EDM-Server-Setup and follow the prompts to install for your system. By default, the system will be installed in the folder C:\EDMServer.

  2. Test your installation by opening your browser to: http://localhost:8080/edm (if you are not on the same machine as the server, replace localhost with the server name or IP address). Login using userid admin and password admin. At installation, the system has the following predefined user id/password combinations:

    remote/remote
    Typical login for a user at a remote site who only has permission to process transactions.
    central/central
    Typical login for a central user who has permission to use all the forms and functions at headquarters.
    admin/admin
    Administrative login with all permissions including setting up new users and roles and modifying the forms and queries in the application.

  3. The Tomcat Web Server is installed as a service, so, to start, stop, or restart Apache Tomcat, use the Services option under Administrative Tools in the Control Panel.

  4. To use the Tomcat Manager to reload the application after updates or configuration changes, add a user to the conf\tomcat-users.xml file in the Tomcat folder with the following format: <user username="me" password="mypassword" roles="tomcat,manager,admin"/> (change the username and password as necessary), restart Tomcat, browse to http://localhost:8080/manager/html (replace localhost with server name if necessary), enter your userid and password, and click Reload on the line that has the /edm path.

Support processing transactions on a separate server

Users may set up a 'transaction server' in addition to the main web server. The transaction server handles inserting rows into the audit table, committing packages, and processing incoming transactions. Using a separate server for transaction processing relieves the main web server of those tasks and improves performance on the main web server. The main web server checks the transaction server's status before forwarding each command to verify that it is available and is running the same version of the software as the main web server. If the transaction server is not available then transaction processing will be performed on the main web server. Since committing and transaction processing may occur on either server, it is important to set the localSendDir and localReceiveDir elements in config.xml to refer to the same server and directory on both the transaction server and the main web server.

To configure the web server to forward transaction processing tasks to a separate transaction server take the following steps:

If command forwarding is working properly, you will see a line in the log.txt file on the main web server similar to the following the first time you commit or process transactions:

INFO Connected to transaction server http://transerver:8080/edm/xmlcommand.do.

If the connection to the transaction server fails, you will see a warning message in the log like this

WARNING Failed to connect to transaction server http://transerver:8080/edm/xmlcommand.do.

and the transaction processing will be performed on the main web server.

If transaction server is running a different software version than the main web server, you will see a warning message in the log like this

WARNING Invalid software version on transaction server: Version 6.2 at http://transerver:8080/edm/xmlcommand.do, must match the software version on this server: Version 6.3.

and the transaction processing will be performed on the main web server.

If main web server is configured to forward messages to itself, you will see a warning message in the log like this

WARNING This server is configured to forward to itself, forwarding is ignored.

and the transaction processing will be performed on the main web server.

Although it is possible to configure the transaction server to forward transaction processing commands to yet another server, this will reduce performance and leads to the possibility of creating an endless circular forwarding loop.

Installing Remote System

The system is usually installed in standalone mode at remote sites because there is no need to support more than one user at a time. For a convenient lab system, the remote system may be installed on the same computer as the central system.

To install the standalone remote system, take the following steps:

  1. Run the executable file that begins with EDM-Remote-Setup and follow the prompts to install for your system. By default, the system will be installed in the folder C:\EdmWeb.

  2. Both 32 bit and 64 bit versions of EDM are available. The 64 bit version has "64" in the filename.

  3. You can start the system for the remote location by double-clicking C:\EdmWeb\go.bat.

Creating Central Tables

Because the central system does not have direct access to the application (such as the POS system), the system must request the table list and table structures from a remote site to create the central database tables. Once the system is installed at the first remote site, take the following steps to create the application tables in the central database:

  1. At the central site, add a site record for the site from which you plan to get the application table list by double-clicking Edit Locations And Groups on the Locations branch of the main menu. Click the add record (+) on the tool bar and enter the site number and name, then close the site form.

  2. Double-click Request Table List on the Transactions branch of the main menu, select the new site and click OK, click OK again to select the default package, click Yes to commit the transaction.

  3. Configure the remote site to be able to communicate with the central web server to transfer transaction files. See Web Transfer for detailed instructions.

  4. Transfer the transaction file (1.xml) from the Outgoing\sitenumber folder to the Incoming\0 folder at the remote site by double-clicking transfer_web.bat in the installation folder (usually C:\EdmWeb).

  5. At the central site, click Process All Transactions on the Transactions branch of the main menu to process the incoming table list and create the central application tables.

Supporting Additional Data Sources

If you already have a system set up with central tables and you want to support additional data sources at the remote sites, take the following steps:

  1. Backup the EdmWeb database and C:\EdmWeb folder at the site.

  2. Add a new <dataSource section to the config.xml at the store that has a unique name and appropriate settings for server name, database, userid, and password.

  3. Run go.bat so EDM loads the new dataSource into the local schema.xml file.

  4. Backup the EdmWebHQ database and jakarta...\webapps\edm\web-inf\classes folder at central.

  5. Use Transactions - Request Table List from central to get the new table structures set up at central. This step only needs to be done once.

  6. Use Transactions - Request Table Refresh from central to load data for the new table. This step needs to be repeated for each site.

Requesting Data from Remote Sites

Once the central database tables have been created using the insructions in the previous section, you can load site data for each remote site by taking the following steps:

  1. At the central site, add a site record for each site from which you plan to load data by double-clicking Edit Locations And Groups on the Locations branch of the main menu. Click the add record (+) on the tool bar and enter the site number and name. When finished, close the site form.

  2. Click Request Table Refresh on the Transactions branch of the main menu, select POS v.v.v Configuration Tables (where v.v.v is the version of POS you are using) and click Ok, select the site and click Ok, click Ok again to select the default package, click Yes to commit the transaction.

  3. Transfer the transaction files from the Outgoing\sitenumber folder to the Incoming\0 folder at the remote site by double-clicking transfer_web.bat in the installation folder (usually C:\EdmWeb).

  4. At the central site, click Process All Transactions on the Transactions branch of the main menu to process the incoming table refresh which loads the site data into the central database.

Loading Remote Location Data Directly

Optionally, users can load location data into the central database by physically bringing the location data to the central location and loading it directly. This is normally only used in lab settings as it is problematic to bring entire application databases from a large number of remote sites.

For remote sites running IRIS, take the following steps:

  1. Backup the SQL Server IRIS database at the remote location and restore it to a SQL Server system that is visible to the central system.

  2. At the central site, add a site record for each site from which you plan to load data by double-clicking Edit Locations And Groups on the Locations branch of the main menu. Click the add record (+) on the tool bar and enter the site number and name. When finished, close the site form.

  3. Click Load Location Data on the Location branch of the menu.

  4. Select the new location.

Setting up Multiple Companies

The system allow you to have more than one company on the central server. For example, if you have a group of hamburger restaurants and a group of coffee shops that are maintained separately, you could have two separate companies set up. Each company has its own database of sites and data so that there can be a site 1 in both companies. To set up an additional company take the following steps:

  1. Edit your config.xml file (by default it is in the folder C:\EDMServer\webapps\edm\WEB-INF\classes).

  2. Copy the existing company element to the clipboard as shown below (from the <company line to the </company> line inclusive).

    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config>

<config
        version = "3">
        <company
                .
                .
                .
        </company>
</config>

  3. Paste the copied company in after the </company> line and before the </config> line as shown below so that you have two company sections inside the config section..

    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config>

<config
        version = "3">
        <company
                .
                .
                .
        </company>
        <company
                .
                .
                .
        </company>
</config>

  4. Edit the properties in the second company section as follows (use an appropriate name instead of COFFEE):

  5. Restart the Apache Tomcat service.

Do I have to use :8080?

If you plan to use the Apache Tomcat Web Server that was installed with the system as the primary web server instead of an Apache or Microsoft or some other web server, you will want to change the default HTTP port for Tomcat from 8080 (it's default value) to 80 (the standard HTTP port).

Using Microsoft IIS as the Primary Web Server

If you are already using Microsoft Internet Information Services as your web server, you can integrate Tomcat with IIS so that users can access the system through IIS. Tomcat is still required because IIS does not include support for Java Server Pages (JSP) or Java Servlets.

To configure IIS to allow Tomcat to handle JSP's and Servlets, take the following steps:

Using Secure Socket Layer (SSL) to Protect Data

You can optionally configure your system to use SSL to encrypt all communications between browsers and the web server to keep your data from being viewed by hackers. This configuration varies based on your web server and you should refer to your web server documentation for details. If you are using Tomcat only as a JSP container while using Apache or IIS as the primary web server, you should configure the primary web server for SSL communictation.

As an example, the steps for configuring a Tomcat web server are given here:

  1. Generate a keystore and remember the keystore password by using the following command from the command line. Note that when the program prompts you for the Common Name, you should enter the exact server name (like www.mycompany.com) that you use when you browse to the web page and, if you are using the transfer_web function, when you configure the Transfer Host field in Edit Locations and Groups.

    %JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA -keystore /my/keystore/path/.keystore

  2. Uncomment and update the SSL Connector configuration in CATALINA_HOME/conf/server.xml

    <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<Connector port="8443" 
    maxThreads="150" minSpareThreads="25"maxSpareThreads="75"
    enableLookups="false"disableUploadTimeout="true"
    acceptCount="100" debug="0"scheme="https" secure="true"
    clientAuth="false" sslProtocol="TLS"

        keystorePass="myKeystorePassword" 
        keystoreFile="/my/keystore/path/.keystore" 
/>

  3. Uncomment the following security constraint in CATALINA_HOME\webapps\edm\WEB-INF\web.xml

    <!-- Ensure SSL used for all pages -->
<security-constraint>
  <web-resource-collection>
    <web-resource-name>main</web-resource-name>
    <url-pattern>/main</url-pattern>
    <url-pattern>/main/*</url-pattern>
    <url-pattern>*.do</url-pattern>
    <url-pattern>/login.jsp</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint>

  4. Restart the Apache Tomcat service.

  5. Access the system as usual from a browser and accept the certificates when prompted. Notice that the protocol on the address line is https: instead of http:.

Increasing Central Site Memory

To change the amount of memory allocated to Java and EDM on a central system running with the Apache Tomcat web server take the following steps:

  1. On the server running Apache Tomcat, select Start – All Programs – Apache Tomcat– Configure Tomcat

  2. Click on the Java tab

  3. Set the Initial memory pool size to the desired number of megabytes, the default is 64.

  4. Set the Maximum memory pool size to the desired number of megabytes, the default is 64.

  5. Click OK

Increasing Remote Site Memory

You can increase the amount of memory available to the system at a remote site by editing the parameters used when starting java from the command line in go.bat in the installation folder (C:\EdmWeb by default). The increase the available memory take the following steps:

  1. Right click go.bat in the installation folder (C:\EdmWeb by default) and select 'Edit'.

  2. Insert the following parameters just before -Duser (change the number of megabytes as desired): -Xms64m -Xmx256m

  3. Close and save go.bat

The following sample shows a modified go.bat that runs the system in the C:\EdmWeb folder with 64mb of initial memory and 256mb maximum memory use:

@"%JAVA_HOME%\bin\java.exe" –Xms64m –Xmx256m "-Duser.dir=C:\EdmWeb" -jar C:\EdmWeb\lib\system.jar "-user=remote" "-pwd=remote" %1 %2 %3 %4 %5

Uninstalling the Central System

To uninstall the central system, take the following steps:

  1. Use SQL Server Enterprise Manager to drop the EdmWebHQ database.

  2. Uninstall Apache Tomcat from the Add/Remove Programs option in the Control Panel (be sure to answer Yes when asked to delete all files).

  3. If you are not using Java for other purposes on the system, uninstall the Java Runtime Environment 5.0 from the Add/Remove Programs option in the Control Panel.

Uninstalling a Remote System

To uninstall the central system, take the following steps:

  1. Use SQL Server Enterprise Manager to drop the EdmWeb database.

  2. Delete the C:\EdmWeb folder and all subfolders..

  3. If you are not using Java for other purposes on the system, uninstall the Java Runtime Environment 5.0 from the Add/Remove Programs option in the Control Panel.

Hiding the Applet Warning Icon

When users access the system through a browser that is using a Java 6 plugin, they may see a yellow warning icon pop up next to the EDM windows. To stop this behavior for the EDM applet (and all other applets), users can modify the java.policy file which is found in the security folder. The path is something like %JRE_HOME%\lib\security\java.policy. Add the following line to the file then restart the browser:

permission java.awt.AWTPermission "showWindowWithoutWarningBanner";