QBMWServices Guide

Overview

QBMWServices is the Windows service application used by QBM web-facing tools to communicate with QBM Server and the selected company database. It is commonly used by QSalesView, QClock, and other browser or integration features that need controlled access to local QBM data.

Typical flow: Browser app or integration -> QBMWServices -> QBMServer -> Microsoft SQL Server company database.

In most installations, QBMWServices runs in the background as a Windows service so it starts with Windows and does not depend on a signed-in desktop user.

Component	Common Default	Purpose
QBMWServices folder	`C:\QBMWServices\x64`	Published application files and configuration.
QBMWServices API port	`8053`	HTTP API used by hosted QBM web applications.
QBMServer port	`8051` for the web bridge scenario	Local QBMServer connection used by QBMWServices.
Configuration file	`appsettings.json`	Controls service settings such as the product key.

When To Use QBMWServices

Use QBMWServices when a QBM web app or integration must reach QBM data through a controlled local service rather than connecting directly to the database from the browser.

QSalesView needs to read sales, customer, employee, location, and manager dashboard data.
QClock needs to validate users and submit time clock activity through QBM services.
A hosted or tunneled web app needs a local API endpoint on the QBMServer computer.
Support needs a stable background service that can restart with Windows.

Do not expose local QBM ports directly to the public internet. For public browser access, use an approved hosting or tunnel design and confirm security settings before go-live.

Before You Begin

Prepare these items before installing or repairing QBMWServices.

Administrator access to the computer that will run QBMWServices.
The published QBMWServices files, normally in C:\QBMWServices\x64.
The QBMServer computer name, port, SQL Server instance, and company database name.
The product key or license value required in appsettings.json.
Permission to create Windows services, add URL reservations, and update Windows Firewall rules.

Support note: If the service files were installed in another folder, use that real folder path in every command below.

Recommended PowerShell Installation

The prepared installer is the preferred installation method because it uses the expected service name and publish folder.

Open PowerShell as Administrator on the QBMServer computer.
Confirm the published files exist in the folder used by the installer.
Run the installer script.

# Change this path if the QBM source folder is not G:\QBM.
& 'G:\QBM\QBMWServices\Docs\Install-QBMWServices.ps1'

If Windows blocks script execution, run the same script with a temporary execution-policy bypass.

# Change this path if the QBM source folder is not G:\QBM.
powershell.exe -ExecutionPolicy Bypass -File 'G:\QBM\QBMWServices\Docs\Install-QBMWServices.ps1'

Check the publish folder first. If the published output is not in C:\QBMWServices\x64, edit the installer script and update the publish folder value before running it.

Verify The Service

After installation, confirm that Windows can see the service and that the API port is listening.

# Confirms the Windows service exists and shows its status.
Get-Service QBMWServices

# Confirms QBMWServices is listening on the expected API port.
Get-NetTCPConnection -LocalPort 8053

You can also check the base URL. A 404 Not Found response from the root address can be normal because the API endpoints are under specific routes.

curl.exe -I http://localhost:8053

Healthy sign: The service is running, port 8053 is listening, and app endpoints respond when called with the correct settings and security headers.

Manual Windows Service Commands

Use manual commands only when the prepared installer is not available or when support needs to repair a service registration.

Command Prompt

Open Command Prompt as Administrator.
Change to the published output folder.
Create, start, stop, or delete the service as needed.

sc create "QBMWServices" binPath= "C:\QBMWServices\x64\QBMWServices.exe"
sc start "QBMWServices"
sc stop "QBMWServices"
sc delete "QBMWServices"

PowerShell

Open PowerShell as Administrator.
Use the published executable path in the service command.

New-Service -Name "QBMWServices" -BinaryPathName "C:\QBMWServices\x64\QBMWServices.exe"
Start-Service -Name "QBMWServices"
Stop-Service -Name "QBMWServices"
Remove-Service -Name "QBMWServices"

Run Without Installing The Service

For temporary testing, QBMWServices can run from the published folder without being installed as a Windows service.

Open Command Prompt or PowerShell.
Change to the published output folder.
Run the DLL with dotnet, or start the executable directly.

cd C:\QBMWServices\x64
dotnet QBMWServices.dll

This mode is useful for support testing, but a Windows service is better for production because it can start automatically and run without an interactive user session.

Folder And Port Permissions

Folder permissions

The service account must be able to read the service files and write any required logs or runtime files.

Right-click the top-level QBMWServices folder.
Open Properties, then the Security tab.
Add or confirm the service account. Many installations use SYSTEM.
Grant the required permissions. For support-managed installations, full control may be used when the service must write logs or update runtime files.

URL reservations

If Windows blocks the service from listening on a port, add a URL reservation from an elevated Command Prompt.

netsh http add urlacl url=http://+:8053/ user=Everyone
netsh http add urlacl url=http://+:8051/ user=Everyone

Security note: Everyone is broad. Use the required service account or Windows group when the customer environment requires stricter control.

Configuration File

QBMWServices reads settings from appsettings.json in the same folder as the application binary.

Confirm the file exists beside QBMWServices.exe or QBMWServices.dll.
Confirm the ProductKey value is present and supplied by the vendor, administrator, or deployment team.
Restart QBMWServices after changing configuration values.

Best practice: Keep a backup copy of the working configuration before changing production settings.

QClock Local Development Settings

For local QClock testing, keep the QBMServer Windows service running separately from QBMWServices.

Field	Local Example
Service Address	`http://localhost:8053`
Server Name	`localhost`
Port	`8051`
Instance Name	`localhost`
Database Name	`AvilaTex`

Run QClock.Server as the web UI host. The Blazor client does not need to run as a separate Visual Studio startup project because the server hosts the client output.

Local database note: For the local AvilaTex test database, use the default local instance value shown above. Do not use a named SQL instance unless that database is actually available through that instance.

Firewall Rules

If a browser app or another computer cannot reach QBMWServices, confirm Windows Firewall allows the required TCP port.

Open Windows Defender Firewall with Advanced Security.
Select Inbound Rules.
Click New Rule.
Select Port, then choose TCP.
Enter the required port, usually 8053.
Select Allow the connection.
Choose the correct network profiles for the customer environment.
Name the rule clearly, for example QBMWServices API 8053.

Public access warning: Opening a firewall port is not the same as safely publishing QBM to the internet. Use an approved hosted or tunnel design for public browser access.

Daily Operation

After installation, QBMWServices should normally run without user interaction.

Set the service startup type to automatic when the customer expects it to survive restarts.
Restart the service after changing configuration or replacing published files.
Keep the required QBMServer service running on the expected port.
Monitor logs when web apps report permission, timeout, product key, or connection errors.
Document the customer-specific service address, database name, SQL instance, and port values.

Operational benefit: A Windows service keeps the API available in the background and avoids dependence on a logged-in Windows desktop session.

Troubleshooting

Symptom	What To Check
Service is not found	Run `Get-Service QBMWServices`. If it is missing, install the service again using the prepared installer or manual service command.
Port is not listening	Run `Get-NetTCPConnection -LocalPort 8053`. If nothing is listening, start the service and check the application logs.
Access denied when starting service	Confirm folder permissions, service account permissions, and URL reservations for the selected ports.
Browser app cannot log in	Confirm service address, server name, port, instance name, database name, product key, and QBM application security settings.
Timeout during permission check	Confirm QBMServer is running, the database is reachable, and QBMWServices can contact the configured server and SQL instance.
Firewall or network failure	Confirm local firewall rules, tunnel routing if used, and that the correct endpoint is being tested.

Installation Checklist

Published files exist in the intended QBMWServices folder.
appsettings.json contains the correct product key and service settings.
QBMWServices is installed as a Windows service.
The service is running and configured for the expected startup behavior.
Port 8053 is listening locally.
URL reservation exists if Windows requires it.
Firewall allows the required local or private network traffic.
QBMServer is running on the configured port, commonly 8051 for web bridge testing.
QSalesView, QClock, or the target web app can log in and validate application permissions.