Out of scope: Crystal Reports (.rpt) files must be replaced by the vendor separately.
The per-PC locale fix is a separate client-side script.
Ready
WSFabLIC is the shared licence database used by all units.
The client copies SysParm into it at every logon. All three checks below must pass.
What is checked
- WSFabLIC exists — the shared licence database
- Companies row — a row where
Directory = unit code - SysParm defaults — every NOT NULL column not in the client’s 14-column INSERT has a DEFAULT, preventing “Unable to establish Licence Details” at logon
The 14 columns the client provides
CompanyCode, CompanyName, Address1,
Address2, Address3, PCode, Tel1, Tel2,
Fax1, Contact, Contact2, CompanyNo,
VATNo, CompanyLogo
Applies
DBSQLWSFAB001.sql to a unit database.
In schema-from-MDB mode the tool automatically pre-widens
TableDict.IDTable and DataJoin.ID1/ID2 to
nvarchar(4) before running the script. The benign
PIT_Ooutlet duplicate on re-run is handled automatically.
Ready
Objects created by this script
StagingSalesStagingSalesTakingsTTExclVendors- TableDict / DataDict / ScreenDict entries
- TrimTrax columns
Known quirks handled automatically
- Dict column pre-widen: IDTable and ID1/ID2 widened to nvarchar(4), covering indexes dropped first
- PIT_Ooutlet duplicate: the script’s idempotency guard has a typo; the resulting duplicate key on re-run is benign and is reported but not treated as an error
Use these tools when running WSUpgrade locally on a machine. Firewall rules are created
on this machine (where WSUpgrade is installed), not on a remote server.
Windows Firewall — Inbound Rule
Existing Relevant Rules
Click Refresh to load…
When to use this
- You installed WSUpgrade locally and want colleagues on the same network to access the web UI
- Create a rule for port 5001 (or whichever port WSUpgrade is running on)
- They then browse to
http://<your-ip>:5001
Requires admin rights
- WSUpgrade must be running as Administrator (or as SYSTEM via the scheduled task) for this to succeed
- If it fails with an access error, restart WSUpgrade as Administrator
Connection Status
Checking…
FortiToken Code
FortiToken For Windows is not running or the code could not be read automatically. Open the FortiToken For Windows app and enter the 6-digit code below:
VPN Configuration
How it works
- Fill in the VPN server, username, and password and click Save Config
- Make sure FortiToken For Windows is open on this machine
- Click Connect - WSUpgrade reads the 6-digit code from the FortiToken app automatically
- If the app cannot be read, a box appears for you to enter the code manually
- Once connected, use
jhb-sql(or your internal server name) in the SQL Server field
Requires openfortivpn
- Download
openfortivpn.exefor Windows from GitHub - Place it at
C:\WSUpgrade\Tools\openfortivpn.exe - Checking…
Certificate fingerprint
- Leave blank on first use — openfortivpn will show the fingerprint in its error output
- Copy that fingerprint into this field and save, then connect again
WSUpgrade must run on a machine that can reach your SQL Server.
Install it locally on the client site, or on any machine on the same network as SQL Server.
Open Local Instance
If WSUpgrade is already running on this machine, open it here:
🔗 Open localhost:5001Install as Windows Service
Registers WSUpgrade as a scheduled task so it starts automatically at boot. Requires Administrator or SYSTEM rights.
SQL Server Express 2022
Checking…
Instance:
SA user:
saSA password:
Connection string:
📄 Deploy WS Reports (WSRepSQL)
Extracts the bundled WSRepSQL report files and copies them to the WorkSmart reports folder. Existing files are only overwritten if the bundled version is newer.
How to install locally
- Copy the WSUpgrade folder to
C:\WSUpgradeon the target machine - Open this Install tab and click Install as Service
- WSUpgrade starts automatically at boot on port 5001
- Colleagues on the same network open
http://<machine-ip>:5001
Service management
Stop-ScheduledTask -TaskName 'WSUpgrade'
Start-ScheduledTask -TaskName 'WSUpgrade'
Unregister-ScheduledTask -TaskName 'WSUpgrade' -Confirm:$false
Connecting to SQL Server
- WSUpgrade connects to SQL from the machine it runs on
- If SQL Server is
jhb-sql, run WSUpgrade on a machine inside that network - The hosted version at wsupgrade.khanyisa.net cannot reach private-network SQL servers unless connected via VPN
SQL Server Express
- Free Microsoft SQL Server, suitable for WorkSmart databases
- Installs with mixed-mode auth (SA login enabled)
- TCP/IP enabled on port 1433
- Requires internet access to download (~300 MB)
- Takes 3–8 minutes to complete
After SQL Express is installed
- Set SQL Server in the top bar to
.\SQLEXPRESS - Login:
saPassword:WSUpgrade@2024! - A reboot may be needed if the SA connection fails immediately after install
Click any section to expand it. Each section covers one workflow from start to finish.
1
Single Unit Conversion
Convert one WorkSmart MDB or ACCDB file to SQL Server
- 1Set the SQL Server connection in the bar at the top of the page — server address, SQL login, password. Click Test to confirm it works before continuing.
- 2Go to the Single Unit tab. Paste the full path to the MDB, ACCDB, or ZIP into MDB path:C:\Units\D0191\WSFab.mdb
- 3The Unit code is auto-detected from the parent folder name (e.g.
D0191). Correct it if needed. - 4The Database name defaults to
WSFab+ unit code (e.g.WSFabD0191). Change only if your naming differs. - 5Choose Schema from MDB (standard — derives columns and types from the Access file). Use Data-only only if the SQL schema already exists and you just need to reload data.
- 6Click Convert. Progress appears on the right — each table card shows row counts as it loads. Green = success, red = error on that table.
- 7When complete, download the log file, CSV report, or SQL script using the links below the progress panel.
ACE driver error on startup? Install Microsoft Access Database Engine 2016 Redistributable (x64) on the machine running WSUpgrade, then restart the server.
Connection fails? Make sure SQL Server has TCP/IP enabled and the firewall allows inbound TCP 1433. Use the Setup tab to create that rule in one click.
2
Batch Conversion
Convert an entire folder of units in one run
- 1Organise files so each unit has its own sub-folder containing
WSFab.mdborWSFab.zip:C:\Units\ D0191\WSFab.mdb D0192\WSFab.mdb D0193\WSFab.zip - 2Set SQL Server in the top bar, then go to the Batch tab.
- 3Enter the Root folder path (e.g.
C:\Units) — the folder that contains all unit sub-folders. - 4Enter the Access password if all MDB files share one. Leave blank if none.
- 5Use Include filter (regex) to process only matching folders — e.g.
^Dfor D-prefix units only. Leave blank to process all sub-folders. - 6Click Start Batch. Each unit appears as a row — green = done, red = failed. A summary CSV is saved in the root folder when the batch finishes.
Resuming a partial run: Leave Force redo unchecked to skip units that already succeeded and re-run only the failures. Tick it to redo everything from scratch.
3
Licence Fix
Repair WSFabLIC so the WorkSmart client can log on
- 1Set SQL Server in the top bar, then go to the Licence tab.
- 2Enter the unit code (e.g.
D0191) and unit name (full company name — this populates the Companies row). - 3Enter the unit database name (e.g.
WSFabD0191) — required for the Simulate Logon test. - 4If WSFabLIC does not exist yet, select
WSFABLIC.sqlfrom the dropdown to create it from the vendor script. - 5Click Check Status to see which of the three checks are failing:
• WSFabLIC database exists • Companies row present • SysParm NOT NULL defaults complete - 6Click Fix Issues to repair all failing checks automatically in one step.
- 7Click Simulate Logon to run the WorkSmart client’s SysParm sync transaction (rolled back after the test). A green result means the client will be able to log on.
Why does logon fail? The WorkSmart client does a 14-column INSERT into SysParm at every logon. If any other NOT NULL column has no DEFAULT, the INSERT fails with “Unable to establish Licence Details”. Fix Issues adds those defaults automatically.
4
POS Upgrade
Apply DBSQLWSFAB001.sql to a unit database
- 1Set SQL Server in the top bar, then go to the POS Upgrade tab.
- 2Enter the unit code and the target database name.
- 3Select
DBSQLWSFAB001.sqlfrom the dropdown. To add it, place the file in theSQL Scriptsfolder next to WSUpgrade and refresh. - 4Leave Schema-from-MDB mode checked — this pre-widens
TableDict.IDTableandDataJoin.ID1/ID2tonvarchar(4)before running the script, which is required when the schema was derived from the MDB. - 5Click Check Objects to see what the script will create. If all objects are present, no upgrade is needed.
- 6Click Apply Upgrade to run the script and create the missing objects.
PIT_Ooutlet duplicate warning is expected. The vendor script has a typo in its idempotency guard. This creates a benign duplicate key on re-run — it is shown as a warning but not treated as a hard error.
5
VPN — Connect to Empact Network
Reach jhb-sql and other private servers from the hosted WSUpgrade
- 1Go to the VPN tab. Fill in: server
vpn.empactgroup.co.za, port10443, usernameWorksmart1, and the VPN password. Click Save Config. - 2Open FortiToken For Windows on the machine running WSUpgrade — the app must be running and showing the 6-digit token.
- 3Click Connect. WSUpgrade reads the OTP from the FortiToken app automatically and dials the VPN.
- 4If the OTP cannot be read automatically, a box appears — type the 6-digit code from the FortiToken app and click Connect with this code.
- 5When the status chip turns green, set SQL Server (top bar) to
jhb-sql(or the internal IP), click Test, and run conversions as normal.
Why VPN? The hosted server (wsupgrade.khanyisa.net) has no route to
jhb-sql — it sits on Empact’s private LAN. The VPN creates a tunnel from the hosted server into that network.openfortivpn fallback: If FortiClient automation fails, WSUpgrade tries
openfortivpn.exe. Place that file at C:\WSUpgrade\Tools\openfortivpn.exe. On the first connect, copy the certificate fingerprint from the error output into the VPN config and reconnect.6
Install WSUpgrade Locally
Run WSUpgrade on a machine at the client site
- 1Copy the
WSUpgradefolder toC:\WSUpgradeon the machine that can reach the SQL Server. - 2On that machine, open PowerShell as Administrator and run:Set-ExecutionPolicy Bypass -Scope Process C:\WSUpgrade\Start-WSUpgrade.ps1
- 3Open
http://localhost:5001in a browser on that machine to confirm it’s running. - 4Go to the Install tab and click Install as Service. WSUpgrade will now auto-start at boot.
- 5Go to the Setup tab and create an inbound firewall rule for port
5001. Colleagues on the same network can then openhttp://[machine-ip]:5001.
Use the hosted version instead whenever the machine has a route to SQL Server via VPN — no local install needed. Local install is only necessary when SQL Server is on a network with no internet route.
7
Install SQL Server Express
Set up a free SQL Server instance on the local machine
- 1Make sure the machine has an internet connection — the installer downloads approximately 300 MB from Microsoft.
- 2Go to the Install tab, scroll to the SQL Server Express 2022 card, and click Install SQL Express.
- 3Wait 3–8 minutes. Do not close the browser or shut down the machine. The progress bar and log update every 2 seconds.
- 4When complete, connection details appear automatically:Instance : MACHINENAME\SQLEXPRESS SA user : sa Password : WSUpgrade@2024!
- 5Set the top bar: server =
.\SQLEXPRESS, username =sa, password =WSUpgrade@2024!. Click Test to confirm the connection. - 6You can now convert MDB files directly to the local SQL Express instance — no network SQL Server required.
Connection fails after install? A Windows restart is sometimes required for the SA login to activate. After rebooting, WSUpgrade auto-restarts and the connection will work.