WME Comenzi Online (WMECOL) - WME Online Orders This is a module of WinMENTOR ENTERPRISE(WME), produced by SC TH JUNIOR SRL. The WMECOL module creates a web browser interface for operations specific to WME users, intended for sales agents. Technical details ================= WMECOL is made up of three main components: --ServerCO.exe - provides the communication environment between the client applications and the WME database. --monitor.html (MONITOR) - web page used to monitor and stop ServerCO.exe. It opens with a double-click, in the browser, and requires no installation. It does not start the server (a web page cannot launch programs from disk). --folder /WMECOL/Data/client, sources for setting up the web page that will serve as the interface for the application's users WMECOL uses two web communication protocols: 1) HTTP for initializing the client page and uploading source files and 2) WS for web page communication with ServerCO.exe. Requirements ============ -Windows 10 operating system -installation/pre-configuration of an HTTP server (example: Apache), or ftp access to a website; -configuration in the local network of the ports accessed from outside (port forwarding): 80 (default port for http access) and the port used by the application for ws (default 9090; can be changed in /WMECOL/Data/app.ini - see Installation, point 2) -a modern web browser on the host computer, for the MONITOR page (monitor.html). Installation ============ 1) Copy the WMECOL directory to the desired location on the disk, where you want to install the application The application directory has the following structure /[WMECOL] - root dir -ServerCO.exe -monitor.html -killswitch.bat -readme.txt /[Data] -dir -app.ini -config.ini /[client] -dir ... /[oracle] -dir OPTIONAL, see below /[network]/[admin] OPTIONAL, see below ServerCO.exe contains inside it both the PHP execution environment and the server code, so there is no need to install PHP on the host computer. On first start it prepares its working environment in %LOCALAPPDATA%\WME\ComenziOnline (approximately 20 MB); subsequent starts are immediate. That folder can be deleted at any time: it is recreated automatically. The name of the server executable Depending on the license key version, the server executable may have one of the following names: ServerCO.exe, WMEServerCO.exe, WMEServerCO10.exe or WMEServerCO50.exe. They all work identically. In this document we refer to it as 'ServerCO.exe'; replace it with the name you actually have in the folder. killswitch.bat stops it regardless of the name. The [oracle] folder (optional) If you unzip Oracle Instant Client 19 (32-bit) into a subfolder named 'oracle', next to ServerCO.exe, the application will use it from there and it is no longer necessary to install it in the system PATH. The [network]\[admin] folder (optional) If you place the tnsnames.ora file here, the application will use it automatically, without the need for the TNS_ADMIN system variable. If the system already has TNS_ADMIN configured, that takes priority. 2) Application configuration - if this is your first use and you do not have the files config.ini, app.ini, config.css, rename config.ini.new.ini, app.ini.new.ini, config.css.new.css to config.ini, app.ini, config.css respectively. (The .new files are reference copies, delivered with every update precisely so that they do NOT overwrite your configuration. On an update, compare them with your own files: new parameters appear there.) - open the app.ini file in a text editor, and modify the default settings if necessary, following the instructions. - [database] : the Oracle database instance used by the application, value 'database' - if you use a PostgreSQL database, set the parameter PG = 1 and fill in the values for pg_host, pg_port and pg_dbname The same ServerCO.exe works with both Oracle and PostgreSQL; there are no longer separate executables. The choice is made exclusively from app.ini, through the PG parameter. If you only use PostgreSQL, Oracle Instant Client is not needed. If app.ini requires Oracle and the Oracle client is missing, the server does not start and will display a message stating exactly what needs to be installed (instead of stopping later, at the first login). - [ports] : the access ports, the 'APP_PORT' and 'EXT_PORT' values (No configuration is required in the application for the access port through the http protocol, where the default is port 80; However, configuration is required for access from outside the local network. See Requirements.) The difference between the two, in short: APP_PORT = the port on which the server LISTENS on the host computer EXT_PORT = the port the browser CALLS; it is written automatically in /Data/client/config.js If you do not specify EXT_PORT, the value of APP_PORT is used automatically. So for use in the local network it is enough to change APP_PORT. Specify EXT_PORT different from APP_PORT ONLY if you have port-forwarding on the router (for example EXT_PORT = 9500 redirected to APP_PORT = 8000). If the two differ, ServerCO.exe will warn in the window and in Data\ServerCO.log, because a wrong value here leads to a client page that does not connect. The MONITOR page (monitor.html) does not read app.ini. If you change APP_PORT, type the same value in the 'Port' box on the page - see point 5. - [HOST] : value 'HOST_NAME' - [PATH] : value 'CLIENT_DIR' 3) Network configuration (required only for access from outside the local network;) -see Requirements and Installation points 6.b and 7. 4) Web server configuration: (Apache) -Set the value (in httpd.conf), the path to /WMECOL/Data/client/ -Start the server 5) Starting the application -Start the server with a double-click on ServerCO.exe In the folder /WMECOL/Data/client/ a configuration file for the client will be generated, /config.js . -Open monitor.html (double-click; it opens in the default browser) The page connects automatically and shows the communication between the server and the connected clients, the server messages and the errors. You can send commands to the server (Ping!, PRINT SESSION) and you can stop the server with the 'Stop AppServer' button. -If messages from the server appear in the WMEOL MONITOR page, you can proceed to the next step. (After starting the server, the WMEOL MONITOR page can be closed; the server keeps running. To stop the server, open monitor.html again and press the 'Stop AppServer' button.) -If you changed APP_PORT in app.ini, type the same port in the 'Port' box on the page. The value is remembered by the browser. It can also be given in the address: monitor.html?port=8000 (The page cannot read Data\app.ini by itself: from a local page, browsers have no access to files on disk.) -The server cannot be started from monitor.html: a web page cannot launch programs from disk. Start it with a double-click on ServerCO.exe. -monitor.html can also be installed on the web server, next to the client pages, but it then becomes accessible to everyone: in that case put it in a password-protected folder. Using it only locally is recommended. When you start ServerCO.exe, a window opens with the text 'Server running...', having the WME icon in the title bar and in the taskbar. The window can be minimized; the server continues to work. Below this text the database read from app.ini is displayed, so that you can see immediately what the server is working with, for example: Oracle - DBVIVI PostgreSQL - 10.0.101.83:5432/postgres The same information appears with 'ServerCO.exe --status' and in Data\ServerCO.log. If you close the window, the server stops (a confirmation is requested, because the connected users would be disconnected). When the server is stopped from MONITOR or from killswitch.bat, the window closes by itself, without asking anything. For diagnostics you have, from the command line, in the application folder: ServerCO.exe --status shows whether the server is running ServerCO.exe --stop stops the server ServerCO.exe --console starts the server displaying the messages in the console ServerCO.exe --probe checks the PHP extensions and the connection to the Oracle / PostgreSQL libraries; the result is also saved in /Data/diagnostic.txt killswitch.bat stops the server in an emergency, when it no longer responds to the commands above. It never starts anything. The files useful for diagnostics are written in the /Data folder: ServerCO.log the server starts and its messages php_error.log PHP errors fatal_errors.log fatal errors When you report a problem, send these three files. 6) Access Application users can connect in two ways: a) Local: from the machine on which the application was installed -Open a modern web browser, capable of web-socket connections (Google Chrome, Mozilla Firefox, etc). -Access http://localhost If the connection has been established, the authentication form will appear on the page. b) Remote: from another device, via the Internet -Open a modern web browser, capable of web-socket connections (Google Chrome, Mozilla Firefox, etc). -Access http://[HOST_NAME], where [HOST_NAME] represents the value set in /WMECOL/Data/app.ini If the connection has been established, the authentication form will appear on the page. 7) Installing the client part on a web site -Copy the contents of /WMECOL/Data/client/ into the desired directory on the site Example: If installation at the address http;//www.example.com/orders/ is desired, all the files and sub-directories from /WMECOL/Data/client/ will be copied into the /orders/ directory on the server hosting the site. Attention! The file /WMECOL/Data/client/config.js must be updated with the corresponding settings from /WMECOL/Data/app.ini, namely the address and the port at which ServerCO.exe can be accessed. -Access http://www.example.com/orders/ from a modern browser If the connection has been established, the authentication form will appear on the page. -------------- For the Oracle version: If you get the error "Fatal error: Call to undefined function oci_connect()" or "Unable to load dynamic library ...php_oci8_19.dll", Oracle Instant Client version 19c, 32-bit (x86) must be installed. You can find it at https://www.oracle.com/database/technologies/instant-client/microsoft-windows-32-downloads.html (Version 19.x, Basic package). Microsoft Visual C++ Redistributable x86 is also required. You have two installation options: a) RECOMMENDED: unzip the contents of the package into a subfolder named 'oracle', next to ServerCO.exe. The application finds it by itself, nothing needs to be changed in the Windows settings. b) unzip into any folder (e.g. C:\instantclient_19) and add the path to the System PATH. Check the result with: ServerCO.exe --probe The report states directly whether the Oracle client library was found and works. If you get an error of the type: ORA-12154 could not resolve the connect identifier specified check in tnsnames.ora that you have a connection string for the database from app.ini. The path to tnsnames.ora can be indicated in two ways: place the file in the 'network\admin' subfolder next to ServerCO.exe (the simple option), or save the path in Environment variables, System, in the TNS_ADMIN variable. For the Postgresql version: No installation is needed anymore: the PostgreSQL client library (libpq) is included in ServerCO.exe. Check with ServerCO.exe --probe . If you receive the error at login: pg_connect(): Unable to connect to PostgreSQL server: authentication method 10 not supported on file the md5 method must be put instead of scram-sha-256, in pg_hba.conf, in the table at the end, on each line; a new line must be added before the others: host all all 0.0.0.0/0 md5 and the password of the user you connect with must be updated, so that it is encrypted with md5: alter system set password_encryption = 'md5'; select pg_reload_conf(); alter role user_name with password 'user_password'; select rolpassword from pg_authid where rolname = 'user_name'; Now the encrypted password should start with md5. ----------------- RUNNING AS A WINDOWS SERVICE ============================ The server can be installed as a service using the utility nssm.exe (http://nssm.cc). ServerCO.exe stays in the foreground as long as the server is running, exactly as nssm needs, and does not open any window. Run, from a console STARTED AS ADMINISTRATOR: nssm install service_name and choose the path to ServerCO.exe in the window that opens. For 'Startup directory' set the installation folder (the one containing Data). Then you can run nssm start service_name nssm stop service_name to start the service (it should appear with the name specified in Task manager, Services) and to stop it. To uninstall the service, use nssm remove service_name. To check beforehand, for running as a service --------------------------------------------- A service runs under another account (by default 'Local System') and without a desktop. Therefore: 1) The Oracle client must be visible to the service account. Place it in the 'oracle' subfolder next to ServerCO.exe (the safe option), or add the path to the SYSTEM PATH (Environment Variables, System variables). A path placed only in the user's PATH is NOT visible to the service. 2) If you use tnsnames.ora, place it in the 'network\admin' subfolder next to ServerCO.exe, or set TNS_ADMIN as a SYSTEM variable, not a user one. 3) The service account needs WRITE permission in the Data folder (that is where ServerCO.log, php_error.log and Data\client\config.js are written). 4) The service prepares its PHP environment in the profile of the account it runs under, so the first start as a service takes a second longer (for 'Local System', in C:\ProgramData\WME\ComenziOnline). 5) As a service there are no dialog windows: ALL messages, including startup errors, are written in Data\ServerCO.log. Check there if the service does not start. 6) Do not start the service and, in parallel, ServerCO.exe by double-click. The second instance is stopped automatically, with a message, but there is no point in getting there. The MONITOR page is not a problem - it is only a client, it does not occupy the port. 7) In nssm, the default value for 'AppExit' is 'Restart', so the 'Stop AppServer' button in MONITOR and killswitch.bat do not stop the server permanently: nssm restarts it immediately. The correct way to stop the service is 'nssm stop service_name'. Quick check before installing the service: run once, manually, ServerCO.exe --probe and make sure that the extension for the database you use appears with 'OK'.