Interface Service

The Commander4j Interface Service is a background process that handles all automated integration between Commander4j and external systems. It monitors for incoming XML messages from ERPs and other systems, generates outbound XML messages, triggers scheduled reports, and drives automatic labelling. It is designed to run continuously on a server as a Windows service.

The service is a separate optional component — the main Commander4j desktop application does not need to be running for the Interface Service to operate.

What the Service Does

When started, the Interface Service logs into the Commander4j database using the built-in interface account and starts five background threads:

Thread	Purpose
Inbound Message Thread	Monitors the configured inbound directory for XML message files from external systems. Processes each file against the appropriate message handler and writes results to `SYS_INTERFACE_LOG`.
Outbound Message Thread	Picks up XML messages queued in the database for transmission to external systems and writes them to the configured outbound directories.
Recovery Thread	Monitors the recovery path for messages that failed processing and re-attempts them on a schedule.
Reporting Thread	Fires scheduled reports at their configured times and distributes the output.
Auto Labeller Thread	Drives automatic pallet labelling triggers that are not handled by AutoLab4j or LabelServer4j.

At a configured daily housekeeping time the service gracefully stops all threads, performs maintenance tasks, and restarts. Email notifications are sent on startup, shutdown, and housekeeping if configured.

Prerequisites

Host Configuration

The Interface Service identifies which database to connect to by looking for a host entry in hosts.xml with a uniqueId of service. This host entry must be created using Setup4j before the service will start. Without it, the service logs an error and exits immediately.

Interface User Account

The service logs into Commander4j using the application account interface with password interface. This account must exist and be enabled in the Commander4j user list. It is created automatically when the schema is initialised, but verify it has not been disabled or had its password changed.

Installing as a Windows Service

The native install package includes Service4j.exe, a service-mode launcher built with install4j. This executable manages the Windows service directly — no additional wrapper is required.

All service commands must be run from an elevated command prompt (Run as Administrator).

The default Windows service name is Service4j (the launcher name defined in the installer). You can specify a different name as an optional second parameter. If a custom name is used at install time, that same name must be passed to every subsequent command.

Command	Effect
`Service4j.exe /install`	Register as Service4j with automatic startup on boot
`Service4j.exe /install "Commander4j Interface"`	Register with a custom service name
`Service4j.exe /install-demand`	Register with manual startup only
`Service4j.exe /start`	Start the service
`Service4j.exe /stop`	Stop the service (waits for graceful shutdown)
`Service4j.exe /restart`	Restart the service
`Service4j.exe /status`	Query status (exit code: 0 = running, 3 = stopped)
`Service4j.exe /uninstall`	Remove the service registration

If a custom service name was used at install time, append it to all subsequent commands:

Service4j.exe /start "Commander4j Interface"
Service4j.exe /stop "Commander4j Interface"
Service4j.exe /uninstall "Commander4j Interface"

Once installed, the service also appears in the Windows Services management console (services.msc).

Testing Before Installing as a Service

Before committing to service installation, run the Interface Service in a visible console window using:

Interface4j.exe

This runs the same application code and all log output is written to the console window. Use this mode to confirm that the correct host is found, the interface account logs in, and all threads start successfully.

Email Notifications

If configured, the service sends email alerts at key lifecycle events:

Event	Trigger
Startup	Service has connected to the database and all threads are running
Shutdown	Service has stopped all threads and disconnected
Housekeeping	Daily maintenance cycle has run
Statistics	Daily statistics summary (if enabled)

Email notification is controlled by the system key INTERFACE EMAIL NOTIFY (true/false) and the recipient list in INTERFACE ADMIN EMAIL. Both are configured in the Commander4j system keys administration screen.

Monitoring

All activity is written to the Log4j log file in the logs/ directory. The Interface Log screen in the Commander4j desktop application provides a searchable view of every message processed — inbound and outbound — including status, error details, and message content.

Failed messages can be resubmitted for reprocessing from the Interface Log screen without re-sending the original file.