Set up the administration app on a workstation

You receive the administration app as a ZIP file, such as GatewayManager-<version>-share.zip. It contains everything a workstation needs: the app, the starter dbgwmgr.exe, and the app's libraries, including the ODBC driver. You don't install anything the traditional way: you extract the ZIP, and when the app starts, the starter sets it up for the signed-in Windows user. Nobody needs administrator rights for this, and with a share, every administrator gets the same version.

graph LR
    subgraph L["Extracted ZIP (share or local folder)"]
        S["dbgwmgr.exe + dbgwmgr.bootstrapper.json"]
        D["deploy folder: app, WKL components, ODBC driver, .NET"]
    end
    subgraph W["Workstation, user profile"]
        F["Copy of the app per version"]
        R["Per-user setup: components, driver, trusted location"]
    end
    S -->|"1 reads"| D
    S -->|"2 copies and checks"| F
    S -->|"3 sets up"| R
    S -->|"4 opens"| F

Figure: What happens at startup. The starter reads the delivery in the deploy folder, copies the app to the user's profile and checks the copy, sets up what the user needs, and opens the copy. It never changes the extracted folder itself.

• Microsoft Access on the workstation. Supported: Access from Microsoft 365 or Office LTSC 2024, full version or Runtime, 32-bit and 64-bit. Older versions from Access 2010 on usually work as well, but they aren't acceptance-tested and no longer receive security updates from Microsoft.
• The address of the data service and a personal key to sign in. You get both from the person who runs the data service (see Create the first administrator, data service documentation).

You don't need to install the ODBC driver separately: the starter sets it up for each user. If the “Wkl OData” driver is already installed for the whole computer, the app uses that one.

1. Extract the ZIP. For several workstations, extract it to a file share, such as \\server\apps\GatewayManager; for a single workstation, a local folder is enough. Don't change any file in it.
2. Set permissions (share only). People who use the app need read access only. Grant write access only to the people who put new versions in place (see Notes, “Write access to the folder”).
3. Start the app. Double-click dbgwmgr.exe, or give the administrators a shortcut to it.

Result: On every start, the starter shows its steps in a full view. On the first start, it copies the app to the user's profile, sets up the components and the driver for the user, and makes the folder with the copies a trusted location in Access. Then the app opens with its sign-in card. Access doesn't ask whether it may run code (see Notes). Next, sign in to the administration app.

If the starter can't start the app, it shows a code and a message. To run the same check without starting the app, run dbgwmgr.exe /diagnose (the WKL Bootstrapper starter) in the extracted folder. If the first line reads 0 Ok, the app will start; otherwise the line shows the code, such as 20 if Access is missing. /diagnose doesn't change anything on the computer. What each code means and what to do is covered in Troubleshooting (WKL Bootstrapper documentation).

A new version also comes as a ZIP. Extract it to an empty folder first, then copy its contents over the existing folder, with deploy\app-manifest.json last: that file is how the starter recognizes the new version, and everything else must be in place before that file arrives. The next time administrators start the app, they get the new version; a copy that's still open isn't touched.

First, the user removes their data on this computer:

1. They sign in.
2. They select Lokale Daten entfernen (Remove local data) at the bottom of the navigation bar.
3. They confirm with Ja (Yes).

Result: The app signs the user out and removes what it stored on this computer for their Windows account: the settings (address, sign-in method, list layouts) including the folder %APPDATA%\The White Knight Labs\GatewayManager, and every key stored for the administration in Windows Credential Manager, for every address. The sign-in then shows empty fields. The data in the gateway (persons, keys, logs) doesn't change.

The starter removes everything it set up for the user; see How to: Remove an application from a PC (WKL Bootstrapper documentation).

If the user can no longer sign in, remove their data by hand: the folder %APPDATA%\The White Knight Labs\GatewayManager and, in Windows Credential Manager (Windows Credentials, Generic Credentials), every entry that starts with Wkl.Data.OData.Odbc: and ends with /admin/v1/odata/. Other Wkl.Data.OData.Odbc: entries belong to data connections of other applications and stay.

• Trusted location: Access runs code from a database in a trusted location without asking. The starter therefore makes the folder with the copies in the user's profile a trusted location. Whatever is in that folder runs with the user's rights; the folder is protected because only the user can write to their own profile and the starter only places checked copies. A group policy that turns off trusted locations prevents the app from starting (code 50). Details: What the starter writes and reports (WKL Bootstrapper documentation).
• Write access to the folder: The starter checks every copy against the delivery and refuses to start one that doesn't match (code 42). This protects against incomplete or accidentally modified files, but not against someone who can write to the folder: they can replace the app. Treat write access to the folder as seriously as administrator rights in the app.
• No code signing: The app isn't code-signed, so Windows SmartScreen and application control (AppLocker, WDAC) may warn about it or block it. Distribute it only from a source you trust.
• Going back to the previous version: In the starter's settings (dbgwmgr.exe /settings), select the previous version on the app's page and start it.
• Other WKL applications: The app comes with release 2.x of the WKL components. A Windows user has either a 1.x or a 2.x release registered, never both. If IT or another product registered a 1.x release that another app still needs, the starter doesn't replace it and reports code 37; see The application was made for another generation of the WKL components (code 37) (WKL Bootstrapper documentation).
• No passwords in the folder: The app gets the address and credentials only on the sign-in card; the extracted folder contains no credentials.
• Edition for 32-bit Office: This delivery contains the edition for 32-bit Office (full version or Runtime). The starter rejects 64-bit Access with a message (code 21) instead of opening the app; see Troubleshooting. 64-bit Office needs its own edition (dbgwmgr_x64.accde/.accdr); ask the manufacturer for it.

• Prerequisites (data service documentation): what the server needs
• Sign in to the administration app: the next step
• Create the first administrator (data service documentation): the first administrative access