Comarch Optima — installation

The integration runs on the Windows host where Comarch ERP Optima is installed. It connects to the Optima MS SQL database (read), to Optima’s COM API (write), and reaches Sancho WMS over the cloud message bus (TLS RabbitMQ).

The component ships as a single zip published per DEPLOY_ENV:

Channel	Zip	Installer
dev	https://download.sancho-wms.pl/dev/latest/comarch-optima.zip	https://download.sancho-wms.pl/dev/latest/comarch-optima-install.ps1
prod	https://download.sancho-wms.pl/prod/latest/comarch-optima.zip	https://download.sancho-wms.pl/prod/latest/comarch-optima-install.ps1

Builds are also pinned per commit under <channel>/<short-sha>/... (immutable).

Prerequisites

• 64-bit Windows 10 1607 or Windows Server 2016+ with TLS 1.2.
• PowerShell 5.1 or newer, running as Administrator.
• Comarch ERP Optima installed on the same host (the integration uses the local COM API).
• Outbound access to download.sancho-wms.pl (image download) and to Sancho’s RabbitMQ host on the TLS port.

What to prepare before running the installer

1. SQL Server login (read Optima database). In SQL Server Management Studio, enable mixed-mode authentication (SQL Server and Windows Authentication mode), create a SQL login (e.g. sancho), and grant the db_datareader role on both CDN_KNF_Konfiguracja and the company database. Restart the SQL Server service after switching auth modes.

2. Optima operator. An operator account with rights to create documents and product cards — used by the COM API for writes. Note the operator login and password.

3. AMQP credentials. Host, user, password, and virtual host for RabbitMQ — issued by Sancho when the integration is activated. Without these the installer cannot finish configuration.

COM API bitness

SanchoWMSComarchOptimaCOM.exe is 64-bit and requires a 64-bit Optima installation (2026+, 64-bit COM API). Legacy 32-bit Optima installs are not supported by the shipped build — a bitness mismatch fails CoCreateInstance with 0x8007007E (ERROR_MOD_NOT_FOUND). The Optima operator account must have the necessary rights in the local Optima installation.

Installation

Run from an elevated PowerShell prompt on the Windows host where Comarch Optima is installed:

prod

irm https://download.sancho-wms.pl/prod/latest/comarch-optima-install.ps1 | iex

dev

irm https://download.sancho-wms.pl/dev/latest/comarch-optima-install.ps1 | iex

What the installer does

1. Verifies prerequisites: Administrator, PowerShell 5.1+, 64-bit Windows 10 1607 / Server 2016 or newer, TLS 1.2.

2. Downloads the channel’s comarch-optima.zip to %TEMP% and logs the SHA-256 fingerprint.

3. Prompts for MSSQL / Optima operator / AMQP credentials (secrets via Read-Host -AsSecureString).

4. Installs binaries to C:\Program Files\SanchoWMS\ComarchOptima\bin\.

5. Writes the .env to C:\ProgramData\SanchoWMS\ComarchOptima\.env.

6. Registers two Windows services via NSSM (auto-start): SanchoWMSComarchOptima (the integration) and SanchoWMSComarchOptimaUpdater (auto-upgrade poller).

7. Starts both services.

Auto-update

SanchoWMSComarchOptimaUpdater polls <channel>/latest/comarch-optima.zip hourly via a HEAD request. When the response ETag changes, it downloads the new zip, stops SanchoWMSComarchOptima, swaps SanchoWMSComarchOptima.exe + SanchoWMSComarchOptimaCOM.exe + duckdb.dll (keeping .previous copies for rollback), and restarts the service. If the new build doesn’t reach Running within 30 s, the updater restores the previous binaries and records the failing build’s ETag in state\last-failed-etag.txt — that build is skipped until a new one is published.

The updater does not swap nssm.exe, itself (SanchoWMSComarchOptimaUpdater.exe), or the .env schema — those self-lock or require interactive input, and are only refreshed by a manual re-run of the installer (which stops both services before swapping).

Auto-update state:

Purpose	Path
Last-seen ETag (deletion forces re-check)	C:\ProgramData\SanchoWMS\ComarchOptima\state\last-etag.txt
ETag of the last failed upgrade (deletion allows retrying the same build)	C:\ProgramData\SanchoWMS\ComarchOptima\state\last-failed-etag.txt
Updater logs (NSSM-captured service log rotated at 10 MB)	C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-updater.log (the updater’s own log), comarch-optima-updater-service.log (merged NSSM stdout + stderr)

Opt out of auto-updates:

Set-Service SanchoWMSComarchOptimaUpdater -StartupType Disabled
Stop-Service SanchoWMSComarchOptimaUpdater

Manual upgrade

Re-run the same one-liner. The installer detects the existing services, stops both, swaps all binaries (including nssm.exe and SanchoWMSComarchOptimaUpdater.exe), preserves .env, and restarts both. Any new key added to .env.example is prompted interactively and appended to the existing .env.

Uninstall

irm https://download.sancho-wms.pl/prod/latest/comarch-optima-install.ps1 -OutFile $env:TEMP\install.ps1
& $env:TEMP\install.ps1 -Uninstall

Removes both services and deletes C:\Program Files\SanchoWMS\ComarchOptima\ and C:\ProgramData\SanchoWMS\ComarchOptima\ (.env, logs, state). No partial uninstall — back up .env first if you plan to reinstall later.

Configuration (.env)

The .env file lives at C:\ProgramData\SanchoWMS\ComarchOptima\.env. Edits require a restart of the main service:

Restart-Service SanchoWMSComarchOptima

Logging

Key	Required	Default	Purpose
LOG_PRETTY	no	false	true enables Pino pretty output (interactive use only)
LOG_LEVEL	no	info	Pino log level (trace, debug, info, warn, error, fatal, silent)
LOG_FILE	no	logs\comarch-optima-integration.log	Integration log path (relative to working directory, i.e. ProgramData). Rotated daily; 14 most recent days kept.

MSSQL (Optima database)

Key	Required	Default	Purpose
MSSQL_SERVER	yes	localhost	Optima SQL Server host
MSSQL_INSTANCE	no	OPTIMA (installer prompt default)	Named instance; blank = default instance
MSSQL_DATABASE	no	(default)	Database name; blank uses the SQL login’s default
MSSQL_USER	yes	sancho	SQL login
MSSQL_PASSWORD	yes	—	SQL password

Optima (COM writes)

Key	Required	Default	Purpose
OPTIMA_OPERATOR_NAME	no	—	Optima operator used for COM-API writes
OPTIMA_OPERATOR_PASSWORD	no	—	Operator password (blank to skip)
OPTIMA_FIRM_INDEX	no	0 (written by the installer)	0-based position of the company in Optima’s firm list (first/only company = 0). Look it up in CDN_KNF_Konfiguracja.CDN.Bazy (ROW_NUMBER() OVER (ORDER BY Baz_BazID) - 1)
OPTIMA_LICENSE_MODEL	no	auto	Licence model of the installed Optima key: classic (HASP / Key Manager key), subscription (service model), or auto (tries classic, then subscription). A classic Handel key must use classic — the subscription fallback fails with “Nie masz uprawnień do korzystania z modułu [Podstawowy]”
OPTIMA_SERVE	no	true	Persistent COM session (“serve mode”): true starts the COM CLI once and holds one Optima login with auto-reconnect; false spawns the CLI per request

AMQP (Sancho message bus)

Key	Required	Default	Purpose
AMQP_HOST	yes	—	Sancho-side RabbitMQ host
AMQP_PORT	yes	5671	RabbitMQ port (TLS)
AMQP_VHOST	yes	/	Virtual host
AMQP_USER	yes	—	RabbitMQ user (per-customer)
AMQP_PASSWORD	yes	—	RabbitMQ password

Host paths

Purpose	Path
Binaries (SanchoWMSComarchOptima.exe, SanchoWMSComarchOptimaCOM.exe, SanchoWMSComarchOptimaUpdater.exe, duckdb.dll, nssm.exe)	C:\Program Files\SanchoWMS\ComarchOptima\bin\
Configuration (.env)	C:\ProgramData\SanchoWMS\ComarchOptima\.env
Integration log (Pino, rotated daily, 14 days)	C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-integration.log (+ .1 … .14 for rolled days)
Main service merged stdout + stderr (NSSM, rotated at 10 MB)	C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-integration-service.log
Updater logs + NSSM stdout	C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-updater.log, comarch-optima-updater-service.log
Auto-update state	C:\ProgramData\SanchoWMS\ComarchOptima\state\last-etag.txt, last-failed-etag.txt
Install transcript	C:\Program Files\SanchoWMS\ComarchOptima\install.log

Operations

Get-Service Sancho*
Restart-Service SanchoWMSComarchOptima
Get-Content -Wait 'C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-integration.log'
Get-Content -Wait 'C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-integration-service.log'
Get-Content -Wait 'C:\ProgramData\SanchoWMS\ComarchOptima\logs\comarch-optima-updater.log'

After editing .env, run Restart-Service SanchoWMSComarchOptima to apply changes.

Troubleshooting

SQL login failed (Login failed for user)

Mixed-mode auth is not enabled, the login doesn’t exist, or it lacks the db_datareader role on the configuration database CDN_KNF_Konfiguracja or on the company database. Open SSMS, check Server Properties → Security, confirm “SQL Server and Windows Authentication mode” is active, and verify the user is mapped to both databases.

Failed to connect to AMQP / TLS handshake error

Check the host firewall and network — AMQP_PORT (5671) must be reachable outbound. Some Windows Server installs disable system-level TLS 1.2 — check SCHANNEL registry settings. AMQP credentials are issued per-customer — if the password is lost, request a new one from Sancho.

Updater isn't picking up a new build

Delete C:\ProgramData\SanchoWMS\ComarchOptima\state\last-etag.txt to force a re-check and Restart-Service SanchoWMSComarchOptimaUpdater. If a previous upgrade attempt failed, that build’s ETag is stored in state\last-failed-etag.txt and the build is skipped — delete that file too to retry the same build. Logs: comarch-optima-updater.log will show whether the HEAD request reached download.sancho-wms.pl.

CO_E_CLASSSTRING (0x800401F3) or COM ProgID error

The COM subprocess can’t load the Optima class. Common causes: the operator account lacks rights in the local Optima install, the Optima installation is broken, or the COM API isn’t registered (launch Optima interactively once to register classes). Check comarch-optima-integration.log — it will show the exact class name and error code.

Service doesn't start after reboot

Get-Service SanchoWMSComarchOptima reports Stopped. Check comarch-optima-integration-service.log — the usual causes are: SQL login failure (bad .env after an edit), the updater can’t reach download.sancho-wms.pl on startup (not fatal — it retries), or a missing .env key after a partial edit.