Web Services
Web Services support the use of the web interface and the mobile applications that are available with DEACOM. The services use TCP for communication between Server and Clients (workstations or mobile devices). They should be installed on the same server where DEACOM programs are installed (which is typically the application server), however they can also be installed on other servers/workstations if needed based on user count, transaction load, etc.
An alternative to Web Service is the Web Console., which is an application used on individual workstations if the Web Service is unavailable for one reason or another. The Console application is available in the DEACOM Production folder, labeled deacom.webserver.console, and provides the same communications necessary for DEACOM to work on a browser. Note that attempting to run the Console while the Service is running will result in an error.
Important: To support Scripting, available beginning in version 15.03, vcredist2015 must be installed on the Server running the Web Service or the PC running the Web Console. The vcredist_2015_32.exe and vcredist_2015_64.exe files are available in the main DEACOM Production folder.
Networking requirements and setup
Before installing or un-installing the web services, note the DEACOM INI file settings for the WEBSVCPORT, which defines the initial default port number for the services. This port number is used to point DEACOM mobile applications to the web service. When the browser connects to the services, the computer must be able to access the server that is running the services on the port on which it is listening. Various firewalls, which exist at almost every level of a typical network stack, can interrupt this communication. The following are the most common, from narrowest to broadest.
- Server firewall - This is a firewall running on the server itself. If the port is not allowed here, nothing except the server itself will be able to talk to the Web Services.
- Intranet firewall - Firewalls can be installed within a network to restrict network access within the network itself. This would usually be a more legitimate setup concern in the cloud where the cloud host has an entire network but has partitioned it into sub networks.
- Gateway firewall - This firewall exists at the outermost level of the network. For a home user, this would be a service provider such as a Verizon or Comcast router/modem, where the device speaks with the rest of the internet. A firewall rule (port forward) is only necessary at this level if the Web Services need to be used outside of the network. If a customer only wants DEACOM to be used within their facility or on their VPN, they would not want to configure a rule here. Direct Store Delivery (DSD) users, for instance, have to configure a rule here so that the DSD devices can talk to the Web Services while out on a route. These situations are handled on a case by case basis.
Install Deacom Web Service form
The table lists the field and options available when installing Web Services. The steps for installing and configuring the services is listed in the sections further down on this page.
Field/Button |
Description |
---|---|
DEACOM Directory |
Leave Blank |
Service Installation Directory |
Defines the location where the web service will be installed, usually the main DEACOM directory such as "C:\Program Files\Deacom - ABC Company". |
Windows User Name |
Indicates the user as which you would like this DEACOM Web Service instance to run. This user needs permissions to read/write to the installation folder and to read/write to the DEACOM folder. |
Windows User Password |
Enter appropriate password |
Windows Domain |
The windows domain (DNS) where the service will be installed (e.g. "ABCCompanyHQ"). If the company is not using a domain environment, put server name, i.e. the name of the computer that the web services will run on during installation. |
Port |
Defines the port you would like the services to listen on. In regards to ports, if using an http address, 80 is the default. If using an https address, 443 is the deault port. If you wish to specify an address besides one of these two, then the port number must be speciifed after the colon in the address. Port numbers are stored and maintained in the "deacom.webserver.settings.xml" file in the service installation folder. Prior to changing the port number, the "Deacom.WebServer.Service" must be stopped and then restarted once the change is made. Note: If multiple instances of the "Deacom.WebService.Service" are running, the one that is needed is the one ending with the system database name. |
Install IIS Adapter |
Optional. The IIS Adapter option offers the ability to have the DEACOM services listen through IIS as well as the specified port. This option is useful in environments where IIS is already configured and serving other web traffic. |
Run Automated Processes |
Optional. Supports the ability to run automated processes that are run on a timer, such as auto logout, automatic exports, stability test movements, scheduled data imports and scheduled externals.
|
Installing and un-installing the Web Services
Installing the Web Services
Important: If re-installation of Web Services must occur for any reason, the service must first be un-installed. Refer to the "Un-installing the Web Services" section on this page for process steps.
There is an installation program provided by Deacom that installs Web Services with minimal input from the user.
- Locate the executable.
- Open the File Explorer.
- Navigate to x:\Deacom\<CompanyName>\.
- Locate the Deacom.WebServer.Service.Installer.exe program and double click it to open the Install Deacom Web Services window.
- Enter valid credentials in the Install Deacom Web Services window and install the service.
- The "DEACOM Directory", "Service Installation Directory", and "Port" fields will be populated based on the INI file of the folder from which the program was launched.
- In the "Windows User Name", "Windows User Password", and "Windows Domain" fields, enter credentials for a Windows user that has admin rights to the appropriate folder. If necessary, request from IT a new user to be created and used only for services.
- Ensure the "Install IIS Adapter" flag is not checked.
- Note: Beginning with new DEACOM installations of versions 15.03 and above, IIS installation is included as part of the entire application installation process.
- Click "Install". Be patient - the process may take a couple minutes. Installation is complete when a prompt appears indicating the Web Services have been installed successfully.
- Configure the newly installed service.
- Navigate to the service installation directory previously used in step 1.2.
- Locate the DEACOM.WebServer.settings.xml file, right click it, and open with Notepad.
- Locate the <DeacomRemote> line and ensure it contains a UNC path rather than a local/mapped drive letter. If it contains a drive letter, change it to a valid UNC path. Prior to saving the file, verify the UNC path specified is valid using the following step.
- Example: <DeacomRemote>\\<ServerName>\<FolderName(If applicable)>\Deacom - ProductionSystem\WWWServices</DeacomRemote>.
- Verify the UNC path specified is valid then save the XML file changes.
- Highlight the UNC path from step 3.3 and copy it.
- Open a File Explorer window and in the address bar, paste the UNC path, and hit Enter on the keyboard. If the path is valid, a folder will open. If the path is invalid, a prompt will appear stating a Network Error occurred and Windows cannot access the path specified.
- Back on the Notepad for the DEACOM.WebServer.settings.xml file, click File, then Save, then close Notepad.
- Locate the service and set the startup type.
- Click "Start" on the computer, and open the Control Panel.
- Select Administrative Tools, then Services.
- Locate the DEACOM Web Server Service, right click, and select "Properties".
- On the General tab, confirm "Startup Type".
- If DEACOM is installed on the SQL Server, set to "Automatic (Delayed Start)" and start service.
- If DEACOM is installed on a separate application server, set to "Automatic" and start service.
- This is so that when the server is restarted, all SQL services start first, then DEACOM services start. DEACOM services are dependent on SQL services running.
- Click "Apply" then "OK" to save any changes, otherwise close the Properties window.
- Stop and restart the service.
- In the Services window, right click the Web Services and click "Stop".
- Right click the Web Services again and click "Start".
- A prompt will appear indicating the service started and then stopped. Click "OK". When the service is initially started, is starts then immediately stops. After about a minute, it will start again by itself.
- Confirm the service started by refreshing the Services window and checking the Status of the service, which should display as Running.
- Verify the credentials used for the service.
- In the Services window, right click the Web Services and click "Properties".
- Navigate to the Log On tab.
- Verify the "Log on as" is set to "This account" and the correct credentials are entered (as previously entered in step 2).
- Note: If the user whose credentials are entered leaves the company or has their security changed, these credentials must be updated to a user with sufficient access. If, as mentioned in step 2.2, a general user for services was created by IT and is being used for this service, the credentials may remain as-is in the event of personnel changes.
- Set the recovery options for the service.
- In the Services window, right click the Web Services and click "Properties".
- Navigate to the Recovery tab.
- Set the "First failure", "Second failure", and "Subsequent failures" fields to "Restart the Service". This means that if the service fails, (if for example, the internet goes out) it will continue to attempt to restart until it is running again.
- Click "Apply" then "OK" to save the changes and close the Properties window.
- Restart the service.
- In the Services window, right click the Web Services and click "Restart".
- A prompt will appear indicating the service started and then stopped. Click "OK". After about a minute, it will start again by itself.
Notes:
- Multiple Web Services may exist on the same server. This is usually the case when both Production and Test environments exist. Each will be set up with a unique port and a Web Server.
- Web Services must be stopped prior to performing an update, otherwise they may not update. Once the update is complete, the services may be restarted.
- DEACOM updates will automatically update Web Services.
- The web service updater is designed to fire and update the files for the web service any time they do not match the files currently in the production directory. When the user running the web service does not have permissions to control services, the web service and web service updater writes a warning to Windows Event Viewer with instructions to handle this case. Also, the web service updater will attempt to update web service files even if it can not control the web service itself due to permissions.
- The DEACOM Web Service is required even if IIS was previously configured.
- The IIS Adapter can redirect traffic to either the same server or a different server. When the IISAdapter is run without a "settings.ini" file in its folder, it will redirect traffic to the service running on the current server. When that file exists in the IISAdapter folder, the traffic is redirected to the server and port specified in the file. If the port is specified but not the server, the traffic will be redirected to that port on the current server.
Installing the Web Services on a non-domain server
The Web Services can be installed on a server that is not on the same domain as the DEACOM folder itself, but additional care and setup is required. Before trying to install this type of setup, become familiar with the basic installation instructions above, as they can be used to add more detail to the specific instructions for this type of setup. After installation, the Web Services should behave as if they were installed on a server that is on the domain, except with vastly more limited permissions as far as access to domain services and files are concerned, which is beneficial for externally-facing web services. It is recommended to pair this process with an SSL certificate for maximum security.
- Access the DEACOM server.
- Log into the server that has the DEACOM (production or training) folder on it. This server should be on the domain.
- Locate or create a domain user with limited access, ie: only read/write access to the DEACOM folder. Take note of these credentials and ensure permissions. After this step, access to the DEACOM server will no longer be necessary.
- Create a new set of Windows credentials.
- On the non-domain server, log in as the user that the Web Services want to run as. Since the web server is not on the domain, this can be an elevated user with much less impact, as long as nothing else sensitive is located on the web server.
- Click "Start" on the computer, and open the Control Panel.
- Select Credential Manager, then Windows Credentials.
- Click "Add a Windows credential". When configured, this credential will allow the non-domain server to impersonate the domain user from step 1.2 when accessing the server that is on the domain.
- Complete the fields with the server name or IP, domain/username, and password, respectively, then click "OK". The Credential Manager is no longer necessary after this step, and can be closed.
- Locate the executable.
- Open the File Explorer.
- Navigate to the UNC path for the server name or IP from step 2.5. Example: "\\ServerName" or "\\192.168.100.101".
- Navigate to the DEACOM folder.
- Locate the Deacom.WebServer.Service.Installer.exe program, right click it, and select Run as administrator to open the Install Deacom Web Services window.
- Enter valid credentials in the Install Deacom Web Services window and install the service.
- Verify that the path in the "DEACOM Directory" field is valid. It should start with the server name or IP from step 2.5. If not, the installer or service may not behave properly.
- In the "Windows User Name" and "Windows User Password" fields, enter the local credentials.
- In the "Windows Domain" field, if the server is not on a domain, enter the local computer's name. Otherwise, enter the alternate domain for this server.
- In the "Port" field, enter a port that is not currently in use on the server. To find an available port:
- Click "Start" on the computer, type "CMD", and open the Command Prompt.
- On the Command Prompt, type "netstat -an" (without quotes) and hit Enter on the keyboard. The computer will produce a list of all ports on the computer. Ports labeled as "Listening" or "Established" are available for use.
- Ensure the "Install IIS Adapter" flag is not checked.
- Note: Beginning with new DEACOM installations of versions 15.03 and above, IIS installation is included as part of the entire application installation process.
- Click "Install". Be patient - the process may take a couple minutes. Installation is complete when a prompt appears indicating the Web Services have been installed successfully.
- Verify the service is installed and started.
- Click "Start" on the computer, and open the Control Panel.
- Select Administrative Tools, then Services.
- Locate the DEACOM Web Server Service and confirm the Status displays as Running.
- Verify a user can access the application using a web browser.
- From a browser on the local server, type "http://localhost:PORT" in the URL, where PORT is the port selected in step 4.4, then hit Enter on the keyboard.
- Verify that a DEACOM login screen appears and that a user can log in and begin using the software.
Un-installing the Web Services
The process for un-installing the DEACOM Web Service is as follows:
- Locate the service.
- Click "Start" on the computer, and open the Control Panel.
- Select Administrative Tools, then Services.
- Locate the Web Services, right click, and select "Properties".
- On the General tab, select the entire Service Name and copy it.
- Exit the Properties window.
- Stop the service.
- In the Services window, locate the Web Services, right click, and select "Stop".
- Open a command prompt as administrator.
- Click "Start" on the computer, type "CMD", right click the Command Prompt result, and select Run as administrator.
- Use the sctool to remove the service from the Services list.
- Type the following: sc delete "<ExactSpellingOfServiceName>" (the service name, pasted from step 1.4, must be in quotes and is not case sensitive)
- Example: sc delete "Deacom.WebServer.Service - ProductionSystem"
- Hit Enter on the keyboard to execute the prompt.
- If successful, the command prompt will display a "[SC] DeleteService SUCCESS" message.
- Confirm the service is deleted.
- In the Services window, refresh the list, and verify the service is no longer listed.
- Delete the folder where the Web Service was living.
- Important: This step must occur to re-install the service. If the folder is not deleted, a prompt will appear during the installation process stating that the folder already exists.
- Open the File Explorer.
- Navigate to the drive on the application server where the DEACOM system is installed.
- Locate the folder and hit Delete on the keyboard.
- Confirm the folder has been deleted. The DEACOM Web Service is now completely un-installed.
- Note: Do not create a new folder.
Installing and configuring IIS
The Internet Information Services (IIS) Adapter allows DEACOM to communicate with HTTPS. If using the IIS Adapter, setting up IIS first is recommended. The address of the site will be http://<yourIISDEACOMSite>.com, where "yourIISDEACOMSite" is the server name or IP address of the server where the Web Service is installed, as defined in step 2.1 of the "Installing the Web Services" process and/or step 2.5 of the "Installing the Web Services on a non-domain server" process. With or without IIS, the site will always be accessible via http://<yoursite:yourport>, where "yourport" is the port selected in step 2.1 of the "Installing the Web Services" process and/or step 4.4 of the "Installing the Web Services on a non-domain server" process.
Installing the IIS Adapter manually
If the Web Services have already been installed but the IIS Adapter has not, it can be manually installed at a later time using the following steps.
- Open the Server Manager and enable the proper features.
- Click "Start" on the computer, type "CMD", and open the Command Prompt.
- On the Command Prompt, type "ServerManager" and press Enter on the keyboard.
- Click "Add Roles and Features".
- In Server Roles, put a check next to "Application Server".
- When prompted, ensure that both .NET Framework 4.7 and Web Server (IIS) Support are enabled.
- Click "Next" to go to Features, then under .NET Framework 4.7 Features, ensure that ASP.NET 4.7 is enabled.
- Click "Install" to confirm enabling the selected features.
- For a dedicated website, copy the IISAdapter files to the IIS web root folder and skip to step 5. For example, copy from C:\Deacom\Production\WWWServices\IISAdapter to C:\inetpub\wwwroot. If you prefer to put the IISAdapter in a subfolder:
- Create a new folder, like C:\IISAdapter
- Give the local IUSR user read-only access to the new folder.
- Copy the IISAdapter files to the new folder.
- Open the IIS Manager and add an Application Pool.
- Click "Start" on the computer, and open the Control Panel.
- Select Administrative Tools, then Internet Information Services (IIS) Manager.
- Expand the Connections to reach "Application Pools".
- Right-click on "Application Pools" and select "Add Application Pool".
- Enter the name and ensure the ".NET CLR version" field is set to ".NET CLR Version v4.0.30319" and the "Managed Pipeline Mode" field is set to "Integrated".
- Click "OK" to create the Application Pool. Leave the IIS Manager open for subsequent steps.
- In the IIS Manager add a virtual directory.
- In the IIS Manager, expand the Connections again to reach "Default Web Site".
- RIght-click on "Default Web Site" and select "Add Application".
- Fill in the "Alias" field (Example: Deacom).
- Click "Select" next to the "Application pool" field and select the Application Pool created in step 2.
- Click "..." next to the "Physical path" field and set it to the IISAdapter folder (Example: C:\IISAdapter).
- Click "Test Settings..."
- Note: If the default user does not have access to the physical path selected, create a local user and give it access, then click "Connect as..." and enter the new credentials.
- Click "OK" to finish creating the virtual directory.
- Edit the ApplicationHost.config file.
- Open File Explorer, navigate to "C:\Windows\System32\inetsrv\config\ApplicationHost.config" and open the file with NotePad.
- In NotePad, find <section name="handlers" overrideModeDefault="Deny"> and change it to "Allow". Save and exit.
- When using a separate user, open File Explorer and give the Windows user read/write access to the "C:\Windows\Microsoft.NET\Framework64\v4.0.30319\Temporary ASP.NET Files" folder.
- Navigate to the Deacom IISAdapter folder and create/edit the "settings.ini" file.
- Add a line for the server name: SERVER=localhost
- Add a line for the port number: PORT=8080
Forcing the IIS file copy process after an update
When installed, the IIS service copies a series of files locally but monitors the production folder to re-copy the files when an update is applied. It usually takes about a minute or so after the DEACOM updater finishes for the files to propagate to the service. If, after an update is applied, the service does not copy the files from the DEACOM directory to the service directory chosen in the wizard, follow the steps below to force the copy process.
- Locate the service directory that was chosen in the service installer.
- Ensure the service user picked in the installer has write access to this directory (14.6.52's service will not start if this is not true). This user needs to be a user that is allowed to elevate programs to administrator rights, so it can self-update.
- Copy the Deacom.WebServer.Service.Updater.exe program from the Deacom production folder and paste in the service directory from step 1.
- Right-click on the executable from the service directory and select "Run as administrator". Once all files are copies, the service will launch.
Configuring IIS to listen for SSL on an alternate port
In situations where users will need to configure the IIS to listen on an alternate port, the IIS Adapter now correctly maintains the custom port number in the URL. Follow the below steps to accomplish this.
- Access the IIS Manager and change the port.
- Using a working IISAdapter setup, log into the server.
- Click "Start" on the computer, and open the Control Panel.
- Select Administrative Tools, then Internet Information Services (IIS) Manager.
- Expand the Connections to reach "Default Web Site".
- Right-click "Default Web Site" and select "Edit Bindings".
- Select HTTPS and click "Edit".
- Modify the Port, save the changes, then exit the Edit Bindings form. Example: Change the port from 443 to 4400.
- Right-click "Default Web Site", select "Manage Website", then select "Restart".
- Verify a user can access the application using a web browser.
- From a browser, enter the URL with the new Port number selected. Example: https://server1:4400/.
- Verify that a DEACOM login screen appears and that a user can log in and begin using the software.
Configuring security and external access
Obtaining an SSL certificate
While DEACOM does not require encryption, if secured access is desired or necessary, customers will need to buy and install a secure certificate on the server. An SSL Certificate may be obtained in order to support an SSL Encrypted Connection (https). To do this, customers need to first get an unmodified IIS installation set up with an SSL certificate. HTTPS traffic runs on port 443 so customers will also need to set up a website in IIS listening for https on that port. Next, make a web application pointing at the WWWServices/IISAdapter folder in the DEACOM application folder on the same server that is running the Web Services. The IIS Adapter will find the running Web Services on the server and automatically start routing the traffic through itself. Users can then navigate to https://<yourIISDEACOMSite>.com and get a fully encrypted connection.
Note: Don't use wildcard characters in the server certificate name.
Configuring access for external users
The process for configuring the DEACOM Web Services for outside access involves the use of port forwarding. This is only necessary if external users should be able to use the DEACOM environment. Port forwarding allows remote computers, computers on the Internet for example, to connect to a specific computer or service within a private local area network. Customers should consult their internal IT resources for specific details on setting up port forwarding at their location(s).
When configuring port forwarding, network administrators will usually set aside one port number on the gateway for the exclusive use of communicating with a service in the private network, located on a specific host. External hosts must know this port number and the address of the gateway to communicate with the network-internal service. Often, the port numbers of well-known Internet services, such as port number 80 for web services (HTTP) or port number 443 for secured web services (HTTPS), are used in port forwarding, so that common Internet services may be implemented on hosts within private networks.
Establishing a DNS site name
Generally, customers will work with their web service provider to establish a site name. A domain name is not required when attempting to establish a site name; Instead a sub-domain may be set up that uses a DNS record pointing to the router's IP. A router is generally configured with an external IP that it uses to communicate to the rest of the internet. The server behind the router has an internal IP and the web server is listening on a certain port. The port forward needs to exist so that when the router is contacted on that port, the router knows to forward that traffic to the server which exists behind the router. When that is set up, outside customers can connect via IP. A sub-domain on their current site may be configured that uses a DNS record pointing at the router's IP. Something like "deacom.abccompany.com" for example. Specifically, the customer will need to add a record on the DNS server to resolve "deacom.abccompany.com" to the external IP address.
Restart Web Services
The option is controlled by the "Access Deacom Restart" field on the Edit User from via System > Maintenance > Users.
- This option is mutually exclusive with both SSO Only login and LDAP users. If "Single-Sign On Only" is checked, or if an LDAP username is entered, the Access Deacom Restart checkbox is grayed out and vice versa.
- This checkbox works in connection with the RestartDeacom endpoint.
- To restart the web service:
- In the browser, at the end of the URL, add /restartdeacom. This will redirect to /MainApp/RestartDeacom.
- A new login box (with the warning that it will restart Deacom) will appear. At this point the user will enter their Deacom credentials.
- A loading screen will appear, followed by File Explorer popup of results from a Performance Diagnostic Utility dump, followed by a popup of a command window. Now the browser page will display a countdown from 60 to 0.
- Once the command window disappears, the user will be returned to the main Deacom page. (You do not need to wait for the countdown to finish.)
- The service should now be running again.
Notes: The restart option automatically runs a Performance Diagnostic Utility. The contents of Performance Diagnostic Utility dump (on screen) should look like those of a normal run of the utility when Export All is selected (correct number and similar size of files)
FAQ and Diagnostic Tips
TIP: Beginning in version 17.03, the system will add logging to the cloud local connection management in the Deacom Web Service. Every hour, each active cloud local connection's client IP, client port, and available printers will be written to the Windows Event Log under the source "Deacom Web Service"
I am seeing the following error when trying to access DEACOM via IIS - "Could not load type 'System.ServiceModel.Activation.HttpModule' from assembly 'System.ServiceModel, Version=3.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089'"
This issue is most likely occurring on Windows Server 2008 which does not natively support ASP.NET 4.0. To correct this, run the following command in the Windows Command Prompt (CMD) will install the version of ASP.NET that is associated with Aspnet_regiis.exe and only registers ASP.NET in IIS. "c:\WINDOWS\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis.exe -iru"
I am receiving a managed pipelinehandler in the module list error when trying to access Deacom via IIS.
Check the web.config file for the below block of remove files:
- <remove name="svc-Integrated-4.0" />
- <remove name="svc-Integrated" />
- <remove name="svc-ISAPI-4.0_64bit" />
- <remove name="svc-ISAPI-4.0_32bit" />
- <remove name="svc-ISAPI-2.0-64" />
- <remove name="svc-ISAPI-2.0" />
What if the service won't start?
Check the account used when installing the services and the credentials entered on the Log On tab of the service's Properties. If security was changed, you must use the new account. To update credentials:
- Locate the service by clicking "Start" on the computer, and opening the Control Panel.
- Select Administrative Tools, then Services.
- Locate the Web Services, right click, and select "Properties".
- On the Log On tab, ensure "This account" is selected and enter the new credentials in the corresponding fields.
- Click "OK" to confirm the changes.
When would I need to un-install and re-install?
Cases where services crash, stop, and/or cease to function for various reasons. These could possibly include Windows updates or web version updates.
What is the minimum security that I need for the Web Services Service User Account?
The minimum security requirements for the Web Services is to have Local Admin rights. However, if you utilize network printers, you’d need domain Admin rights in order to print from those. In most cases, users make use of network printing and thus need to have both local and domain admin rights on the service account user tied to the Web Services.
How do I handle the following error message? - “The source was not found, but some or all event logs could not be searched. To create the source, you need permission to read all event logs to make sure that the new source name is unique. Inaccessible logs..”
This message indicates that the user running Deacom is not a Local Admin as they do not have permission to read and write from the Event Log.