Commander4j - User contributions [en-gb]

File:SFTPTransfer.jpg

2026-04-24T17:54:03Z

Dgarratt:

SFTPTransfer

2026-04-24T17:53:51Z

Dgarratt:

SFTPTransfer is a background file transfer service that moves files between a local filesystem and a remote SFTP server. It is a standalone Java application that runs either as a headless background service or as a desktop application with a minimal GUI, and supports both uploading (PUT) and downloading (GET) in independent threads.

SFTPTransfer replaces the earlier sftpSend and sftpGet tools with a unified, configurable service.

== Purpose ==

SFTPTransfer automates recurring file transfers between Commander4j and external systems — for example, uploading despatch notifications to a customer portal or downloading order files from a supplier. It runs continuously, polling for new files at a configurable interval, and handles authentication, retry, backup, and archiving without operator involvement.

[[File:SFTPTransfer.jpg|800px]]

== Startup Modes ==

SFTPTransfer supports two startup modes selected at launch time:

{| class="wikitable"
|-
! Mode !! Behaviour
|-
| '''Start desktop''' || Opens a small GUI window. Transfer threads start in a paused state; the operator must click Start in the interface to begin polling. Useful for testing configuration.
|-
| '''Start service''' || Headless — no GUI window. Transfer threads start immediately on launch. Suitable for production deployment as a background service or scheduled task.
|}

On Windows, the native install package includes <code>sftpTransfer_Service.exe</code>, which manages the Windows service directly — see [[#Installing as a Windows Service|Installing as a Windows Service]] below. On Linux/macOS, use systemd, launchd, or nohup.

== Configuration Files ==

All configuration is held in XML files under the <code>xml/config/</code> directory. Changes require a service restart unless hot-reload is triggered (see below).

=== sftp_common.xml ===

Shared settings used by all transfer threads:

{| class="wikitable"
|-
! Setting !! Description
|-
| Poll interval || How often (in seconds) each thread checks for new files. Default: 10 seconds.
|-
| Backup retention || Number of days to keep backed-up files before automatic deletion.
|-
| Log level || Logging verbosity passed to Log4j.
|}

=== sftp_put.xml ===

Configures one or more PUT (upload) profiles. Each profile defines:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether this profile's thread is active.
|-
| Local path || Local directory to watch for outbound files.
|-
| File mask || Wildcard pattern to match files (e.g. <code>*.xml</code>, <code>order_*.csv</code>). Uses Apache Commons IO WildcardFileFilter.
|-
| Remote host || SFTP server hostname or IP address.
|-
| Remote port || SFTP port (default: 22).
|-
| Remote path || Target directory on the remote server.
|-
| Username || SFTP login username.
|-
| Password || AES-encrypted password (see [[#Password Encryption|Password Encryption]]).
|-
| Private key path || Path to SSH private key file (alternative to password authentication).
|-
| Backup path || Local directory where successfully uploaded files are moved.
|-
| Error path || Local directory where files that failed to upload are moved.
|}

=== sftp_get.xml ===

Configures one or more GET (download) profiles. Each profile defines:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether this profile's thread is active.
|-
| Remote host || SFTP server hostname or IP address.
|-
| Remote port || SFTP port (default: 22).
|-
| Remote path || Directory on the remote server to poll for incoming files.
|-
| File mask || Wildcard pattern matched against the remote file listing (server-side ls).
|-
| Local path || Local directory where downloaded files are saved.
|-
| Username || SFTP login username.
|-
| Password || AES-encrypted password.
|-
| Private key path || Path to SSH private key file.
|-
| Delete after download || Whether to delete the remote file after successful download.
|-
| Backup path || Local directory where a copy of each downloaded file is kept.
|}

=== jsch_properties.xml ===

Advanced SSH session parameters passed directly to the JSch library. Used to control host key checking, preferred algorithms, and connection timeouts. In most deployments this file can be left at its defaults.

=== email_properties.xml ===

SMTP settings for error notification emails. When a transfer failure occurs and email notification is enabled, SFTPTransfer sends an alert to the configured address. Fields include SMTP host, port, sender address, recipient address, and AES-encrypted SMTP password.

== Installing as a Windows Service ==

The native install package includes <code>sftpTransfer_Service.exe</code>, 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 '''sftpTransfer_Service''' (the launcher name defined in the installer). You can specify a different name as an optional second parameter — useful if you need to run multiple instances on the same machine. If a custom name is used at install time, that same name must be passed to every subsequent command.

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>sftpTransfer_Service.exe /install</code> || Register as '''sftpTransfer_Service''' with automatic startup on boot
|-
| <code>sftpTransfer_Service.exe /install "My SFTP Service"</code> || Register with a custom service name
|-
| <code>sftpTransfer_Service.exe /install-demand</code> || Register with manual startup only
|-
| <code>sftpTransfer_Service.exe /start</code> || Start the service
|-
| <code>sftpTransfer_Service.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>sftpTransfer_Service.exe /restart</code> || Restart the service
|-
| <code>sftpTransfer_Service.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>sftpTransfer_Service.exe /uninstall</code> || Remove the service registration
|}

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

sftpTransfer_Service.exe /start "My SFTP Service"
sftpTransfer_Service.exe /stop "My SFTP Service"
sftpTransfer_Service.exe /uninstall "My SFTP Service"

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

=== Testing Before Installing as a Service ===

The native install package also provides two alternatives for testing:

{| class="wikitable"
|-
! Launcher !! Mode !! Use case
|-
| <code>sftpTransfer_Console.exe</code> || Console (headless) || Runs the service logic in a visible console window — useful for watching log output during initial configuration
|-
| <code>sftpTransfer.exe</code> || Desktop GUI || Opens the GUI window in Start desktop mode — transfer threads start paused, allowing configuration to be verified before enabling transfers
|}

== Authentication ==

SFTPTransfer supports two authentication methods, configured per profile:

{| class="wikitable"
|-
! Method !! How to configure
|-
| Password || Set the <code>Password</code> field in the profile to an AES-encrypted value. Leave the private key path empty.
|-
| SSH private key || Set the <code>Private key path</code> field to the path of a PEM-format private key file. The password field is ignored.
|}

Both methods use the JSch 2.x SSH library with Bouncy Castle as the cryptographic provider.

=== Password Encryption ===

Passwords stored in configuration files are AES-encrypted. Plain-text passwords are never stored on disk. To encrypt a password, use the password utility included with Commander4j (the same utility used for database passwords in Commander4j's own configuration).

== File Transfer Behaviour ==

=== PUT (Upload) ===

# SFTPTransfer polls the local input directory every 10 seconds (configurable).
# Files matching the file mask are selected for upload.
# Each file is uploaded to the remote path using a temporary name with a <code>.tmp</code> extension.
# On successful transfer, the remote file is renamed to its final name (atomic rename — the remote system never sees a partial file).
# The local source file is moved to the backup directory.
# If the transfer fails, the file is moved to the error directory and an error is logged.

=== GET (Download) ===

# SFTPTransfer lists the remote directory every 10 seconds (configurable).
# Files matching the file mask are selected for download.
# Each file is downloaded to the local path using a <code>.tmp</code> extension.
# On successful download, the local file is renamed to its final name.
# If configured, the remote file is deleted after download.
# A backup copy is optionally saved to the local backup directory.

== Thread Architecture ==

When running, SFTPTransfer maintains the following threads:

{| class="wikitable"
|-
! Thread !! Purpose
|-
| TransferPUT || One thread per enabled PUT profile, each managing its own SFTP connection.
|-
| TransferGET || One thread per enabled GET profile, each managing its own SFTP connection.
|-
| EmailThread || Sends error notification emails asynchronously.
|-
| ArchiveThread || Periodically purges backup files older than the configured retention period.
|}

== Hot Configuration Reload ==

SFTPTransfer supports a configuration reload mode (<code>Mode_CONFIG_UPDATE</code>). When this mode is triggered, running threads re-read their configuration files without requiring a full service restart. This allows profile changes — such as updating a remote path or rotating credentials — to be applied with minimal disruption.

== Logging ==

All activity is written to the Log4j log file. The log records:

* Service startup and configuration loaded
* Each thread starting and its profile settings
* Every file detected, transfer attempted, and outcome
* Every remote connection attempt and disconnect
* File move operations (to backup or error directories)
* Errors and exceptions with full context

Log rotation and retention are configured in the Log4j configuration file included in the distribution.

== Dependencies ==

{| class="wikitable"
|-
! Library !! Version !! Purpose
|-
| JSch || 2.27.9 || SSH/SFTP client
|-
| Bouncy Castle || current || Cryptographic provider for JSch
|-
| Apache Commons IO || current || WildcardFileFilter for local file matching
|-
| Log4j || 2.25.3 || Logging
|}

See also: [[LabelServer4j]], [[Middleware4j]], [[Production Lines & Labellers]]

[[Category:Commander4j]]

ZPLRenderer

2026-04-24T16:34:15Z

Dgarratt:

ZPL Renderer is a desktop application that interprets ZPL (Zebra Programming Language) commands and renders them as a visual preview of what a label will look like when printed on a physical Zebra printer. It is a companion tool to Commander4j, LabelServer4j, and AutoLab4j.

== Purpose ==

ZPL is a text-based command language used to define label layouts, text, graphics, and barcodes for Zebra label printers. The commands are sent directly to the printer as a stream of characters and are not human-readable. ZPL Renderer allows you to:

* Load a ZPL file and see what the label will look like before sending it to a printer
* Listen on a network socket so that any application sending ZPL to that port renders the label on screen in real time
* Zoom in and out to examine label detail
* Preview multiple labels from a single ZPL stream
* Export the rendered label to PDF
* Print the rendered label directly from the application

[[File:ZPLRenderer.jpg|800px]]

== Running ZPL Renderer ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method.

Alternatively, ZPL Renderer can be run directly from the distribution archive. It is a Java 21 desktop (Swing) application:

java -jar zplrenderer.jar

On first launch it reads its configuration from <code>xml/config/config.xml</code>.

== Loading a ZPL File ==

Use the '''Open''' toolbar button to load a <code>.zpl</code> text file from disk. The label is rendered immediately. Use '''Refresh''' to reload the file after editing it externally.

Several example ZPL files are included in the <code>examples/</code> directory:

{| class="wikitable"
|-
! File !! Contents
|-
| example1.zpl || Shipping label with QR code, text, and graphics
|-
| example2.zpl || Complex layout with boxes, barcodes, and logo
|-
| barcodes.zpl || Showcase of all supported barcode types
|-
| pallet_labels.zpl || Pallet label examples typical of Commander4j output
|-
| fonts.zpl || Font size and style demonstration
|-
| shipping.zpl || Shipping label sample
|-
| character.zpl || Character set reference
|-
| grid.zpl || Layout grid for alignment reference
|}

== Network Socket Mode ==

ZPL Renderer can listen on a TCP/IP port and render any ZPL label stream sent to it. This allows Commander4j, LabelServer4j, or any other application to use ZPL Renderer as a virtual printer — sending ZPL to the socket and seeing the result on screen instead of printing to paper.

The default port is '''9100''' (the standard Zebra raw print port). The IP address and port are configured in <code>config.xml</code>. Enable listening using the '''Network''' button in the toolbar.

ZPL Renderer extracts complete label blocks from the stream, identified by the standard <code>^XA</code> (start of label) and <code>^XZ</code> (end of label) delimiters.

== Zoom ==

Use the zoom controls in the toolbar to scale the rendered label between 0.10× and 2.00×. The default zoom is configured in <code>config.xml</code> (default: 0.5×). This is useful for examining barcode detail or checking overall label proportions.

== Multiple Labels ==

When a ZPL file or network stream contains multiple labels, ZPL Renderer displays them as pages. Navigation controls allow stepping through each label. The maximum number of pages displayed is configurable (default: 3).

== Export and Print ==

* '''PDF Export''' — saves the rendered label as a vector PDF using Apache PDFBox
* '''Print''' — sends the rendered label to a system printer

== Supported ZPL Commands ==

ZPL Renderer supports over 100 ZPL commands. Key categories:

=== Label Setup ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^XA || Start of label
|-
| ^XZ || End of label
|-
| ^LL || Label length
|-
| ^LH || Label home (origin offset)
|-
| ^LT || Label top offset
|-
| ^PQ || Print quantity
|-
| ^CD || Change delimiter character
|-
| ^CC || Change caret character
|}

=== Text and Fields ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^FO || Field origin (X,Y position from top-left)
|-
| ^FT || Field typeset (X,Y position from bottom-left)
|-
| ^FD || Field data (the text content)
|-
| ^FS || Field separator
|-
| ^FR || Field reverse (inverted colours)
|-
| ^FW || Field orientation/rotation
|-
| ^FX || Comment (ignored in output)
|}

=== Fonts ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^A0–^AZ || Select font by ID
|-
| ^CF || Change default alphanumeric font
|-
| ^CI || Change international character set/encoding
|}

=== Graphics ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^GB || Graphic box (rectangle)
|-
| ^GC || Graphic circle
|-
| ^GD || Graphic diagonal line
|-
| ^GE || Graphic ellipse
|-
| ^GF || Graphic field (embedded image data)
|-
| ^GS || Graphic symbol
|}

=== Barcodes ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^BC || Code 128 / GS1-128 (EAN-128)
|-
| ^BE || EAN-13
|-
| ^B8 || EAN-8
|-
| ^B3 || Code 39
|-
| ^B2 || Interleaved 2 of 5
|-
| ^B1 || Code 11
|-
| ^BQ || QR Code
|-
| ^B7 || PDF417
|-
| ^B0 / ^BO || Aztec
|-
| ^BY || Bar code field defaults (width, ratio, height)
|}

Barcode rendering uses the OkapiBarcode library. GS1 application identifiers are interpreted from <code>xml/config/gs1_app_defs.xml</code>.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>:

{| class="wikitable"
|-
! Setting !! Description
|-
| Input folder || Default directory for ZPL file loading (default: <code>./examples</code>)
|-
| Port || Network socket port to listen on (default: 9100)
|-
| Default magnification || Starting zoom level (default: 0.5)
|-
| Max pages || Maximum number of label pages to display (default: 3)
|}

=== fonts.xml ===

Located at <code>xml/config/fonts.xml</code>, this file maps ZPL font IDs (0, A–Z) to TrueType font files and defines their pixel dimensions. This allows ZPL Renderer to simulate the fonts installed in a physical Zebra printer.

Included fonts: Bitstream Vera, Anonymous Pro, ATTriumvirate.

If your labels use fonts that differ from the defaults, edit <code>fonts.xml</code> to match the font metrics of your target printer.

== Relationship to Commander4j ==

Commander4j generates ZPL label streams for pallet and case labels. ZPL Renderer allows you to preview these labels before deploying them to production printers, and to verify that label templates produce the correct output after making changes to the template syntax. See [[Label Template Syntax]] and [[Zebra ZPL Label]] for information on ZPL label authoring within Commander4j.

See also: [[Zebra ZPL Label]], [[Label Template Syntax]], [[Printer Queues]], [[Production Lines & Labellers]]

[[Category:Commander4j]]

File:ZPLRenderer.jpg

2026-04-24T15:19:57Z

Dgarratt:

ZPLRenderer

2026-04-24T15:18:39Z

Dgarratt:

ZPL Renderer is a desktop application that interprets ZPL (Zebra Programming Language) commands and renders them as a visual preview of what a label will look like when printed on a physical Zebra printer. It is a companion tool to Commander4j, LabelServer4j, and AutoLab4j.

== Purpose ==

ZPL is a text-based command language used to define label layouts, text, graphics, and barcodes for Zebra label printers. The commands are sent directly to the printer as a stream of characters and are not human-readable. ZPL Renderer allows you to:

* Load a ZPL file and see what the label will look like before sending it to a printer
* Listen on a network socket so that any application sending ZPL to that port renders the label on screen in real time
* Zoom in and out to examine label detail
* Preview multiple labels from a single ZPL stream
* Export the rendered label to PDF
* Print the rendered label directly from the application

[[File:ZPLRenderer.png|800px]]

== Running ZPL Renderer ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method.

Alternatively, ZPL Renderer can be run directly from the distribution archive. It is a Java 21 desktop (Swing) application:

java -jar zplrenderer.jar

On first launch it reads its configuration from <code>xml/config/config.xml</code>.

== Loading a ZPL File ==

Use the '''Open''' toolbar button to load a <code>.zpl</code> text file from disk. The label is rendered immediately. Use '''Refresh''' to reload the file after editing it externally.

Several example ZPL files are included in the <code>examples/</code> directory:

{| class="wikitable"
|-
! File !! Contents
|-
| example1.zpl || Shipping label with QR code, text, and graphics
|-
| example2.zpl || Complex layout with boxes, barcodes, and logo
|-
| barcodes.zpl || Showcase of all supported barcode types
|-
| pallet_labels.zpl || Pallet label examples typical of Commander4j output
|-
| fonts.zpl || Font size and style demonstration
|-
| shipping.zpl || Shipping label sample
|-
| character.zpl || Character set reference
|-
| grid.zpl || Layout grid for alignment reference
|}

== Network Socket Mode ==

ZPL Renderer can listen on a TCP/IP port and render any ZPL label stream sent to it. This allows Commander4j, LabelServer4j, or any other application to use ZPL Renderer as a virtual printer — sending ZPL to the socket and seeing the result on screen instead of printing to paper.

The default port is '''9100''' (the standard Zebra raw print port). The IP address and port are configured in <code>config.xml</code>. Enable listening using the '''Network''' button in the toolbar.

ZPL Renderer extracts complete label blocks from the stream, identified by the standard <code>^XA</code> (start of label) and <code>^XZ</code> (end of label) delimiters.

== Zoom ==

Use the zoom controls in the toolbar to scale the rendered label between 0.10× and 2.00×. The default zoom is configured in <code>config.xml</code> (default: 0.5×). This is useful for examining barcode detail or checking overall label proportions.

== Multiple Labels ==

When a ZPL file or network stream contains multiple labels, ZPL Renderer displays them as pages. Navigation controls allow stepping through each label. The maximum number of pages displayed is configurable (default: 3).

== Export and Print ==

* '''PDF Export''' — saves the rendered label as a vector PDF using Apache PDFBox
* '''Print''' — sends the rendered label to a system printer

== Supported ZPL Commands ==

ZPL Renderer supports over 100 ZPL commands. Key categories:

=== Label Setup ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^XA || Start of label
|-
| ^XZ || End of label
|-
| ^LL || Label length
|-
| ^LH || Label home (origin offset)
|-
| ^LT || Label top offset
|-
| ^PQ || Print quantity
|-
| ^CD || Change delimiter character
|-
| ^CC || Change caret character
|}

=== Text and Fields ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^FO || Field origin (X,Y position from top-left)
|-
| ^FT || Field typeset (X,Y position from bottom-left)
|-
| ^FD || Field data (the text content)
|-
| ^FS || Field separator
|-
| ^FR || Field reverse (inverted colours)
|-
| ^FW || Field orientation/rotation
|-
| ^FX || Comment (ignored in output)
|}

=== Fonts ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^A0–^AZ || Select font by ID
|-
| ^CF || Change default alphanumeric font
|-
| ^CI || Change international character set/encoding
|}

=== Graphics ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^GB || Graphic box (rectangle)
|-
| ^GC || Graphic circle
|-
| ^GD || Graphic diagonal line
|-
| ^GE || Graphic ellipse
|-
| ^GF || Graphic field (embedded image data)
|-
| ^GS || Graphic symbol
|}

=== Barcodes ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^BC || Code 128 / GS1-128 (EAN-128)
|-
| ^BE || EAN-13
|-
| ^B8 || EAN-8
|-
| ^B3 || Code 39
|-
| ^B2 || Interleaved 2 of 5
|-
| ^B1 || Code 11
|-
| ^BQ || QR Code
|-
| ^B7 || PDF417
|-
| ^B0 / ^BO || Aztec
|-
| ^BY || Bar code field defaults (width, ratio, height)
|}

Barcode rendering uses the OkapiBarcode library. GS1 application identifiers are interpreted from <code>xml/config/gs1_app_defs.xml</code>.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>:

{| class="wikitable"
|-
! Setting !! Description
|-
| Input folder || Default directory for ZPL file loading (default: <code>./examples</code>)
|-
| Port || Network socket port to listen on (default: 9100)
|-
| Default magnification || Starting zoom level (default: 0.5)
|-
| Max pages || Maximum number of label pages to display (default: 3)
|}

=== fonts.xml ===

Located at <code>xml/config/fonts.xml</code>, this file maps ZPL font IDs (0, A–Z) to TrueType font files and defines their pixel dimensions. This allows ZPL Renderer to simulate the fonts installed in a physical Zebra printer.

Included fonts: Bitstream Vera, Anonymous Pro, ATTriumvirate.

If your labels use fonts that differ from the defaults, edit <code>fonts.xml</code> to match the font metrics of your target printer.

== Relationship to Commander4j ==

Commander4j generates ZPL label streams for pallet and case labels. ZPL Renderer allows you to preview these labels before deploying them to production printers, and to verify that label templates produce the correct output after making changes to the template syntax. See [[Label Template Syntax]] and [[Zebra ZPL Label]] for information on ZPL label authoring within Commander4j.

See also: [[Zebra ZPL Label]], [[Label Template Syntax]], [[Printer Queues]], [[Production Lines & Labellers]]

[[Category:Commander4j]]

File:JLaunchPad.png

2026-04-09T07:58:14Z

Dgarratt:

LaunchPad

2026-04-09T07:56:11Z

Dgarratt: Updated by push_wiki.py

LaunchPad is a macOS application organiser and launcher. It provides a tabbed grid interface for grouping macOS applications (.app bundles) into named categories and launching them with a double-click. It is a companion tool to the Commander4j suite, used to organise the suite's tools and supporting applications in a single place.

[[File:JLaunchPad.png|thumb|right|500px|JLaunchPad showing the Desktop tab]]

== Purpose ==

LaunchPad replaces cluttered Dock folders and aliases with a structured, tabbed grid. Each tab is a named category and each cell in the grid holds one application. Applications are added by browsing or dragging from Finder.

== Running LaunchPad ==

The easiest way to run LaunchPad is to double-click the <code>JLaunchPad.app</code> bundle. This is available from the [[Downloads]] page and launches the application exactly as you would any other macOS application.

Alternatively, LaunchPad can be run from the command line using:

java -jar JLaunchPad.jar

The window opens at 1300 × 900 pixels. Tabs are listed on the left edge; the grid fills the rest of the window.

== Adding Applications ==

=== Single Application ===

Click the '''Add App''' toolbar button. A file chooser opens, defaulting to <code>/Applications</code> and your home directory. Select any <code>.app</code> bundle. If you select <code>/Applications</code>, LaunchPad also scans <code>/System/Applications</code> and <code>/System/Applications/Utilities</code> automatically.

=== Importing a Folder ===

Click '''Import Folder''' to scan a directory recursively for application bundles. LaunchPad filters out uninstall helpers, login item helpers, and background-only bundles, adding only user-facing applications.

=== Drag and Drop ===

Drag a <code>.app</code> bundle from Finder directly onto the grid or onto a tab. An application can only appear once across all tabs — dragging a duplicate has no effect.

== Grid Layout ==

Each tab contains a 7-column grid of 150 × 150 pixel cells. Each cell displays the application icon (120 × 120 pixels) and the application's display name. Click '''Pack Icons''' to remove empty cells from the current tab, compacting the grid.

Applications can be reordered within the grid by dragging from one cell to another. The same drag operation works between tabs.

== Tab Management ==

The toolbar provides buttons for:

* '''Add Tab''' — create a new named category
* '''Edit Tab''' — rename the selected tab
* '''Delete Tab''' — remove the selected tab (with confirmation)
* '''Move Up / Move Down''' — reorder tabs

== Launching Applications ==

Double-click any application icon to launch it. LaunchPad uses the macOS <code>open</code> command to launch the bundle, so the application opens exactly as if you had double-clicked it in Finder.

== Cell Context Menu ==

Right-click any cell or application to access:

* '''Assign Custom Icon...''' — replace the icon with any PNG, JPG, GIF, or ICNS image
* '''Remove App''' — clear the cell
* '''Reveal in Finder''' — open the application's location in Finder

== Icon Resolution ==

When an application is added, LaunchPad attempts to extract its icon automatically. It tries the following in order:

# The <code>.icns</code> file named in the app's <code>Info.plist</code>
# PNG icons listed in <code>Info.plist</code> under <code>CFBundleIcons</code>
# The app's <code>Assets.car</code> (rendered via QuickLook)
# A generic system icon as a last resort

Extracted icons are scaled to 120 × 120 pixels and cached to <code>images/appIcons/</code> on disk. On subsequent launches the cached PNG is used unless the app itself has been updated.

== Configuration ==

LaunchPad saves its state automatically on exit and restores it on the next launch.

=== launchpad.xml ===

Located at <code>xml/config/launchpad.xml</code>. This file records all tabs, their names, and the path of each application in the grid. It is written automatically — you do not need to edit it manually.

=== images/appIcons/ ===

The icon cache directory. Each application has a <code><BundleName>.png</code> file here. If you use '''Assign Custom Icon...''', the cache file for that application is overwritten with your chosen image.

See also: [[Menu4j]], [[ZPLRenderer]], [[Downloads]]

[[Category:Commander4j]]

LabelServer4j Example User Interface

2026-04-05T16:05:04Z

Dgarratt: Updated by push_wiki.py

LabelServer4j is a headless background service — it has no graphical user interface. All interaction with the service is through configuration files, log files, and (on Windows) the Windows Services control panel.

== Starting LabelServer4j ==

=== Windows — Running as a Service ===

The native install package includes <code>LabelServer.exe</code>, a service-mode launcher that manages the Windows service directly. All commands must be run from an elevated command prompt (Run as Administrator).

The default service name is '''LabelService'''. A custom name can be passed as an optional second parameter — if used, the same name must be supplied to all subsequent commands.

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>LabelServer.exe /install</code> || Register as '''LabelService''' with automatic startup on boot
|-
| <code>LabelServer.exe /install "My Label Service"</code> || Register with a custom service name
|-
| <code>LabelServer.exe /install-demand</code> || Register with manual startup only
|-
| <code>LabelServer.exe /start</code> || Start the service
|-
| <code>LabelServer.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>LabelServer.exe /restart</code> || Restart the service
|-
| <code>LabelServer.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>LabelServer.exe /uninstall</code> || Remove the service registration
|}

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

=== Windows — Testing in a Console Window ===

Before installing as a service, use the debug launcher to run LabelServer4j with all output visible in the console:

LabelServerDebug.exe

This runs the same application code and is the most convenient way to verify that labellers connect and that the configuration is correct before committing to service deployment.

=== Linux / macOS ===

Start from the terminal using the provided shell script:

./start_labeller.sh

Or directly:

java -cp ./LabelServer.jar:./lib/devonly/i4jruntime.jar com.commander4j.labeller.Service

The process runs in the foreground. Use a process manager (systemd, launchd, or nohup) for production deployment.

== Monitoring ==

Since there is no GUI, the primary monitoring tool is the log file:

logs/c4jLabelServer.log

The log records every event in detail:

* Service startup and configuration loading
* Each labeller thread starting
* Every CSV file detected and processed
* Every command sent to a printer and every response received
* File operations (upload, download, backup, delete)
* Errors and exceptions with full context

Log files rotate at 10 MB and are retained for 14 days.

=== What to Look For ===

{| class="wikitable"
|-
! Situation !! What to check in the log
|-
| Label not printing || Look for the CSV filename being detected; if absent, check the input path in labellers.xml
|-
| Printer not responding || Look for TCP connection errors or timeout messages for that labeller's IP and port
|-
| Wrong data on label || Check the variable substitution log lines to see what values were sent
|-
| Script error || Look for the script line number and command that caused the failure
|-
| File stuck in input directory || File renamed to <code>.in</code> means the script is running or failed — check for a <code>.error</code> file
|}

== Configuration Changes ==

To change a labeller's IP address, port, command script, or input path, edit the relevant <code>labellers.xml</code> file and restart the service. Changes to configuration files are not picked up at runtime.

To switch site, edit <code>xml/config/config.xml</code> and change the <code>site id</code> attribute, then restart.

== Thread Architecture ==

When running, LabelServer4j maintains the following threads:

* One main service thread (lifecycle management)
* One server thread (configuration and orchestration)
* Per enabled labeller: one labeller thread, one TCP receive thread, one TCP transmit thread

The thread count grows with the number of configured printers. A site with six printers typically runs around 20 threads in total.

== Graceful Shutdown ==

Sending a termination signal (Ctrl+C on Linux/macOS, or stopping the Windows service) triggers the shutdown hook. LabelServer4j signals all labeller threads to stop, waits for any in-progress print jobs to complete, then exits cleanly.

See also: [[Overview LabelServer4j]], [[LabelServer4j Configuration]], [[LabelServer4j Operation]], [[Install Interface Services]]

[[Category:LabelServer4j]]

Interface Service

2026-04-05T16:05:03Z

Dgarratt: Updated by push_wiki.py

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 <code>interface</code> account and starts five background threads:

{| class="wikitable"
|-
! 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 <code>SYS_INTERFACE_LOG</code>.
|-
| '''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 <code>hosts.xml</code> with a <code>uniqueId</code> of <code>service</code>. 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 <code>interface</code> with password <code>interface</code>. 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 <code>Service4j.exe</code>, 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.

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>Service4j.exe /install</code> || Register as '''Service4j''' with automatic startup on boot
|-
| <code>Service4j.exe /install "Commander4j Interface"</code> || Register with a custom service name
|-
| <code>Service4j.exe /install-demand</code> || Register with manual startup only
|-
| <code>Service4j.exe /start</code> || Start the service
|-
| <code>Service4j.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>Service4j.exe /restart</code> || Restart the service
|-
| <code>Service4j.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>Service4j.exe /uninstall</code> || 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 (<code>services.msc</code>).

=== 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 <code>interface</code> account logs in, and all threads start successfully.

== Email Notifications ==

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

{| class="wikitable"
|-
! 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 <code>INTERFACE EMAIL NOTIFY</code> (true/false) and the recipient list in <code>INTERFACE ADMIN EMAIL</code>. Both are configured in the Commander4j system keys administration screen.

== Monitoring ==

All activity is written to the Log4j log file in the <code>logs/</code> 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.

See also: [[Interface Log]], [[Interface Message Formats]], [[Setup4j]], [[AutoLab4j]], [[LabelServer4j]]

[[Category:Commander4j]]

SFTPTransfer

2026-04-05T16:05:02Z

Dgarratt: Updated by push_wiki.py

SFTPTransfer is a background file transfer service that moves files between a local filesystem and a remote SFTP server. It is a standalone Java application that runs either as a headless background service or as a desktop application with a minimal GUI, and supports both uploading (PUT) and downloading (GET) in independent threads.

SFTPTransfer replaces the earlier sftpSend and sftpGet tools with a unified, configurable service.

== Purpose ==

SFTPTransfer automates recurring file transfers between Commander4j and external systems — for example, uploading despatch notifications to a customer portal or downloading order files from a supplier. It runs continuously, polling for new files at a configurable interval, and handles authentication, retry, backup, and archiving without operator involvement.

== Startup Modes ==

SFTPTransfer supports two startup modes selected at launch time:

{| class="wikitable"
|-
! Mode !! Behaviour
|-
| '''Start desktop''' || Opens a small GUI window. Transfer threads start in a paused state; the operator must click Start in the interface to begin polling. Useful for testing configuration.
|-
| '''Start service''' || Headless — no GUI window. Transfer threads start immediately on launch. Suitable for production deployment as a background service or scheduled task.
|}

On Windows, the native install package includes <code>sftpTransfer_Service.exe</code>, which manages the Windows service directly — see [[#Installing as a Windows Service|Installing as a Windows Service]] below. On Linux/macOS, use systemd, launchd, or nohup.

== Configuration Files ==

All configuration is held in XML files under the <code>xml/config/</code> directory. Changes require a service restart unless hot-reload is triggered (see below).

=== sftp_common.xml ===

Shared settings used by all transfer threads:

{| class="wikitable"
|-
! Setting !! Description
|-
| Poll interval || How often (in seconds) each thread checks for new files. Default: 10 seconds.
|-
| Backup retention || Number of days to keep backed-up files before automatic deletion.
|-
| Log level || Logging verbosity passed to Log4j.
|}

=== sftp_put.xml ===

Configures one or more PUT (upload) profiles. Each profile defines:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether this profile's thread is active.
|-
| Local path || Local directory to watch for outbound files.
|-
| File mask || Wildcard pattern to match files (e.g. <code>*.xml</code>, <code>order_*.csv</code>). Uses Apache Commons IO WildcardFileFilter.
|-
| Remote host || SFTP server hostname or IP address.
|-
| Remote port || SFTP port (default: 22).
|-
| Remote path || Target directory on the remote server.
|-
| Username || SFTP login username.
|-
| Password || AES-encrypted password (see [[#Password Encryption|Password Encryption]]).
|-
| Private key path || Path to SSH private key file (alternative to password authentication).
|-
| Backup path || Local directory where successfully uploaded files are moved.
|-
| Error path || Local directory where files that failed to upload are moved.
|}

=== sftp_get.xml ===

Configures one or more GET (download) profiles. Each profile defines:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether this profile's thread is active.
|-
| Remote host || SFTP server hostname or IP address.
|-
| Remote port || SFTP port (default: 22).
|-
| Remote path || Directory on the remote server to poll for incoming files.
|-
| File mask || Wildcard pattern matched against the remote file listing (server-side ls).
|-
| Local path || Local directory where downloaded files are saved.
|-
| Username || SFTP login username.
|-
| Password || AES-encrypted password.
|-
| Private key path || Path to SSH private key file.
|-
| Delete after download || Whether to delete the remote file after successful download.
|-
| Backup path || Local directory where a copy of each downloaded file is kept.
|}

=== jsch_properties.xml ===

Advanced SSH session parameters passed directly to the JSch library. Used to control host key checking, preferred algorithms, and connection timeouts. In most deployments this file can be left at its defaults.

=== email_properties.xml ===

SMTP settings for error notification emails. When a transfer failure occurs and email notification is enabled, SFTPTransfer sends an alert to the configured address. Fields include SMTP host, port, sender address, recipient address, and AES-encrypted SMTP password.

== Installing as a Windows Service ==

The native install package includes <code>sftpTransfer_Service.exe</code>, 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 '''sftpTransfer_Service''' (the launcher name defined in the installer). You can specify a different name as an optional second parameter — useful if you need to run multiple instances on the same machine. If a custom name is used at install time, that same name must be passed to every subsequent command.

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>sftpTransfer_Service.exe /install</code> || Register as '''sftpTransfer_Service''' with automatic startup on boot
|-
| <code>sftpTransfer_Service.exe /install "My SFTP Service"</code> || Register with a custom service name
|-
| <code>sftpTransfer_Service.exe /install-demand</code> || Register with manual startup only
|-
| <code>sftpTransfer_Service.exe /start</code> || Start the service
|-
| <code>sftpTransfer_Service.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>sftpTransfer_Service.exe /restart</code> || Restart the service
|-
| <code>sftpTransfer_Service.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>sftpTransfer_Service.exe /uninstall</code> || Remove the service registration
|}

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

sftpTransfer_Service.exe /start "My SFTP Service"
sftpTransfer_Service.exe /stop "My SFTP Service"
sftpTransfer_Service.exe /uninstall "My SFTP Service"

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

=== Testing Before Installing as a Service ===

The native install package also provides two alternatives for testing:

{| class="wikitable"
|-
! Launcher !! Mode !! Use case
|-
| <code>sftpTransfer_Console.exe</code> || Console (headless) || Runs the service logic in a visible console window — useful for watching log output during initial configuration
|-
| <code>sftpTransfer.exe</code> || Desktop GUI || Opens the GUI window in Start desktop mode — transfer threads start paused, allowing configuration to be verified before enabling transfers
|}

== Authentication ==

SFTPTransfer supports two authentication methods, configured per profile:

{| class="wikitable"
|-
! Method !! How to configure
|-
| Password || Set the <code>Password</code> field in the profile to an AES-encrypted value. Leave the private key path empty.
|-
| SSH private key || Set the <code>Private key path</code> field to the path of a PEM-format private key file. The password field is ignored.
|}

Both methods use the JSch 2.x SSH library with Bouncy Castle as the cryptographic provider.

=== Password Encryption ===

Passwords stored in configuration files are AES-encrypted. Plain-text passwords are never stored on disk. To encrypt a password, use the password utility included with Commander4j (the same utility used for database passwords in Commander4j's own configuration).

== File Transfer Behaviour ==

=== PUT (Upload) ===

# SFTPTransfer polls the local input directory every 10 seconds (configurable).
# Files matching the file mask are selected for upload.
# Each file is uploaded to the remote path using a temporary name with a <code>.tmp</code> extension.
# On successful transfer, the remote file is renamed to its final name (atomic rename — the remote system never sees a partial file).
# The local source file is moved to the backup directory.
# If the transfer fails, the file is moved to the error directory and an error is logged.

=== GET (Download) ===

# SFTPTransfer lists the remote directory every 10 seconds (configurable).
# Files matching the file mask are selected for download.
# Each file is downloaded to the local path using a <code>.tmp</code> extension.
# On successful download, the local file is renamed to its final name.
# If configured, the remote file is deleted after download.
# A backup copy is optionally saved to the local backup directory.

== Thread Architecture ==

When running, SFTPTransfer maintains the following threads:

{| class="wikitable"
|-
! Thread !! Purpose
|-
| TransferPUT || One thread per enabled PUT profile, each managing its own SFTP connection.
|-
| TransferGET || One thread per enabled GET profile, each managing its own SFTP connection.
|-
| EmailThread || Sends error notification emails asynchronously.
|-
| ArchiveThread || Periodically purges backup files older than the configured retention period.
|}

== Hot Configuration Reload ==

SFTPTransfer supports a configuration reload mode (<code>Mode_CONFIG_UPDATE</code>). When this mode is triggered, running threads re-read their configuration files without requiring a full service restart. This allows profile changes — such as updating a remote path or rotating credentials — to be applied with minimal disruption.

== Logging ==

All activity is written to the Log4j log file. The log records:

* Service startup and configuration loaded
* Each thread starting and its profile settings
* Every file detected, transfer attempted, and outcome
* Every remote connection attempt and disconnect
* File move operations (to backup or error directories)
* Errors and exceptions with full context

Log rotation and retention are configured in the Log4j configuration file included in the distribution.

== Dependencies ==

{| class="wikitable"
|-
! Library !! Version !! Purpose
|-
| JSch || 2.27.9 || SSH/SFTP client
|-
| Bouncy Castle || current || Cryptographic provider for JSch
|-
| Apache Commons IO || current || WildcardFileFilter for local file matching
|-
| Log4j || 2.25.3 || Logging
|}

See also: [[LabelServer4j]], [[Middleware4j]], [[Production Lines & Labellers]]

[[Category:Commander4j]]

Installation Middleware4j

2026-04-05T16:05:01Z

Dgarratt: Updated by push_wiki.py

This page covers deploying Middleware4j on a server or integration host.

== Requirements ==

* Network access to any input or output directories defined in the map configuration (local paths, UNC shares, or mounted network drives)
* If using the EMAIL connector: network access to an SMTP server
* If using the SOCKET connector: network access to the target TCP/IP device
* Windows, Linux, or macOS
* Java 21 — required only when running from the distribution archive; the native install package bundles its own Java runtime

== Installation ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method. The installer creates the application directory, copies all configuration templates, and handles the Java runtime dependency automatically.

Alternatively, a distribution archive can be extracted to a suitable directory, for example:

C:\Commander4j\Middleware4j\ (Windows)
/opt/commander4j/middleware4j/ (Linux)

The extracted directory contains:

c4jMiddleware.jar
Middleware_Service.exe (Windows — service launcher)
Middleware_GUI.exe (Windows — desktop GUI launcher)
Encrypt_String.exe (Windows — utility to encrypt passwords)
start.cmd (Windows — fallback start script)
start.sh (Linux/macOS — start script)
xml/config/
xslt/
interface/
logs/
samples/

== Configuration Before First Run ==

=== 1. Maps ===

Edit <code>xml/config/config.xml</code> to define the transformation maps. Each map specifies one input connector, one or more output connectors, and optionally an XSLT stylesheet. See [[Maps]] for the full configuration reference.

=== 2. XSLT Stylesheets ===

Place any XSLT stylesheets used by your maps in the <code>xslt/</code> directory. A library of over 60 sample stylesheets is included covering common integration scenarios with SAP, Sage, Tropos, B2MML, and others.

=== 3. Email Notifications (Optional) ===

Edit <code>xml/config/email.xml</code> with your SMTP server details and recipient addresses for error notifications.

=== 4. Password Encryption ===

Any passwords stored in configuration files (SMTP, database connections) must be AES-encrypted. Use the included <code>Encrypt_String.exe</code> utility (Windows) to generate encrypted values. On Linux/macOS, use the equivalent utility from the Commander4j installation.

== Installing as a Windows Service ==

The native install package includes <code>Middleware_Service.exe</code>, a service-mode launcher built with install4j. This executable manages the Windows service directly — no additional wrapper (such as WinSW) is required.

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

The default Windows service name is '''Middleware Service''' (the launcher name defined in the installer). You can specify a different name as an optional second parameter — useful if you need to run multiple instances on the same machine. If a custom name is used at install time, that same name must be passed to every subsequent command.

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>Middleware_Service.exe /install</code> || Register as '''Middleware Service''' with automatic startup on boot
|-
| <code>Middleware_Service.exe /install "My Middleware"</code> || Register with a custom service name
|-
| <code>Middleware_Service.exe /install-demand</code> || Register with manual startup only
|-
| <code>Middleware_Service.exe /start</code> || Start the service
|-
| <code>Middleware_Service.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>Middleware_Service.exe /restart</code> || Restart the service
|-
| <code>Middleware_Service.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>Middleware_Service.exe /uninstall</code> || Remove the service registration
|}

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

Middleware_Service.exe /start "My Middleware"
Middleware_Service.exe /stop "My Middleware"
Middleware_Service.exe /uninstall "My Middleware"

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

=== Testing Before Installing as a Service ===

Before committing to service installation, run Middleware4j in desktop GUI mode using:

Middleware_GUI.exe

This launches a desktop window showing all configured maps, their current status, and real-time message counts. Use this mode to confirm that maps are reading from the correct input directories and that XSLT transformations produce the expected output. Once satisfied, switch to service mode for production deployment.

== Starting on Linux / macOS ==

Use the provided shell script:

./start.sh

The mode (GUI or Service) is passed as an argument by the script. The process runs in the foreground. For production deployment, use systemd, launchd, or nohup to manage it as a background process.

== Verifying the Installation ==

After starting Middleware4j:

# Check <code>logs/</code> for startup messages confirming that each map thread has initialised.
# Place a test input file in the input directory of one of the configured maps.
# Confirm the file is consumed and the expected output appears in the output directory.
# Check <code>interface/log/</code> for the message transaction record.

== Log Files ==

All activity is written to the Log4j log file in the <code>logs/</code> directory. Log rotation and retention are configured in <code>xml/config/log4j2.xml</code>.

See also: [[Overview_Middleware4j]], [[Maps]], [[Connectors]]

[[Category:Middleware4j]]

Installation LabelServer4j

2026-04-05T16:05:00Z

Dgarratt: Updated by push_wiki.py

This page covers deploying LabelServer4j on a server or PC connected to the production network.

== Requirements ==

* Network access to each label printer (TCP/IP — Zebra port 9100, Logopak port 9100 or as configured)
* Network access to the Commander4j server (to receive CSV request files)
* Windows, Linux, or macOS
* Java 21 — required only when running from the distribution archive; the native install package bundles its own Java runtime

== Installation ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method. The installer creates the application directory, copies all configuration templates, and handles the Java runtime dependency automatically.

Alternatively, a distribution archive can be extracted to a suitable directory, for example:

C:\Commander4j\LabelServer4j\ (Windows)
/opt/commander4j/labelserver4j/ (Linux)

The extracted directory contains:

LabelServer.jar
LabelServer.exe (Windows — service launcher)
LabelServerDebug.exe (Windows — console launcher for testing)
start_labeller.cmd (Windows — fallback start script)
start_labeller.sh (Linux/macOS — start script)
lib/
xml/config/
labeller_files/
labeller_requests/
labeller_cmd/
labeller_backups/
logs/

== Configuration Before First Run ==

Before starting LabelServer4j, complete the following configuration steps.

=== 1. Site and Labeller Definitions ===

Edit <code>xml/config/config.xml</code> to set the active site identifier. Then create or edit the <code>labellers.xml</code> file for that site in <code>xml/config/</code>. Each labeller entry defines:

* The labeller name (must match the name used in Commander4j)
* The printer IP address and TCP port
* The path to the command script
* The input directory where Commander4j writes CSV files

See [[LabelServer4j Configuration]] for the full XML structure.

=== 2. Command Scripts ===

Place the command script files (plain text <code>.txt</code> files) for each labeller in the <code>labeller_cmd/</code> directory. The script filename is referenced in <code>labellers.xml</code>.

=== 3. Label Files (Logopak only) ===

If using Logopak printers with stored label templates, place the binary label files in the appropriate subdirectory of <code>labeller_files/</code>. LabelServer4j can upload these to the printer using the <code>SEND_FILE_INTELHEX</code> command.

=== 4. Database Connection (Optional) ===

If the command scripts use <code>DB_QUERY</code> to enrich label data from the Commander4j database, configure the database connection in <code>xml/config/config.xml</code> with the JDBC URL, username, and AES-encrypted password.

=== 5. Email Notifications (Optional) ===

To receive alerts on print failures or service events, configure <code>xml/config/email.xml</code> with SMTP server details and recipient addresses.

== Installing as a Windows Service ==

The native install package includes <code>LabelServer.exe</code>, a service-mode launcher built with install4j. This executable manages the Windows service directly — no additional wrapper (such as WinSW) is required.

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

The default Windows service name is '''LabelService''' (the launcher name defined in the installer). You can specify a different name as an optional second parameter — useful if you need to run multiple instances on the same machine. If a custom name is used at install time, that same name must be passed to every subsequent command.

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>LabelServer.exe /install</code> || Register as '''LabelService''' with automatic startup on boot
|-
| <code>LabelServer.exe /install "My Label Service"</code> || Register with a custom service name
|-
| <code>LabelServer.exe /install-demand</code> || Register with manual startup only
|-
| <code>LabelServer.exe /start</code> || Start the service
|-
| <code>LabelServer.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>LabelServer.exe /restart</code> || Restart the service
|-
| <code>LabelServer.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>LabelServer.exe /uninstall</code> || Remove the service registration
|}

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

LabelServer.exe /start "My Label Service"
LabelServer.exe /stop "My Label Service"
LabelServer.exe /uninstall "My Label Service"

Once installed, the service also appears in the Windows Services management console (<code>services.msc</code>) and can be started and stopped from there.

=== Testing Before Installing as a Service ===

Before committing to service installation, run LabelServer4j in a visible console window using the debug launcher:

LabelServerDebug.exe

This runs the same application code with all log output written to the console window. Use this mode to confirm that labellers connect to their printers and that the configuration is correct before installing as a service.

== Starting on Linux / macOS ==

Use the provided shell script:

./start_labeller.sh

Or directly:

java -cp ./LabelServer.jar:./lib/devonly/i4jruntime.jar com.commander4j.labeller.Service

The process runs in the foreground. For production deployment, use a process manager (systemd, launchd, or nohup) to run it as a background service.

== Verifying the Installation ==

After starting LabelServer4j:

# Check <code>logs/c4jLabelServer.log</code> — there should be startup and thread initialisation messages.
# Verify that each labeller thread reports a successful TCP connection to its printer.
# Place a test CSV file in a labeller's input directory to trigger an end-to-end print cycle.
# Confirm the CSV file is consumed (deleted on success, or moved to the error directory on failure).

== Log Files ==

All activity is written to <code>logs/c4jLabelServer.log</code>. Log files rotate at 10 MB and are retained for 14 days.

See also: [[Overview LabelServer4j]], [[LabelServer4j Operation]], [[LabelServer4j Configuration]], [[LabelServer4j Example User Interface]]

[[Category:LabelServer4j]]

Interface Service

2026-04-05T16:01:24Z

Dgarratt: Updated by push_wiki.py

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 <code>interface</code> account and starts five background threads:

{| class="wikitable"
|-
! 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 <code>SYS_INTERFACE_LOG</code>.
|-
| '''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 <code>hosts.xml</code> with a <code>uniqueId</code> of <code>service</code>. 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 <code>interface</code> with password <code>interface</code>. 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 <code>Service4j.exe</code>, 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).

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>Service4j.exe /install</code> || Register the Windows service with automatic startup on boot
|-
| <code>Service4j.exe /install-demand</code> || Register the service with manual startup only
|-
| <code>Service4j.exe /start</code> || Start the service
|-
| <code>Service4j.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>Service4j.exe /restart</code> || Restart the service
|-
| <code>Service4j.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>Service4j.exe /uninstall</code> || Remove the service registration
|}

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

=== 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 <code>interface</code> account logs in, and all threads start successfully.

== Email Notifications ==

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

{| class="wikitable"
|-
! 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 <code>INTERFACE EMAIL NOTIFY</code> (true/false) and the recipient list in <code>INTERFACE ADMIN EMAIL</code>. Both are configured in the Commander4j system keys administration screen.

== Monitoring ==

All activity is written to the Log4j log file in the <code>logs/</code> 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.

See also: [[Interface Log]], [[Interface Message Formats]], [[Setup4j]], [[AutoLab4j]], [[LabelServer4j]]

[[Category:Commander4j]]

Clone4j

2026-04-05T16:01:21Z

Dgarratt: Updated by push_wiki.py

'''Clone4j''' is a database copy utility included with Commander4j. It copies the entire contents of one Commander4j database into another, and supports copying between different database types — for example from SQL Server to MySQL or from MySQL to Oracle.

Clone4j is launched from the <code>Clone4j.exe</code> executable in the Commander4j installation directory. It requires administrator privileges (the launcher requests elevation on Windows).

== When to Use Clone4j ==

Typical uses include:

* Copying a live production database to a test or development environment
* Migrating data when moving a site from one database platform to another
* Creating a full backup copy of the database in a different database instance

== Prerequisites ==

Before running Clone4j:

* Both the source and destination databases must be defined as hosts in <code>hosts.xml</code> (use [[Setup4j]] to configure host connections)
* Both databases must be on the '''same schema version''' — Clone4j will refuse to proceed if the schema versions differ
* Both databases must have the same number of tables — they must be on identical schema revisions with no partial upgrades applied
* The destination database will have '''all its data erased''' and replaced with the source data

== Using Clone4j ==

# Launch <code>Clone4j.exe</code>
# The window shows two lists populated from <code>hosts.xml</code> — select the '''source''' database on the left and the '''destination''' database on the right
# Click '''Clone Database'''
# A confirmation prompt warns that all data in the destination will be erased — confirm to proceed
# Clone4j copies every table in sequence, updating a progress bar as it works
# On completion, the status bar reports the outcome

The Clone button is only enabled when both a source and a destination have been selected and they are not the same host.

== Limitations ==

* Clone4j copies data row by row — it is not a structural migration tool. Both databases must already have matching schemas (same schema version, same table count).
* It is not designed for continuous replication. It is a one-time full copy.
* Large databases may take several minutes to clone depending on row count and network speed.

See also: [[Setup4j]], [[Installation]], [[Upgrading]]

[[Category:Commander4j]]

LabelServer4j

2026-04-05T15:56:01Z

Dgarratt: Updated by push_wiki.py

'''LabelServer4j''' is a background label printing service that bridges Commander4j and physical label printer devices on a production line. When an operator assigns a [[Process Orders|Process Order]] to a production line, Commander4j exports a data file which LabelServer4j picks up, processes through a configurable script, and uses to drive the printer over TCP/IP.

LabelServer4j supports Zebra ZPL printers, Logopak labellers, and any device that accepts raw TCP/IP text commands. It runs as a headless background service with no graphical interface, and can manage multiple printers simultaneously in independent threads.

== Getting Started ==

{| class="wikitable" style="width:100%"
|-
| [[Overview LabelServer4j]] || What LabelServer4j does and how it differs from AutoLab4j
|-
| [[Downloads]] || Download the latest release
|-
| [[Installation LabelServer4j]] || Installing LabelServer4j and configuring as a Windows service
|-
| [[LabelServer4j Configuration]] || Configuring sites, labellers, and database connections
|-
| [[LabelServer4j Folder Structure]] || Directory layout and purpose of each folder
|}

== User Guide ==

{| class="wikitable" style="width:100%"
|-
| [[LabelServer4j Operation]] || End-to-end workflow from order assignment to label printed
|-
| [[LabelServer4j Dataset CSV]] || Fields available in the CSV data file from Commander4j
|-
| [[LabelServer4j Example User Interface]] || Deployment, startup, monitoring, and log file reference
|}

== Related Pages ==

{| class="wikitable" style="width:100%"
|-
| [[Production Lines & Labellers]] || Configuring production lines in Commander4j
|-
| [[Process Order Assign to Labeller]] || Assigning orders to labellers from Commander4j
|-
| [[Zebra ZPL Label]] || ZPL label template syntax reference
|-
| [[Label Template Syntax]] || Commander4j label template language
|-
| [[ZPLRenderer]] || Tool for previewing ZPL labels before printing
|}

[[Category:LabelServer4j]]

Installation AutoLab4j

2026-04-05T15:56:00Z

Dgarratt: Updated by push_wiki.py

This page covers deploying AutoLab4j on a server or PC connected to the production network.

== Requirements ==

* Network access to the Modbus I/O device on each production line (TCP port 502 by default)
* Network access to each Zebra printer (TCP port 9100)
* Network access to the Commander4j server (to receive CSV dataset files)
* Windows, Linux, or macOS
* Java 21 (JRE or JDK) — required only when running from the distribution archive; the native install package bundles its own Java runtime

== Installation ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method. The installer creates the application directory, registers it with the operating system, and handles the Java runtime dependency automatically.

Alternatively, a distribution archive can be downloaded from the [[Downloads]] page and extracted to a suitable directory, for example:

C:\Commander4j\AutoLab4j\ (Windows)
/opt/commander4j/autolab4j/ (Linux)

The extracted directory contains:

AutoLab.jar
lib/
xml/
labels/
logs/
interface/
running/

== Configuration Before First Run ==

Before starting AutoLab4j, complete the following configuration steps.

=== 1. Production Lines ===

Edit <code>xml/config/config.xml</code> and define each production line. For each line you need:

* The Modbus device IP address and port
* The coil address that signals a pallet complete event
* The coil address for semi-pallet detection
* The printer name (must match the name used in Commander4j)

See [[AutoLab4j Configuration]] for the full XML structure.

=== 2. SSCC Sequence Files ===

Create one SSCC sequence file per printer in <code>xml/sscc/</code>. The filename must match the printer name configured in <code>config.xml</code>. For example, for a printer named <code>PRINTER 1</code>:

xml/sscc/PRINTER 1.xml

The file must contain the SSCC prefix, starting sequence number, warning limit, and upper limit. Your GS1 member organisation will provide the prefix. Example:

<?xml version="1.0" encoding="UTF-8"?>
<sscc>
<prefix>384133182</prefix>
<sequence>00000001</sequence>
<checkDigit>0</checkDigit>
<upperlimit>00009999</upperlimit>
<warninglimit>00009000</warninglimit>
</sscc>

=== 3. Label Templates ===

Copy the ZPL label template files into the <code>labels/</code> directory. The filename for each template is specified in the CSV dataset file in the <code>REPORT_FILENAME</code> field. See [[Zebra ZPL Label]] for information on ZPL label authoring.

=== 4. Dataset Directory ===

Ensure the directory configured as <code>dataSet path</code> in <code>config.xml</code> is accessible. This is where Commander4j writes the CSV files when an operator assigns a process order to a labeller. The directory can be a local path or a network share.

=== 5. Output Directory ===

Ensure the directory configured as <code>output path</code> in <code>config.xml</code> exists and is writable. AutoLab4j writes Production Declaration XML files here after each pallet is printed.

=== 6. Email Notifications (Optional) ===

If you want email alerts for SSCC warnings and service start/stop events, configure <code>xml/config/email.xml</code> with your SMTP server details and distribution lists.

== Starting AutoLab4j ==

=== Windows — Native Package ===

The native install package creates <code>AutoLab4j_Startup.exe</code> in the installation directory. Double-click this launcher, or create a shortcut to it, to start AutoLab4j. It enforces single-instance operation — a second launch will signal the running instance to shut down before the new one starts.

AutoLab4j is a GUI application and does not include a built-in Windows service launcher. To run it automatically at boot without an interactive session, use a service wrapper such as WinSW configured to launch <code>AutoLab4j_Startup.exe</code>.

=== Windows — Distribution Archive ===

If running from the extracted archive rather than the native package:

java -jar AutoLab.jar

=== Linux / macOS ===

java -jar AutoLab.jar

Use systemd, launchd, or nohup for production deployment as a background process.

When running, AutoLab4j appears in the system tray with one icon per production line. The System Log window shows startup progress.

== Exclusive Runtime ==

AutoLab4j uses a TCP port (default: 8000) as an exclusive runtime lock. Only one instance can run at a time. If you start a second instance, it sends a shutdown signal to the running instance and waits for it to stop before starting. The watchdog port can be changed in <code>config.xml</code>.

== Verifying the Installation ==

After starting AutoLab4j:

# Check the system tray — there should be one icon per enabled production line.
# Open the System Log window (right-click the system tray icon).
# Verify that each production line shows a Modbus connection attempt in its log window.
# Place a test CSV file in the dataset directory and trigger the Modbus coil to confirm end-to-end operation.

== Log Files ==

All activity is written to <code>logs/AutoLab.log</code>. Log files rotate at 10 MB and are retained for 14 days. Review this file if any production line fails to connect or if labels are not printing.

See also: [[AutoLab4j Configuration]], [[Overview AutoLab4j]], [[AutoLab4j Operation]]

[[Category:AutoLab4j]]

SFTPTransfer

2026-04-05T15:55:54Z

Dgarratt: Updated by push_wiki.py

SFTPTransfer is a background file transfer service that moves files between a local filesystem and a remote SFTP server. It is a standalone Java application that runs either as a headless background service or as a desktop application with a minimal GUI, and supports both uploading (PUT) and downloading (GET) in independent threads.

SFTPTransfer replaces the earlier sftpSend and sftpGet tools with a unified, configurable service.

== Purpose ==

SFTPTransfer automates recurring file transfers between Commander4j and external systems — for example, uploading despatch notifications to a customer portal or downloading order files from a supplier. It runs continuously, polling for new files at a configurable interval, and handles authentication, retry, backup, and archiving without operator involvement.

== Startup Modes ==

SFTPTransfer supports two startup modes selected at launch time:

{| class="wikitable"
|-
! Mode !! Behaviour
|-
| '''Start desktop''' || Opens a small GUI window. Transfer threads start in a paused state; the operator must click Start in the interface to begin polling. Useful for testing configuration.
|-
| '''Start service''' || Headless — no GUI window. Transfer threads start immediately on launch. Suitable for production deployment as a background service or scheduled task.
|}

On Windows, the native install package includes <code>sftpTransfer_Service.exe</code>, which manages the Windows service directly — see [[#Installing as a Windows Service|Installing as a Windows Service]] below. On Linux/macOS, use systemd, launchd, or nohup.

== Configuration Files ==

All configuration is held in XML files under the <code>xml/config/</code> directory. Changes require a service restart unless hot-reload is triggered (see below).

=== sftp_common.xml ===

Shared settings used by all transfer threads:

{| class="wikitable"
|-
! Setting !! Description
|-
| Poll interval || How often (in seconds) each thread checks for new files. Default: 10 seconds.
|-
| Backup retention || Number of days to keep backed-up files before automatic deletion.
|-
| Log level || Logging verbosity passed to Log4j.
|}

=== sftp_put.xml ===

Configures one or more PUT (upload) profiles. Each profile defines:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether this profile's thread is active.
|-
| Local path || Local directory to watch for outbound files.
|-
| File mask || Wildcard pattern to match files (e.g. <code>*.xml</code>, <code>order_*.csv</code>). Uses Apache Commons IO WildcardFileFilter.
|-
| Remote host || SFTP server hostname or IP address.
|-
| Remote port || SFTP port (default: 22).
|-
| Remote path || Target directory on the remote server.
|-
| Username || SFTP login username.
|-
| Password || AES-encrypted password (see [[#Password Encryption|Password Encryption]]).
|-
| Private key path || Path to SSH private key file (alternative to password authentication).
|-
| Backup path || Local directory where successfully uploaded files are moved.
|-
| Error path || Local directory where files that failed to upload are moved.
|}

=== sftp_get.xml ===

Configures one or more GET (download) profiles. Each profile defines:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether this profile's thread is active.
|-
| Remote host || SFTP server hostname or IP address.
|-
| Remote port || SFTP port (default: 22).
|-
| Remote path || Directory on the remote server to poll for incoming files.
|-
| File mask || Wildcard pattern matched against the remote file listing (server-side ls).
|-
| Local path || Local directory where downloaded files are saved.
|-
| Username || SFTP login username.
|-
| Password || AES-encrypted password.
|-
| Private key path || Path to SSH private key file.
|-
| Delete after download || Whether to delete the remote file after successful download.
|-
| Backup path || Local directory where a copy of each downloaded file is kept.
|}

=== jsch_properties.xml ===

Advanced SSH session parameters passed directly to the JSch library. Used to control host key checking, preferred algorithms, and connection timeouts. In most deployments this file can be left at its defaults.

=== email_properties.xml ===

SMTP settings for error notification emails. When a transfer failure occurs and email notification is enabled, SFTPTransfer sends an alert to the configured address. Fields include SMTP host, port, sender address, recipient address, and AES-encrypted SMTP password.

== Installing as a Windows Service ==

The native install package includes <code>sftpTransfer_Service.exe</code>, 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).

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>sftpTransfer_Service.exe /install</code> || Register the Windows service with automatic startup on boot
|-
| <code>sftpTransfer_Service.exe /install-demand</code> || Register the service with manual startup only
|-
| <code>sftpTransfer_Service.exe /start</code> || Start the service
|-
| <code>sftpTransfer_Service.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>sftpTransfer_Service.exe /restart</code> || Restart the service
|-
| <code>sftpTransfer_Service.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>sftpTransfer_Service.exe /uninstall</code> || Remove the service registration
|}

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

=== Testing Before Installing as a Service ===

The native install package also provides two alternatives for testing:

{| class="wikitable"
|-
! Launcher !! Mode !! Use case
|-
| <code>sftpTransfer_Console.exe</code> || Console (headless) || Runs the service logic in a visible console window — useful for watching log output during initial configuration
|-
| <code>sftpTransfer.exe</code> || Desktop GUI || Opens the GUI window in Start desktop mode — transfer threads start paused, allowing configuration to be verified before enabling transfers
|}

== Authentication ==

SFTPTransfer supports two authentication methods, configured per profile:

{| class="wikitable"
|-
! Method !! How to configure
|-
| Password || Set the <code>Password</code> field in the profile to an AES-encrypted value. Leave the private key path empty.
|-
| SSH private key || Set the <code>Private key path</code> field to the path of a PEM-format private key file. The password field is ignored.
|}

Both methods use the JSch 2.x SSH library with Bouncy Castle as the cryptographic provider.

=== Password Encryption ===

Passwords stored in configuration files are AES-encrypted. Plain-text passwords are never stored on disk. To encrypt a password, use the password utility included with Commander4j (the same utility used for database passwords in Commander4j's own configuration).

== File Transfer Behaviour ==

=== PUT (Upload) ===

# SFTPTransfer polls the local input directory every 10 seconds (configurable).
# Files matching the file mask are selected for upload.
# Each file is uploaded to the remote path using a temporary name with a <code>.tmp</code> extension.
# On successful transfer, the remote file is renamed to its final name (atomic rename — the remote system never sees a partial file).
# The local source file is moved to the backup directory.
# If the transfer fails, the file is moved to the error directory and an error is logged.

=== GET (Download) ===

# SFTPTransfer lists the remote directory every 10 seconds (configurable).
# Files matching the file mask are selected for download.
# Each file is downloaded to the local path using a <code>.tmp</code> extension.
# On successful download, the local file is renamed to its final name.
# If configured, the remote file is deleted after download.
# A backup copy is optionally saved to the local backup directory.

== Thread Architecture ==

When running, SFTPTransfer maintains the following threads:

{| class="wikitable"
|-
! Thread !! Purpose
|-
| TransferPUT || One thread per enabled PUT profile, each managing its own SFTP connection.
|-
| TransferGET || One thread per enabled GET profile, each managing its own SFTP connection.
|-
| EmailThread || Sends error notification emails asynchronously.
|-
| ArchiveThread || Periodically purges backup files older than the configured retention period.
|}

== Hot Configuration Reload ==

SFTPTransfer supports a configuration reload mode (<code>Mode_CONFIG_UPDATE</code>). When this mode is triggered, running threads re-read their configuration files without requiring a full service restart. This allows profile changes — such as updating a remote path or rotating credentials — to be applied with minimal disruption.

== Logging ==

All activity is written to the Log4j log file. The log records:

* Service startup and configuration loaded
* Each thread starting and its profile settings
* Every file detected, transfer attempted, and outcome
* Every remote connection attempt and disconnect
* File move operations (to backup or error directories)
* Errors and exceptions with full context

Log rotation and retention are configured in the Log4j configuration file included in the distribution.

== Dependencies ==

{| class="wikitable"
|-
! Library !! Version !! Purpose
|-
| JSch || 2.27.9 || SSH/SFTP client
|-
| Bouncy Castle || current || Cryptographic provider for JSch
|-
| Apache Commons IO || current || WildcardFileFilter for local file matching
|-
| Log4j || 2.25.3 || Logging
|}

See also: [[LabelServer4j]], [[Middleware4j]], [[Production Lines & Labellers]]

[[Category:Commander4j]]

LabelServer4j Example User Interface

2026-04-05T15:55:53Z

Dgarratt: Updated by push_wiki.py

LabelServer4j is a headless background service — it has no graphical user interface. All interaction with the service is through configuration files, log files, and (on Windows) the Windows Services control panel.

== Starting LabelServer4j ==

=== Windows — Running as a Service ===

The native install package includes <code>LabelServer.exe</code>, a service-mode launcher that manages the Windows service directly. All commands must be run from an elevated command prompt (Run as Administrator).

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>LabelServer.exe /install</code> || Register the service with automatic startup on boot
|-
| <code>LabelServer.exe /install-demand</code> || Register the service with manual startup only
|-
| <code>LabelServer.exe /start</code> || Start the service
|-
| <code>LabelServer.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>LabelServer.exe /restart</code> || Restart the service
|-
| <code>LabelServer.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>LabelServer.exe /uninstall</code> || Remove the service registration
|}

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

=== Windows — Testing in a Console Window ===

Before installing as a service, use the debug launcher to run LabelServer4j with all output visible in the console:

LabelServerDebug.exe

This runs the same application code and is the most convenient way to verify that labellers connect and that the configuration is correct before committing to service deployment.

=== Linux / macOS ===

Start from the terminal using the provided shell script:

./start_labeller.sh

Or directly:

java -cp ./LabelServer.jar:./lib/devonly/i4jruntime.jar com.commander4j.labeller.Service

The process runs in the foreground. Use a process manager (systemd, launchd, or nohup) for production deployment.

== Monitoring ==

Since there is no GUI, the primary monitoring tool is the log file:

logs/c4jLabelServer.log

The log records every event in detail:

* Service startup and configuration loading
* Each labeller thread starting
* Every CSV file detected and processed
* Every command sent to a printer and every response received
* File operations (upload, download, backup, delete)
* Errors and exceptions with full context

Log files rotate at 10 MB and are retained for 14 days.

=== What to Look For ===

{| class="wikitable"
|-
! Situation !! What to check in the log
|-
| Label not printing || Look for the CSV filename being detected; if absent, check the input path in labellers.xml
|-
| Printer not responding || Look for TCP connection errors or timeout messages for that labeller's IP and port
|-
| Wrong data on label || Check the variable substitution log lines to see what values were sent
|-
| Script error || Look for the script line number and command that caused the failure
|-
| File stuck in input directory || File renamed to <code>.in</code> means the script is running or failed — check for a <code>.error</code> file
|}

== Configuration Changes ==

To change a labeller's IP address, port, command script, or input path, edit the relevant <code>labellers.xml</code> file and restart the service. Changes to configuration files are not picked up at runtime.

To switch site, edit <code>xml/config/config.xml</code> and change the <code>site id</code> attribute, then restart.

== Thread Architecture ==

When running, LabelServer4j maintains the following threads:

* One main service thread (lifecycle management)
* One server thread (configuration and orchestration)
* Per enabled labeller: one labeller thread, one TCP receive thread, one TCP transmit thread

The thread count grows with the number of configured printers. A site with six printers typically runs around 20 threads in total.

== Graceful Shutdown ==

Sending a termination signal (Ctrl+C on Linux/macOS, or stopping the Windows service) triggers the shutdown hook. LabelServer4j signals all labeller threads to stop, waits for any in-progress print jobs to complete, then exits cleanly.

See also: [[Overview LabelServer4j]], [[LabelServer4j Configuration]], [[LabelServer4j Operation]], [[Install Interface Services]]

[[Category:LabelServer4j]]

Installation Middleware4j

2026-04-05T15:55:52Z

Dgarratt: Updated by push_wiki.py

This page covers deploying Middleware4j on a server or integration host.

== Requirements ==

* Network access to any input or output directories defined in the map configuration (local paths, UNC shares, or mounted network drives)
* If using the EMAIL connector: network access to an SMTP server
* If using the SOCKET connector: network access to the target TCP/IP device
* Windows, Linux, or macOS
* Java 21 — required only when running from the distribution archive; the native install package bundles its own Java runtime

== Installation ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method. The installer creates the application directory, copies all configuration templates, and handles the Java runtime dependency automatically.

Alternatively, a distribution archive can be extracted to a suitable directory, for example:

C:\Commander4j\Middleware4j\ (Windows)
/opt/commander4j/middleware4j/ (Linux)

The extracted directory contains:

c4jMiddleware.jar
Middleware_Service.exe (Windows — service launcher)
Middleware_GUI.exe (Windows — desktop GUI launcher)
Encrypt_String.exe (Windows — utility to encrypt passwords)
start.cmd (Windows — fallback start script)
start.sh (Linux/macOS — start script)
xml/config/
xslt/
interface/
logs/
samples/

== Configuration Before First Run ==

=== 1. Maps ===

Edit <code>xml/config/config.xml</code> to define the transformation maps. Each map specifies one input connector, one or more output connectors, and optionally an XSLT stylesheet. See [[Maps]] for the full configuration reference.

=== 2. XSLT Stylesheets ===

Place any XSLT stylesheets used by your maps in the <code>xslt/</code> directory. A library of over 60 sample stylesheets is included covering common integration scenarios with SAP, Sage, Tropos, B2MML, and others.

=== 3. Email Notifications (Optional) ===

Edit <code>xml/config/email.xml</code> with your SMTP server details and recipient addresses for error notifications.

=== 4. Password Encryption ===

Any passwords stored in configuration files (SMTP, database connections) must be AES-encrypted. Use the included <code>Encrypt_String.exe</code> utility (Windows) to generate encrypted values. On Linux/macOS, use the equivalent utility from the Commander4j installation.

== Installing as a Windows Service ==

The native install package includes <code>Middleware_Service.exe</code>, a service-mode launcher built with install4j. This executable manages the Windows service directly — no additional wrapper (such as WinSW) is required.

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

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>Middleware_Service.exe /install</code> || Register the Windows service with automatic startup on boot
|-
| <code>Middleware_Service.exe /install-demand</code> || Register the service with manual startup only
|-
| <code>Middleware_Service.exe /start</code> || Start the service
|-
| <code>Middleware_Service.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>Middleware_Service.exe /restart</code> || Restart the service
|-
| <code>Middleware_Service.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>Middleware_Service.exe /uninstall</code> || Remove the service registration
|}

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

=== Testing Before Installing as a Service ===

Before committing to service installation, run Middleware4j in desktop GUI mode using:

Middleware_GUI.exe

This launches a desktop window showing all configured maps, their current status, and real-time message counts. Use this mode to confirm that maps are reading from the correct input directories and that XSLT transformations produce the expected output. Once satisfied, switch to service mode for production deployment.

== Starting on Linux / macOS ==

Use the provided shell script:

./start.sh

The mode (GUI or Service) is passed as an argument by the script. The process runs in the foreground. For production deployment, use systemd, launchd, or nohup to manage it as a background process.

== Verifying the Installation ==

After starting Middleware4j:

# Check <code>logs/</code> for startup messages confirming that each map thread has initialised.
# Place a test input file in the input directory of one of the configured maps.
# Confirm the file is consumed and the expected output appears in the output directory.
# Check <code>interface/log/</code> for the message transaction record.

== Log Files ==

All activity is written to the Log4j log file in the <code>logs/</code> directory. Log rotation and retention are configured in <code>xml/config/log4j2.xml</code>.

See also: [[Overview_Middleware4j]], [[Maps]], [[Connectors]]

[[Category:Middleware4j]]

Installation LabelServer4j

2026-04-05T15:55:35Z

Dgarratt: Updated by push_wiki.py

This page covers deploying LabelServer4j on a server or PC connected to the production network.

== Requirements ==

* Network access to each label printer (TCP/IP — Zebra port 9100, Logopak port 9100 or as configured)
* Network access to the Commander4j server (to receive CSV request files)
* Windows, Linux, or macOS
* Java 21 — required only when running from the distribution archive; the native install package bundles its own Java runtime

== Installation ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method. The installer creates the application directory, copies all configuration templates, and handles the Java runtime dependency automatically.

Alternatively, a distribution archive can be extracted to a suitable directory, for example:

C:\Commander4j\LabelServer4j\ (Windows)
/opt/commander4j/labelserver4j/ (Linux)

The extracted directory contains:

LabelServer.jar
LabelServer.exe (Windows — service launcher)
LabelServerDebug.exe (Windows — console launcher for testing)
start_labeller.cmd (Windows — fallback start script)
start_labeller.sh (Linux/macOS — start script)
lib/
xml/config/
labeller_files/
labeller_requests/
labeller_cmd/
labeller_backups/
logs/

== Configuration Before First Run ==

Before starting LabelServer4j, complete the following configuration steps.

=== 1. Site and Labeller Definitions ===

Edit <code>xml/config/config.xml</code> to set the active site identifier. Then create or edit the <code>labellers.xml</code> file for that site in <code>xml/config/</code>. Each labeller entry defines:

* The labeller name (must match the name used in Commander4j)
* The printer IP address and TCP port
* The path to the command script
* The input directory where Commander4j writes CSV files

See [[LabelServer4j Configuration]] for the full XML structure.

=== 2. Command Scripts ===

Place the command script files (plain text <code>.txt</code> files) for each labeller in the <code>labeller_cmd/</code> directory. The script filename is referenced in <code>labellers.xml</code>.

=== 3. Label Files (Logopak only) ===

If using Logopak printers with stored label templates, place the binary label files in the appropriate subdirectory of <code>labeller_files/</code>. LabelServer4j can upload these to the printer using the <code>SEND_FILE_INTELHEX</code> command.

=== 4. Database Connection (Optional) ===

If the command scripts use <code>DB_QUERY</code> to enrich label data from the Commander4j database, configure the database connection in <code>xml/config/config.xml</code> with the JDBC URL, username, and AES-encrypted password.

=== 5. Email Notifications (Optional) ===

To receive alerts on print failures or service events, configure <code>xml/config/email.xml</code> with SMTP server details and recipient addresses.

== Installing as a Windows Service ==

The native install package includes <code>LabelServer.exe</code>, a service-mode launcher built with install4j. This executable manages the Windows service directly — no additional wrapper (such as WinSW) is required.

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

{| class="wikitable"
|-
! Command !! Effect
|-
| <code>LabelServer.exe /install</code> || Register the Windows service with automatic startup on boot
|-
| <code>LabelServer.exe /install-demand</code> || Register the service with manual startup only
|-
| <code>LabelServer.exe /start</code> || Start the service
|-
| <code>LabelServer.exe /stop</code> || Stop the service (waits for graceful shutdown)
|-
| <code>LabelServer.exe /restart</code> || Restart the service
|-
| <code>LabelServer.exe /status</code> || Query status (exit code: 0 = running, 3 = stopped)
|-
| <code>LabelServer.exe /uninstall</code> || Remove the service registration
|}

Once installed, the service also appears in the Windows Services management console (<code>services.msc</code>) and can be started and stopped from there.

=== Testing Before Installing as a Service ===

Before committing to service installation, run LabelServer4j in a visible console window using the debug launcher:

LabelServerDebug.exe

This runs the same application code with all log output written to the console window. Use this mode to confirm that labellers connect to their printers and that the configuration is correct before installing as a service.

== Starting on Linux / macOS ==

Use the provided shell script:

./start_labeller.sh

Or directly:

java -cp ./LabelServer.jar:./lib/devonly/i4jruntime.jar com.commander4j.labeller.Service

The process runs in the foreground. For production deployment, use a process manager (systemd, launchd, or nohup) to run it as a background service.

== Verifying the Installation ==

After starting LabelServer4j:

# Check <code>logs/c4jLabelServer.log</code> — there should be startup and thread initialisation messages.
# Verify that each labeller thread reports a successful TCP connection to its printer.
# Place a test CSV file in a labeller's input directory to trigger an end-to-end print cycle.
# Confirm the CSV file is consumed (deleted on success, or moved to the error directory on failure).

== Log Files ==

All activity is written to <code>logs/c4jLabelServer.log</code>. Log files rotate at 10 MB and are retained for 14 days.

See also: [[Overview LabelServer4j]], [[LabelServer4j Operation]], [[LabelServer4j Configuration]], [[LabelServer4j Example User Interface]]

[[Category:LabelServer4j]]

AutoLab4j Folder Structure

2026-04-01T15:28:46Z

Dgarratt: Updated by push_wiki.py

This page describes the directory layout of an AutoLab4j installation and the purpose of each folder.

== Directory Layout ==

AutoLab4j/
├── AutoLab.jar
├── lib/
├── xml/
│ ├── config/
│ │ ├── config.xml
│ │ ├── email.xml
│ │ └── log4j2.xml
│ └── sscc/
│ └── PRINTER NAME.xml
├── labels/
├── interface/
│ ├── input/
│ │ └── dataset/
│ └── output/
│ └── ProdDec/
├── remote_dataset/
├── remote_labels/
├── labelary/
├── logs/
└── running/

== File and Folder Descriptions ==

=== AutoLab.jar ===

The main application JAR. When running from the distribution archive, start AutoLab4j with <code>java -jar AutoLab.jar</code>. If installed using the native package, use the shortcut or service entry created by the installer.

=== lib/ ===

Third-party library JARs required by AutoLab4j (referenced in the JAR manifest classpath). Do not modify this directory.

=== xml/config/config.xml ===

The main configuration file. Defines production lines, Modbus connection details, pallet quantities, batch format patterns, and file paths. See [[AutoLab4j Configuration]] for the full structure.

=== xml/config/email.xml ===

SMTP and distribution list settings for email notifications. Used for SSCC warning alerts and service start/stop notifications.

=== xml/config/log4j2.xml ===

Log4j2 logging configuration. Controls log file location, rotation size, and retention period.

=== xml/sscc/ ===

Contains one XML sequence file per printer, named after the printer (for example <code>PRINTER 1.xml</code>). Each file stores the current SSCC prefix, sequence number, check digit, warning limit, and upper limit. AutoLab4j reads and updates these files atomically each time a new SSCC is generated. Back up this directory regularly — it records how far through the SSCC sequence each printer has progressed.

=== labels/ ===

ZPL label template files. The filename of the template to use for each order is specified in the <code>REPORT_FILENAME</code> field of the CSV dataset file. Templates contain ZPL commands with field placeholders such as <code><*MATERIAL*></code> and <code><*SSCC*></code>.

=== interface/input/dataset/ ===

The directory AutoLab4j monitors for incoming CSV dataset files from Commander4j. When Commander4j assigns a process order to a production line, it writes a CSV file here named <code>LINE_NAME_PRINTER_NAME.CSV</code>. This directory is configured as <code>dataSet path</code> in <code>config.xml</code>.

=== interface/output/ProdDec/ ===

Production Declaration XML files are written here after each pallet is printed — one file per SSCC. These files record the SSCC, product, batch, shelf life, and other details for downstream integration. This directory is configured as <code>output path</code> in <code>config.xml</code>.

=== remote_dataset/ ===

An optional secondary location for CSV dataset files, used when the dataset files are delivered from a remote source and need to be synchronised locally before processing. Configured as <code>dataSet path</code> if remote synchronisation is in use.

=== remote_labels/ ===

An optional source directory for label template files. The LabelSync thread copies label files from this directory into <code>labels/</code> at a configurable interval. Used when label templates are maintained centrally and need to be distributed to multiple AutoLab4j instances. Configured as <code>labelSync path</code> in <code>config.xml</code>.

=== labelary/ ===

Cache directory for label preview images fetched from the Labelary API. Each ZPL label that is previewed produces a PNG file here. The cache is used to avoid re-fetching the same label image on repeat prints.

=== logs/ ===

Application log files. The main log file is <code>AutoLab.log</code>. Log files rotate at 10 MB and are retained for 14 days. Review this directory when diagnosing Modbus connection issues, print failures, or SSCC sequence problems.

=== running/ ===

Temporary runtime flag files created by AutoLab4j while it is running. These files are created on startup and removed on clean shutdown. If they remain after an unexpected exit, AutoLab4j will clear them on the next start. Do not modify or delete these files while the service is running.

See also: [[AutoLab4j Configuration]], [[Installation AutoLab4j]], [[Overview AutoLab4j]]

[[Category:AutoLab4j]]

Installation AutoLab4j

2026-04-01T15:28:45Z

Dgarratt: Updated by push_wiki.py

This page covers deploying AutoLab4j on a server or PC connected to the production network.

== Requirements ==

* Network access to the Modbus I/O device on each production line (TCP port 502 by default)
* Network access to each Zebra printer (TCP port 9100)
* Network access to the Commander4j server (to receive CSV dataset files)
* Windows, Linux, or macOS
* Java 21 (JRE or JDK) — required only when running from the distribution archive; the native install package bundles its own Java runtime

== Installation ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method. The installer creates the application directory, registers it with the operating system, and handles the Java runtime dependency automatically.

Alternatively, a distribution archive can be downloaded from the [[Downloads]] page and extracted to a suitable directory, for example:

C:\Commander4j\AutoLab4j\ (Windows)
/opt/commander4j/autolab4j/ (Linux)

The extracted directory contains:

AutoLab.jar
lib/
xml/
labels/
logs/
interface/
running/

== Configuration Before First Run ==

Before starting AutoLab4j, complete the following configuration steps.

=== 1. Production Lines ===

Edit <code>xml/config/config.xml</code> and define each production line. For each line you need:

* The Modbus device IP address and port
* The coil address that signals a pallet complete event
* The coil address for semi-pallet detection
* The printer name (must match the name used in Commander4j)

See [[AutoLab4j Configuration]] for the full XML structure.

=== 2. SSCC Sequence Files ===

Create one SSCC sequence file per printer in <code>xml/sscc/</code>. The filename must match the printer name configured in <code>config.xml</code>. For example, for a printer named <code>PRINTER 1</code>:

xml/sscc/PRINTER 1.xml

The file must contain the SSCC prefix, starting sequence number, warning limit, and upper limit. Your GS1 member organisation will provide the prefix. Example:

<?xml version="1.0" encoding="UTF-8"?>
<sscc>
<prefix>384133182</prefix>
<sequence>00000001</sequence>
<checkDigit>0</checkDigit>
<upperlimit>00009999</upperlimit>
<warninglimit>00009000</warninglimit>
</sscc>

=== 3. Label Templates ===

Copy the ZPL label template files into the <code>labels/</code> directory. The filename for each template is specified in the CSV dataset file in the <code>REPORT_FILENAME</code> field. See [[Zebra ZPL Label]] for information on ZPL label authoring.

=== 4. Dataset Directory ===

Ensure the directory configured as <code>dataSet path</code> in <code>config.xml</code> is accessible. This is where Commander4j writes the CSV files when an operator assigns a process order to a labeller. The directory can be a local path or a network share.

=== 5. Output Directory ===

Ensure the directory configured as <code>output path</code> in <code>config.xml</code> exists and is writable. AutoLab4j writes Production Declaration XML files here after each pallet is printed.

=== 6. Email Notifications (Optional) ===

If you want email alerts for SSCC warnings and service start/stop events, configure <code>xml/config/email.xml</code> with your SMTP server details and distribution lists.

== Starting AutoLab4j ==

If you installed using the native package, start AutoLab4j using the shortcut or service entry created by the installer.

If running from the distribution archive:

=== Windows ===

java -jar AutoLab.jar

AutoLab4j can be installed as a Windows service using a wrapper such as WinSW so that it starts automatically on boot.

=== Linux / macOS ===

java -jar AutoLab.jar

Use systemd, launchd, or nohup for production deployment.

When running, AutoLab4j appears in the system tray with one icon per production line. The System Log window shows startup progress.

== Exclusive Runtime ==

AutoLab4j uses a TCP port (default: 8000) as an exclusive runtime lock. Only one instance can run at a time. If you start a second instance, it sends a shutdown signal to the running instance and waits for it to stop before starting. The watchdog port can be changed in <code>config.xml</code>.

== Verifying the Installation ==

After starting AutoLab4j:

# Check the system tray — there should be one icon per enabled production line.
# Open the System Log window (right-click the system tray icon).
# Verify that each production line shows a Modbus connection attempt in its log window.
# Place a test CSV file in the dataset directory and trigger the Modbus coil to confirm end-to-end operation.

== Log Files ==

All activity is written to <code>logs/AutoLab.log</code>. Log files rotate at 10 MB and are retained for 14 days. Review this file if any production line fails to connect or if labels are not printing.

See also: [[AutoLab4j Configuration]], [[Overview AutoLab4j]], [[AutoLab4j Operation]]

[[Category:AutoLab4j]]

XML Viewer

2026-04-01T15:28:44Z

Dgarratt: Updated by push_wiki.py

XML Viewer is a desktop application for exploring XML documents as an interactive, expandable tree. It supports configurable display modes, multi-language element name translation, and adjustable tree expansion depth. It is designed for viewing structured XML files such as SAP IDoc messages, Commander4j configuration files, and production schedule exports.

== Purpose ==

XML Viewer makes it practical to inspect complex XML files that are difficult to read as raw text. Element names can be translated into plain-language descriptions (for example, the SAP field code <code>ABWKZ</code> becomes "Deviation indicator" in the English translation), and the tree can be expanded to a specific depth to give a high-level overview without showing every leaf value.

== Running XML Viewer ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method.

Alternatively, XML Viewer can be run directly from the distribution archive. It is a Java 21 desktop (Swing) application:

java -jar xmlviewer.jar [optional path to XML file]

If a file path is provided on the command line, that file is opened immediately on launch. Otherwise, the last-opened file from the configuration is loaded.

== Loading a Document ==

Click the '''Open XML Document''' button in the right sidebar, or pass a file path on the command line. Only well-formed XML files are supported. Click '''Reload XML Document''' to re-read the current file after it has been changed externally.

== Display Modes ==

=== Standard Mode ===

The XML hierarchy is displayed exactly as it appears in the file — elements nest within their parent elements, forming a tree that mirrors the XML structure.

=== Flat Mode ===

Leaf elements (those containing only text, no child elements) are collapsed into their parent's row rather than appearing as separate tree nodes. Only elements that contain child elements appear as tree nodes. This produces a more compact view of documents with many small leaf values.

Toggle between modes using the '''View Mode''' button in the right sidebar.

== Tree Expansion Control ==

The top toolbar provides four buttons:

* '''Expand All''' — expand every node in the tree
* '''Expand Selected''' — expand only the selected subtree
* '''Collapse Selected''' — collapse the selected subtree
* '''Collapse All''' — collapse everything to root level

The '''−''' and '''+''' buttons in the toolbar adjust the current expansion level (shown as a number between the buttons). Clicking '''Refresh''' after changing the level re-expands the tree to that depth.

The expansion level is saved in the configuration and restored on next launch.

== Translation ==

XML Viewer can replace technical XML element names and values with plain-language descriptions from a translation file.

=== Enabling Translation ===

Toggle translations using the '''View Translations''' button. The '''Translation''' dropdown at the bottom of the window selects which translation file to use. The '''Language''' dropdown selects the language within that file.

=== Built-in Translation Files ===

{| class="wikitable"
|-
! File !! Contents
|-
| matmas05.xml || SAP MATMAS05 IDoc field translations
|-
| zmatmas03.xml || SAP ZMATMAS03 IDoc field translations
|-
| productionschedule.xml || Production schedule export field translations
|-
| config.xml || Commander4j configuration element translations
|-
| default.xml || Generic fallback translations
|}

=== Languages ===

The default installation includes English, French, German, and Italian. The active language can be changed at any time from the Language dropdown.

=== Adding Translations ===

Translation files are XML documents located in <code>xml/translations/</code>. Each file maps element names, attribute names, element values, and attribute values to their translated equivalents for each language. Elements without a translation entry are shown using their original name from the XML file.

== Other Display Options ==

{| class="wikitable"
|-
! Button !! Effect
|-
| View Icons || Show or hide the icon column next to each tree node
|-
| View Brackets || Wrap element values in <code>[ ]</code> brackets to distinguish them from element names
|}

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>. Stores the last-opened file path, selected translation file, selected language, current expansion level, and the state of all four display toggles (mode, translations, brackets, icons). Updated automatically on exit.

=== log4j2.xml ===

Located at <code>xml/log/log4j2.xml</code>. Controls logging to <code>logs/XML_View.log</code>. Log files rotate at 10 MB and are retained for 14 days.

=== fonts.xml / icons ===

Icons are loaded from <code>images/xmlIcons/</code>. If an icon file referenced by a translation is not found, the icon column is left blank for that element without an error.

See also: [[TreeDoc]], [[Middleware4j]], [[Label Template Syntax]]

[[Category:Commander4j]]

TreeDoc

2026-04-01T15:28:43Z

Dgarratt: Updated by push_wiki.py

TreeDoc is a desktop utility that generates an ASCII directory tree from a folder you select and displays it in a scrollable text window. The output can be copied to the clipboard or saved as a plain text file.

== Purpose ==

TreeDoc is useful for producing a human-readable snapshot of a folder structure — for example, documenting a Commander4j installation layout, comparing the contents of two directories, or quickly exploring an unfamiliar project. The output uses box-drawing characters (├──, └──, │) to show the hierarchy clearly in any monospace environment.

== Running TreeDoc ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method.

Alternatively, TreeDoc can be run directly from the distribution archive. It is a Java 21 desktop (Swing) application:

java -jar Tree.jar

The window opens at 900 × 750 pixels.

== Generating a Tree ==

# Click '''Browse''' to choose the root folder, or type a path directly into the folder field.
# Adjust '''Max Depth''' and '''Max Entries''' if needed (see below).
# Check '''Include Files''' if you want files shown alongside directories.
# Click '''Refresh''' to generate the tree.

The output appears in the central text area. The status bar at the bottom shows the total number of entries printed, and indicates if the output was truncated.

== Options ==

{| class="wikitable"
|-
! Option !! Default !! Description
|-
| Max Depth || 9999 || Maximum folder depth to traverse. Set to a small number (e.g. 3) to get a high-level overview of a deep tree.
|-
| Max Entries || 10,000 || Maximum number of lines to print. Prevents the output from becoming unmanageable for very large trees.
|-
| Include Files || Off || When off, only directory names are shown. When on, files are listed inside their parent directory.
|}

== Output Format ==

The output is plain UTF-8 text using box-drawing characters:

project/
├── src/
│ ├── main/
│ └── test/
├── docs/
└── build.xml

Directories are always included. Files appear indented under their parent directory when '''Include Files''' is enabled.

=== What is Excluded ===

The following are always omitted regardless of settings:

* Hidden files and folders (system hidden flag)
* <code>.DS_Store</code> and <code>.localized</code> (macOS metadata)
* <code>.app</code> bundles (macOS application packages)
* Symbolic links (skipped to prevent infinite loops)

== Saving and Copying Output ==

The right sidebar provides:

* '''Save''' — save the output as a <code>.txt</code> file (default filename: <code>tree.txt</code>, UTF-8 encoded)
* '''Clipboard''' — copy the entire output to the system clipboard
* '''Clear''' — clear the output area

== Configuration ==

TreeDoc saves your last-used folder path and the Include Files checkbox state to <code>xml/config/config.xml</code> automatically on exit. These are restored the next time the application opens.

If the saved folder path no longer exists, TreeDoc prompts you to choose a new folder on startup.

== Log Files ==

Activity is written to <code>logs/TreeDoc.log</code>. Log files rotate at 10 MB and are retained for 14 days.

See also: [[XML Viewer]], [[Menu4j]], [[Downloads]]

[[Category:Commander4j]]

Menu4j

2026-04-01T15:28:41Z

Dgarratt: Updated by push_wiki.py

Menu4j (JMenuTree) is a desktop command launcher that organises shell commands, scripts, and applications into a hierarchical tree menu. It provides a configurable, script-aware alternative to Finder shortcuts and shell aliases, with support for real-time terminal output, multiple linked menu trees, and optional startup password protection.

== Purpose ==

Menu4j is used to organise the day-to-day development and operational commands for the Commander4j suite in a single, structured interface. Menu items can run shell scripts, open applications, pass parameters, capture output, and link to other menu tree files.

== Running Menu4j ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method.

Alternatively, Menu4j can be run directly from the distribution archive. It is a Java 21 desktop (Swing) application:

java -jar JMenu.jar

On first launch, if no configuration file is found, Menu4j copies a template configuration from <code>xml/config/init/config.xml</code> and a template menu tree from <code>xml/tree/init/tree.xml</code>.

If a startup password has been configured, you are prompted to enter it before the menu is shown. Three failed attempts close the application.

== The Menu Tree ==

The main window displays a JTree. There are two node types:

{| class="wikitable"
|-
! Type !! Purpose
|-
| Branch || A folder that contains other branches or leaves
|-
| Leaf || An executable item — a command, script, or application
|}

Double-click a leaf to execute it. Double-click a branch to expand or collapse it.

=== Adding and Editing Items ===

The right sidebar toolbar provides:

* '''Add''' — insert a new branch or leaf under the selected node
* '''Edit''' — open the editor for the selected node
* '''Delete''' — remove the selected node
* '''Duplicate''' — copy the selected node

=== Leaf Properties ===

When editing a leaf node, the following properties are available:

{| class="wikitable"
|-
! Property !! Description
|-
| Description || The label shown in the menu tree
|-
| Directory || The working directory for the command
|-
| Command || The executable or system command to run
|-
| Parameters || A list of arguments to pass to the command
|-
| Shell Script Required || Whether to wrap the command in the configured shell wrapper script
|-
| Terminal Window Required || Whether to open a terminal output window to show command output
|-
| Confirm Execute || Whether to show a confirmation prompt before running
|-
| Link to Menu Tree || Whether this item opens a different tree file instead of running a command
|-
| Hint || A tooltip shown when hovering over the item
|-
| Icon || An image file to display next to the item label
|}

== Executing Commands ==

When a leaf is executed:

# Menu4j validates that the directory and command exist
# If '''Shell Script Required''' is set, the command is wrapped using the script configured in Settings (typically a shell wrapper that sources the user's environment)
# If '''Terminal Window Required''' is set, a terminal output window opens and displays stdout and stderr in real time; otherwise the command runs silently in the background
# Environment variables configured in Settings are injected before execution

=== Terminal Output Window ===

The terminal window displays command output with configurable foreground and background colours and font (configured in Settings). A '''Respond''' button allows text to be sent to the command's standard input for interactive commands. When the command completes, the return code is displayed.

== Multiple Tree Files ==

A leaf node can be configured to switch to a different menu tree rather than execute a command. Set '''Link to Menu Tree''' and specify the filename. Double-clicking the leaf saves the current tree's expansion state and loads the linked tree. The application title bar updates to show the active tree filename.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>. This file stores global settings including the active tree filename, shell script settings, colours, fonts, environment variables, system command whitelist, and the encrypted startup password.

=== tree.xml ===

Located at <code>xml/tree/tree.xml</code> (or a different filename if you have switched trees). This is the menu structure file. It is written automatically when you save from the application.

=== tree.xml.state ===

Located alongside the tree file. Records which branches were expanded on the last exit and restores them on next launch.

== Settings ==

Open Settings from the toolbar to configure:

{| class="wikitable"
|-
! Setting !! Description
|-
| Password || Optional startup password (stored AES-encrypted)
|-
| Shell script || Enable/disable the shell wrapper and set the script filename
|-
| Terminal colours || Foreground and background colours for the terminal output window
|-
| Tree colours || Foreground colours for leaf and branch labels
|-
| Fonts || Font choice and size for the terminal window, leaf labels, and branch labels
|-
| Environment variables || Key/value pairs injected into every executed process
|-
| System commands || Whitelist of system commands (such as <code>open</code>) that do not require a file path to be validated
|}

== Tree Navigation ==

The top toolbar provides four buttons for expanding and collapsing the tree:

* Expand All
* Expand Selected Branch
* Collapse Selected Branch
* Collapse All

== Saving ==

Changes to the tree structure are saved using the '''Save''' button in the sidebar toolbar. You are prompted to save if you close the application with unsaved changes.

See also: [[LaunchPad]], [[Downloads]]

[[Category:Commander4j]]

LaunchPad

2026-04-01T15:28:41Z

Dgarratt: Updated by push_wiki.py

LaunchPad is a macOS application organiser and launcher. It provides a tabbed grid interface for grouping macOS applications (.app bundles) into named categories and launching them with a double-click. It is a companion tool to the Commander4j suite, used to organise the suite's tools and supporting applications in a single place.

== Purpose ==

LaunchPad replaces cluttered Dock folders and aliases with a structured, tabbed grid. Each tab is a named category and each cell in the grid holds one application. Applications are added by browsing or dragging from Finder.

== Running LaunchPad ==

A native macOS install package is available from the [[Downloads]] page and is the preferred installation method.

Alternatively, LaunchPad can be run directly from the distribution archive. It is a Java 21 desktop (Swing) application for macOS:

java -jar JLaunchPad.jar

The window opens at 1300 × 900 pixels. Tabs are listed on the left edge; the grid fills the rest of the window.

== Adding Applications ==

=== Single Application ===

Click the '''Add App''' toolbar button. A file chooser opens, defaulting to <code>/Applications</code> and your home directory. Select any <code>.app</code> bundle. If you select <code>/Applications</code>, LaunchPad also scans <code>/System/Applications</code> and <code>/System/Applications/Utilities</code> automatically.

=== Importing a Folder ===

Click '''Import Folder''' to scan a directory recursively for application bundles. LaunchPad filters out uninstall helpers, login item helpers, and background-only bundles, adding only user-facing applications.

=== Drag and Drop ===

Drag a <code>.app</code> bundle from Finder directly onto the grid or onto a tab. An application can only appear once across all tabs — dragging a duplicate has no effect.

== Grid Layout ==

Each tab contains a 7-column grid of 150 × 150 pixel cells. Each cell displays the application icon (120 × 120 pixels) and the application's display name. Click '''Pack Icons''' to remove empty cells from the current tab, compacting the grid.

Applications can be reordered within the grid by dragging from one cell to another. The same drag operation works between tabs.

== Tab Management ==

The toolbar provides buttons for:

* '''Add Tab''' — create a new named category
* '''Edit Tab''' — rename the selected tab
* '''Delete Tab''' — remove the selected tab (with confirmation)
* '''Move Up / Move Down''' — reorder tabs

== Launching Applications ==

Double-click any application icon to launch it. LaunchPad uses the macOS <code>open</code> command to launch the bundle, so the application opens exactly as if you had double-clicked it in Finder.

== Cell Context Menu ==

Right-click any cell or application to access:

* '''Assign Custom Icon...''' — replace the icon with any PNG, JPG, GIF, or ICNS image
* '''Remove App''' — clear the cell
* '''Reveal in Finder''' — open the application's location in Finder

== Icon Resolution ==

When an application is added, LaunchPad attempts to extract its icon automatically. It tries the following in order:

# The <code>.icns</code> file named in the app's <code>Info.plist</code>
# PNG icons listed in <code>Info.plist</code> under <code>CFBundleIcons</code>
# The app's <code>Assets.car</code> (rendered via QuickLook)
# A generic system icon as a last resort

Extracted icons are scaled to 120 × 120 pixels and cached to <code>images/appIcons/</code> on disk. On subsequent launches the cached PNG is used unless the app itself has been updated.

== Configuration ==

LaunchPad saves its state automatically on exit and restores it on the next launch.

=== launchpad.xml ===

Located at <code>xml/config/launchpad.xml</code>. This file records all tabs, their names, and the path of each application in the grid. It is written automatically — you do not need to edit it manually.

=== images/appIcons/ ===

The icon cache directory. Each application has a <code><BundleName>.png</code> file here. If you use '''Assign Custom Icon...''', the cache file for that application is overwritten with your chosen image.

See also: [[Menu4j]], [[ZPLRenderer]], [[Downloads]]

[[Category:Commander4j]]

ZPLRenderer

2026-04-01T15:28:39Z

Dgarratt: Updated by push_wiki.py

ZPL Renderer is a desktop application that interprets ZPL (Zebra Programming Language) commands and renders them as a visual preview of what a label will look like when printed on a physical Zebra printer. It is a companion tool to Commander4j, LabelServer4j, and AutoLab4j.

== Purpose ==

ZPL is a text-based command language used to define label layouts, text, graphics, and barcodes for Zebra label printers. The commands are sent directly to the printer as a stream of characters and are not human-readable. ZPL Renderer allows you to:

* Load a ZPL file and see what the label will look like before sending it to a printer
* Listen on a network socket so that any application sending ZPL to that port renders the label on screen in real time
* Zoom in and out to examine label detail
* Preview multiple labels from a single ZPL stream
* Export the rendered label to PDF
* Print the rendered label directly from the application

== Running ZPL Renderer ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method.

Alternatively, ZPL Renderer can be run directly from the distribution archive. It is a Java 21 desktop (Swing) application:

java -jar zplrenderer.jar

On first launch it reads its configuration from <code>xml/config/config.xml</code>.

== Loading a ZPL File ==

Use the '''Open''' toolbar button to load a <code>.zpl</code> text file from disk. The label is rendered immediately. Use '''Refresh''' to reload the file after editing it externally.

Several example ZPL files are included in the <code>examples/</code> directory:

{| class="wikitable"
|-
! File !! Contents
|-
| example1.zpl || Shipping label with QR code, text, and graphics
|-
| example2.zpl || Complex layout with boxes, barcodes, and logo
|-
| barcodes.zpl || Showcase of all supported barcode types
|-
| pallet_labels.zpl || Pallet label examples typical of Commander4j output
|-
| fonts.zpl || Font size and style demonstration
|-
| shipping.zpl || Shipping label sample
|-
| character.zpl || Character set reference
|-
| grid.zpl || Layout grid for alignment reference
|}

== Network Socket Mode ==

ZPL Renderer can listen on a TCP/IP port and render any ZPL label stream sent to it. This allows Commander4j, LabelServer4j, or any other application to use ZPL Renderer as a virtual printer — sending ZPL to the socket and seeing the result on screen instead of printing to paper.

The default port is '''9100''' (the standard Zebra raw print port). The IP address and port are configured in <code>config.xml</code>. Enable listening using the '''Network''' button in the toolbar.

ZPL Renderer extracts complete label blocks from the stream, identified by the standard <code>^XA</code> (start of label) and <code>^XZ</code> (end of label) delimiters.

== Zoom ==

Use the zoom controls in the toolbar to scale the rendered label between 0.10× and 2.00×. The default zoom is configured in <code>config.xml</code> (default: 0.5×). This is useful for examining barcode detail or checking overall label proportions.

== Multiple Labels ==

When a ZPL file or network stream contains multiple labels, ZPL Renderer displays them as pages. Navigation controls allow stepping through each label. The maximum number of pages displayed is configurable (default: 3).

== Export and Print ==

* '''PDF Export''' — saves the rendered label as a vector PDF using Apache PDFBox
* '''Print''' — sends the rendered label to a system printer

== Supported ZPL Commands ==

ZPL Renderer supports over 100 ZPL commands. Key categories:

=== Label Setup ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^XA || Start of label
|-
| ^XZ || End of label
|-
| ^LL || Label length
|-
| ^LH || Label home (origin offset)
|-
| ^LT || Label top offset
|-
| ^PQ || Print quantity
|-
| ^CD || Change delimiter character
|-
| ^CC || Change caret character
|}

=== Text and Fields ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^FO || Field origin (X,Y position from top-left)
|-
| ^FT || Field typeset (X,Y position from bottom-left)
|-
| ^FD || Field data (the text content)
|-
| ^FS || Field separator
|-
| ^FR || Field reverse (inverted colours)
|-
| ^FW || Field orientation/rotation
|-
| ^FX || Comment (ignored in output)
|}

=== Fonts ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^A0–^AZ || Select font by ID
|-
| ^CF || Change default alphanumeric font
|-
| ^CI || Change international character set/encoding
|}

=== Graphics ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^GB || Graphic box (rectangle)
|-
| ^GC || Graphic circle
|-
| ^GD || Graphic diagonal line
|-
| ^GE || Graphic ellipse
|-
| ^GF || Graphic field (embedded image data)
|-
| ^GS || Graphic symbol
|}

=== Barcodes ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^BC || Code 128 / GS1-128 (EAN-128)
|-
| ^BE || EAN-13
|-
| ^B8 || EAN-8
|-
| ^B3 || Code 39
|-
| ^B2 || Interleaved 2 of 5
|-
| ^B1 || Code 11
|-
| ^BQ || QR Code
|-
| ^B7 || PDF417
|-
| ^B0 / ^BO || Aztec
|-
| ^BY || Bar code field defaults (width, ratio, height)
|}

Barcode rendering uses the OkapiBarcode library. GS1 application identifiers are interpreted from <code>xml/config/gs1_app_defs.xml</code>.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>:

{| class="wikitable"
|-
! Setting !! Description
|-
| Input folder || Default directory for ZPL file loading (default: <code>./examples</code>)
|-
| Port || Network socket port to listen on (default: 9100)
|-
| Default magnification || Starting zoom level (default: 0.5)
|-
| Max pages || Maximum number of label pages to display (default: 3)
|}

=== fonts.xml ===

Located at <code>xml/config/fonts.xml</code>, this file maps ZPL font IDs (0, A–Z) to TrueType font files and defines their pixel dimensions. This allows ZPL Renderer to simulate the fonts installed in a physical Zebra printer.

Included fonts: Bitstream Vera, Anonymous Pro, ATTriumvirate.

If your labels use fonts that differ from the defaults, edit <code>fonts.xml</code> to match the font metrics of your target printer.

== Relationship to Commander4j ==

Commander4j generates ZPL label streams for pallet and case labels. ZPL Renderer allows you to preview these labels before deploying them to production printers, and to verify that label templates produce the correct output after making changes to the template syntax. See [[Label Template Syntax]] and [[Zebra ZPL Label]] for information on ZPL label authoring within Commander4j.

See also: [[Zebra ZPL Label]], [[Label Template Syntax]], [[Printer Queues]], [[Production Lines & Labellers]]

[[Category:Commander4j]]

SocketTest

2026-04-01T15:28:29Z

Dgarratt: Updated by push_wiki.py

SocketTest is a TCP/IP network testing utility with a graphical interface. It acts as both a TCP client and a TCP server, allowing you to send and receive arbitrary data over a socket connection, debug protocol implementations, and simulate network endpoints. It is a companion tool to LabelServer4j, AutoLab4j, and ZPL Renderer, which all communicate with devices over raw TCP/IP sockets.

== Purpose ==

SocketTest is useful when:

* Testing whether a printer or other device is accepting connections on a given IP address and port
* Checking what a device responds with when given a specific command
* Sending raw ZPL or Logopak commands to a printer to verify a script without running the full service
* Acting as a test server to capture what LabelServer4j or AutoLab4j is actually transmitting

== Running SocketTest ==

Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method.

Alternatively, SocketTest can be run directly from the distribution archive. It is a Java 21 desktop (Swing) application:

java -jar SocketTest.jar

The main window contains two tabs: '''Client''' and '''Server'''. Both tabs can be used independently or together in proxy mode.

== Client Tab ==

The client tab connects to a remote TCP server.

=== Connecting ===

Enter the IP address and port of the remote server and click '''Connect'''. The IP address dropdown is pre-populated with the network interfaces found on the local machine. The default port is '''9100''' (the standard raw Zebra print port).

=== Sending Data ===

Type or load the message you want to send in the left-hand text area. Use the prefix and suffix dropdowns to select control character sequences that will be prepended or appended to the message:

{| class="wikitable"
|-
! Token !! Character
|-
| (none) || No delimiter
|-
| <code><CR></code> || Carriage return (0x0D)
|-
| <code><LF></code> || Line feed (0x0A)
|-
| <code><CR><LF></code> || Carriage return + line feed
|-
| <code><STX></code> || Start of text (0x02)
|-
| <code><ETX></code> || End of text (0x03)
|-
| <code><ESC></code> || Escape (0x1B)
|-
| <code><ACK></code> || Acknowledge (0x06)
|-
| <code><NAK></code> || Negative acknowledge (0x15)
|}

Click '''Send''' to transmit. The right-hand log pane shows all data sent and received, colour-coded in green on a black background.

=== Loading and Saving Messages ===

Use '''Load''' to populate the input area from a text file, and '''Save''' to persist the input area contents. Use '''Clear''' and '''Save''' on the log pane to manage the communication history.

== Server Tab ==

The server tab listens for incoming TCP connections.

=== Starting the Server ===

Enter the bind IP address (or <code>0.0.0.0</code> to listen on all interfaces) and the port, then click '''Open'''. When a client connects, its hostname and IP address are shown in the panel border. The '''Disconnect''' button closes the current client connection without stopping the server.

=== Sending Responses ===

Once a client is connected you can type a response in the input area and click '''Send''' to transmit it back to the client. All data received from the client is shown in the log pane, colour-coded in white on a black background.

== Proxy Mode ==

The '''Proxy''' button on the server tab enables transparent data relay. When proxy mode is active, data received on the server side is automatically forwarded to whatever the client tab is connected to, and vice versa. This allows SocketTest to sit between a client and a real device and relay all traffic in both directions, which is useful for capturing a complete protocol conversation.

== Control Characters ==

Control characters are entered in human-readable token notation (<code><STX></code>, <code><CR></code>, etc.) in the input area and converted to the actual byte values before transmission. Incoming bytes are decoded back to token notation in the log. SocketTest supports the full standard ASCII control character set (NUL through DEL).

== Configuration ==

SocketTest has no persistent configuration file. IP addresses, ports, and message formatting options are per-session only and reset when the application is closed.

== Log Files ==

SocketTest does not write a log file. All communication history is displayed in the on-screen log panes and can optionally be saved to a text file using the Save button on each pane.

See also: [[LabelServer4j]], [[ZPLRenderer]], [[Production Lines & Labellers]]

[[Category:Commander4j]]

Installation AutoLab4j

2026-04-01T11:35:25Z

Dgarratt: Updated by push_wiki.py

This page covers deploying AutoLab4j on a server or PC connected to the production network.

== Requirements ==

* Java 21 (JRE or JDK)
* Network access to the Modbus I/O device on each production line (TCP port 502 by default)
* Network access to each Zebra printer (TCP port 9100)
* Network access to the Commander4j server (to receive CSV dataset files)
* Windows, Linux, or macOS

== Installation ==

Download the AutoLab4j distribution from the [[Downloads]] page and extract it to a suitable directory, for example:

C:\Commander4j\AutoLab4j\ (Windows)
/opt/commander4j/autolab4j/ (Linux)

The extracted directory contains:

AutoLab.jar
lib/
xml/
labels/
logs/
interface/
running/

== Configuration Before First Run ==

Before starting AutoLab4j, complete the following configuration steps.

=== 1. Production Lines ===

Edit <code>xml/config/config.xml</code> and define each production line. For each line you need:

* The Modbus device IP address and port
* The coil address that signals a pallet complete event
* The coil address for semi-pallet detection
* The printer name (must match the name used in Commander4j)

See [[AutoLab4j Configuration]] for the full XML structure.

=== 2. SSCC Sequence Files ===

Create one SSCC sequence file per printer in <code>xml/sscc/</code>. The filename must match the printer name configured in <code>config.xml</code>. For example, for a printer named <code>PRINTER 1</code>:

xml/sscc/PRINTER 1.xml

The file must contain the SSCC prefix, starting sequence number, warning limit, and upper limit. Your GS1 member organisation will provide the prefix. Example:

<?xml version="1.0" encoding="UTF-8"?>
<sscc>
<prefix>384133182</prefix>
<sequence>00000001</sequence>
<checkDigit>0</checkDigit>
<upperlimit>00009999</upperlimit>
<warninglimit>00009000</warninglimit>
</sscc>

=== 3. Label Templates ===

Copy the ZPL label template files into the <code>labels/</code> directory. The filename for each template is specified in the CSV dataset file in the <code>REPORT_FILENAME</code> field. See [[Zebra ZPL Label]] for information on ZPL label authoring.

=== 4. Dataset Directory ===

Ensure the directory configured as <code>dataSet path</code> in <code>config.xml</code> is accessible. This is where Commander4j writes the CSV files when an operator assigns a process order to a labeller. The directory can be a local path or a network share.

=== 5. Output Directory ===

Ensure the directory configured as <code>output path</code> in <code>config.xml</code> exists and is writable. AutoLab4j writes Production Declaration XML files here after each pallet is printed.

=== 6. Email Notifications (Optional) ===

If you want email alerts for SSCC warnings and service start/stop events, configure <code>xml/config/email.xml</code> with your SMTP server details and distribution lists.

== Starting AutoLab4j ==

=== Windows ===

java -jar AutoLab.jar

AutoLab4j can be installed as a Windows service using a wrapper such as WinSW so that it starts automatically on boot.

=== Linux / macOS ===

java -jar AutoLab.jar

Use systemd, launchd, or nohup for production deployment.

When running, AutoLab4j appears in the system tray with one icon per production line. The System Log window shows startup progress.

== Exclusive Runtime ==

AutoLab4j uses a TCP port (default: 8000) as an exclusive runtime lock. Only one instance can run at a time. If you start a second instance, it sends a shutdown signal to the running instance and waits for it to stop before starting. The watchdog port can be changed in <code>config.xml</code>.

== Verifying the Installation ==

After starting AutoLab4j:

# Check the system tray — there should be one icon per enabled production line.
# Open the System Log window (right-click the system tray icon).
# Verify that each production line shows a Modbus connection attempt in its log window.
# Place a test CSV file in the dataset directory and trigger the Modbus coil to confirm end-to-end operation.

== Log Files ==

All activity is written to <code>logs/AutoLab.log</code>. Log files rotate at 10 MB and are retained for 14 days. Review this file if any production line fails to connect or if labels are not printing.

See also: [[AutoLab4j Configuration]], [[Overview AutoLab4j]], [[AutoLab4j Operation]]

[[Category:AutoLab4j]]

AutoLab4j Folder Structure

2026-04-01T11:35:23Z

Dgarratt: Updated by push_wiki.py

This page describes the directory layout of an AutoLab4j installation and the purpose of each folder.

== Directory Layout ==

AutoLab4j/
├── AutoLab.jar
├── lib/
├── xml/
│ ├── config/
│ │ ├── config.xml
│ │ ├── email.xml
│ │ └── log4j2.xml
│ └── sscc/
│ └── PRINTER NAME.xml
├── labels/
├── interface/
│ ├── input/
│ │ └── dataset/
│ └── output/
│ └── ProdDec/
├── remote_dataset/
├── remote_labels/
├── labelary/
├── logs/
└── running/

== File and Folder Descriptions ==

=== AutoLab.jar ===

The main application JAR. Start AutoLab4j by running <code>java -jar AutoLab.jar</code>.

=== lib/ ===

Third-party library JARs required by AutoLab4j (referenced in the JAR manifest classpath). Do not modify this directory.

=== xml/config/config.xml ===

The main configuration file. Defines production lines, Modbus connection details, pallet quantities, batch format patterns, and file paths. See [[AutoLab4j Configuration]] for the full structure.

=== xml/config/email.xml ===

SMTP and distribution list settings for email notifications. Used for SSCC warning alerts and service start/stop notifications.

=== xml/config/log4j2.xml ===

Log4j2 logging configuration. Controls log file location, rotation size, and retention period.

=== xml/sscc/ ===

Contains one XML sequence file per printer, named after the printer (for example <code>PRINTER 1.xml</code>). Each file stores the current SSCC prefix, sequence number, check digit, warning limit, and upper limit. AutoLab4j reads and updates these files atomically each time a new SSCC is generated. Back up this directory regularly — it records how far through the SSCC sequence each printer has progressed.

=== labels/ ===

ZPL label template files. The filename of the template to use for each order is specified in the <code>REPORT_FILENAME</code> field of the CSV dataset file. Templates contain ZPL commands with field placeholders such as <code><*MATERIAL*></code> and <code><*SSCC*></code>.

=== interface/input/dataset/ ===

The directory AutoLab4j monitors for incoming CSV dataset files from Commander4j. When Commander4j assigns a process order to a production line, it writes a CSV file here named <code>LINE_NAME_PRINTER_NAME.CSV</code>. This directory is configured as <code>dataSet path</code> in <code>config.xml</code>.

=== interface/output/ProdDec/ ===

Production Declaration XML files are written here after each pallet is printed — one file per SSCC. These files record the SSCC, product, batch, shelf life, and other details for downstream integration. This directory is configured as <code>output path</code> in <code>config.xml</code>.

=== remote_dataset/ ===

An optional secondary location for CSV dataset files, used when the dataset files are delivered from a remote source and need to be synchronised locally before processing. Configured as <code>dataSet path</code> if remote synchronisation is in use.

=== remote_labels/ ===

An optional source directory for label template files. The LabelSync thread copies label files from this directory into <code>labels/</code> at a configurable interval. Used when label templates are maintained centrally and need to be distributed to multiple AutoLab4j instances. Configured as <code>labelSync path</code> in <code>config.xml</code>.

=== labelary/ ===

Cache directory for label preview images fetched from the Labelary API. Each ZPL label that is previewed produces a PNG file here. The cache is used to avoid re-fetching the same label image on repeat prints.

=== logs/ ===

Application log files. The main log file is <code>AutoLab.log</code>. Log files rotate at 10 MB and are retained for 14 days. Review this directory when diagnosing Modbus connection issues, print failures, or SSCC sequence problems.

=== running/ ===

Temporary runtime flag files created by AutoLab4j while it is running. These files are created on startup and removed on clean shutdown. If they remain after an unexpected exit, AutoLab4j will clear them on the next start. Do not modify or delete these files while the service is running.

See also: [[AutoLab4j Configuration]], [[Installation AutoLab4j]], [[Overview AutoLab4j]]

[[Category:AutoLab4j]]

AutoLab4j Dataset CSV

2026-04-01T11:35:22Z

Dgarratt: Updated by push_wiki.py

When an operator assigns a [[Process Orders|Process Order]] to a production line in Commander4j, a CSV data file is written to the dataset directory monitored by AutoLab4j. This file contains all the product and order information AutoLab4j needs to generate and print labels.

== File Naming ==

The CSV filename follows the format:

LINE_NAME_PRINTER_NAME.CSV

For example, a production line named <code>LINE 1</code> with a printer named <code>PRINTER 1</code> produces:

LINE 1_PRINTER 1.CSV

AutoLab4j monitors the configured dataset directory and loads this file as soon as it appears. If a new file arrives while production is active, it replaces the previous data immediately.

== File Format ==

The file contains a header row followed by a single data row. Fields are comma-separated. The column headers are used to map values to named variables in the label template and print configuration.

== Fields ==

=== Order and Product ===

{| class="wikitable"
|-
! Field !! Description
|-
| PROCESS_ORDER || The process order number from Commander4j
|-
| MATERIAL || The material/product code
|-
| DESCRIPTION || Product description
|-
| CUSTOMER_ID || Customer identifier, used to look up batch format patterns in config.xml
|-
| LANGUAGE || Language code for label content
|-
| REPORT_FILENAME || Filename of the ZPL label template to use (looked up in the <code>labels/</code> directory)
|}

=== Batch and Expiry ===

{| class="wikitable"
|-
! Field !! Description
|-
| BATCH_FORMAT || Batch number format pattern (overrides the customer default in config.xml if present)
|-
| BATCH_NUMBER || Pre-calculated batch number (used directly if BATCH_FORMAT is not specified)
|-
| BATCH_PREFIX || Optional prefix prepended to the calculated batch number
|-
| DATE_OF_MANUFACTURE || Manufacturing date, used as the base for expiry date calculation
|-
| EXPIRY_DATE || Pre-calculated expiry date (used directly if shelf life fields are not present)
|-
| SHELF_LIFE || Numeric shelf life value
|-
| SHELF_LIFE_UOM || Shelf life unit of measure (D = days, M = months, Y = years)
|-
| SHELF_LIFE_RULE || Rule for how the expiry date is calculated from the manufacture date and shelf life
|}

=== Barcodes and Identifiers ===

{| class="wikitable"
|-
! Field !! Description
|-
| EAN || EAN-13 barcode value for the product (trading unit barcode)
|-
| PROD_EAN || EAN used specifically for the production label barcode (may differ from EAN)
|}

=== Pallet Configuration ===

{| class="wikitable"
|-
! Field !! Description
|-
| SSCC_PER_PALLET || Number of SSCCs (pallet labels) to generate for a full pallet
|-
| LABELS_PER_SSCC || Number of label copies to print for each SSCC
|}

=== Printer Destination ===

{| class="wikitable"
|-
! Field !! Description
|-
| IP_ADDRESS || IP address of the Zebra printer for this line
|-
| PORT || TCP port of the Zebra printer (typically 9100)
|}

== Field Substitution in Label Templates ==

All fields in the CSV are available as placeholders in the ZPL label template using the syntax <code><*FIELD_NAME*></code>. For example:

* <code><*MATERIAL*></code> is replaced with the MATERIAL field value
* <code><*SSCC*></code> is replaced with the generated SSCC
* <code><*EXPIRY_DATE*></code> is replaced with the calculated expiry date

The <code>fieldNamesLookup</code> section in <code>config.xml</code> can map CSV field names to different template placeholder names if the CSV field names do not match the placeholder names in the template. The <code>clone</code> section can copy a field value under an additional name, and the <code>formats</code> section can apply numeric formatting to a field before substitution.

== SSCC Field ==

The SSCC is not present in the CSV file — it is generated by AutoLab4j at print time from the sequence file for the printer. It is available in the label template as <code><*SSCC*></code>.

See also: [[AutoLab4j Operation]], [[AutoLab4j Configuration]], [[Zebra ZPL Label]], [[Label Template Syntax]]

[[Category:AutoLab4j]]

AutoLab4j Operation

2026-04-01T11:35:21Z

Dgarratt: Updated by push_wiki.py

This page describes the end-to-end operational workflow of AutoLab4j — from an operator assigning a process order in Commander4j through to a label being printed on the production line.

== Step 1 — Assign a Process Order ==

In the Commander4j desktop application, an operator assigns a [[Process Orders|Process Order]] to a production line using the [[Process Order Assign to Labeller|Pallet Labelling]] screen.

Commander4j validates the assignment and writes a CSV data file to the dataset directory configured for that line. The filename follows the format <code>LINE_NAME_PRINTER_NAME.CSV</code>. See [[AutoLab4j Dataset CSV]] for the full list of fields in this file.

== Step 2 — Data File Detection ==

AutoLab4j monitors the dataset directory continuously. When the CSV file appears, it is parsed and all fields are loaded into memory and made available to the label generation and Modbus threads for that production line.

If a new CSV file arrives while production is active, it replaces the previous data immediately. The next pallet printed will use the new product information.

== Step 3 — Modbus Polling ==

AutoLab4j polls the Modbus coil address configured for the production line every 250 ms. When the coil transitions to the configured trigger value (typically <code>true</code>), a print sequence is initiated.

A second coil address is read at the same time to determine whether this is a full pallet or a semi-pallet. Full pallets and semi-pallets can have different quantities of SSCCs per pallet and labels per SSCC, as configured in <code>config.xml</code>.

== Step 4 — SSCC Generation ==

For each SSCC to be printed on the pallet, AutoLab4j reads the next sequence number from the SSCC sequence file for this printer (<code>xml/sscc/PRINTER_NAME.xml</code>), calculates the EAN-13 check digit, and composes the 18-digit SSCC. The sequence file is updated immediately after each read so that the number is never reused even if the application restarts.

If the sequence number reaches the configured warning limit, an email alert is sent to the SSCC distribution list.

== Step 5 — Label Generation ==

For each label to be printed, AutoLab4j loads the ZPL label template specified in the <code>REPORT_FILENAME</code> field of the CSV file. Field placeholders in the template (for example <code><*MATERIAL*></code>, <code><*SSCC*></code>, <code><*EXPIRY_DATE*></code>) are replaced with values from the dataset.

Batch numbers are calculated dynamically from the pattern configured for the customer in <code>config.xml</code>, using values such as the Julian day, week number, year, or process order number.

Expiry dates are calculated from the date of manufacture and shelf life values in the CSV.

== Step 6 — Sending to the Printer ==

The completed ZPL is sent to the printer's IP address and port (read from the CSV dataset) over a raw TCP/IP socket connection on port 9100. AutoLab4j waits for the print thread to confirm transmission before moving to the next label.

If the Labelary preview is enabled, the ZPL is also sent to the Labelary API to render a preview image, which is displayed in the preview window on screen.

== Step 7 — Production Declaration ==

After all labels for the pallet have been printed, AutoLab4j writes a Production Declaration XML file to the output directory. One file is produced per SSCC. The file records the SSCC, product, batch number, shelf life, and other details for downstream integration.

== Step 8 — Ready for Next Pallet ==

The Modbus poller immediately resumes monitoring for the next coil transition. When the signal fires again, the same process repeats with the next SSCC sequence number.

== Monitoring ==

=== System Tray Icons ===

AutoLab4j shows one system tray icon per production line. The icon colour indicates status:

{| class="wikitable"
|-
! Colour !! Meaning
|-
| Green || Operating normally
|-
| Yellow || Warning (SSCC sequence approaching limit)
|-
| Red || Error (Modbus connection failure or print failure)
|}

Right-click any tray icon for options:

* '''Information''' — shows the Modbus and printer connection details for that line
* '''View Order''' — shows the current product data loaded from the CSV
* '''View Log''' — opens the notification window for that line

=== Log Windows ===

Each production line has its own notification window showing the last 50 log messages for that line. A separate System Log window shows service-level events. Right-click the system tray icon and select '''View Log''' to open it.

=== Log Files ===

All activity is written to <code>logs/AutoLab.log</code> with rolling rotation (10 MB per file, 14 days retention). The log records every Modbus poll result, every SSCC generated, every label sent, and every print confirmation.

== Changing the Active Product ==

To switch product on a running line, an operator assigns a new process order in Commander4j. Commander4j overwrites the CSV file in the dataset directory. AutoLab4j detects the new file and loads it. The next Modbus trigger will use the new product data.

== Stopping AutoLab4j ==

Stopping the service (via Windows Services, Ctrl+C, or the system tray Exit option) triggers a graceful shutdown. AutoLab4j signals all threads to stop, waits for any in-progress print jobs to complete, flushes the email queue, and exits cleanly.

See also: [[Overview AutoLab4j]], [[AutoLab4j Configuration]], [[AutoLab4j Dataset CSV]], [[Installation AutoLab4j]]

[[Category:AutoLab4j]]

Overview AutoLab4j

2026-04-01T11:35:20Z

Dgarratt: Updated by push_wiki.py

AutoLab4j is an automated label printing and SSCC generation service for production lines. It monitors Modbus digital signals from production equipment, reads product data from CSV files exported by Commander4j, generates ZPL labels, sends them to networked Zebra printers over TCP/IP, and produces Production Declaration XML documents for each pallet printed.

== Purpose ==

When a pallet is complete on a production line, the line's PLC or I/O module raises a Modbus coil signal. AutoLab4j detects this signal, generates a unique SSCC (Serial Shipping Container Code), builds the ZPL label from the active product data and label template, and sends it to the printer — all without any operator interaction.

This separates label printing from the Commander4j desktop application and ties it directly to the physical production event rather than a manual operator action.

== Difference from LabelServer4j ==

AutoLab4j and LabelServer4j both print labels from Commander4j data, but serve different roles:

{| class="wikitable"
|-
! Feature !! AutoLab4j !! LabelServer4j
|-
| Typical use || Pallet labellers || Case and secondary labellers
|-
| Print trigger || Modbus coil signal from production line equipment || CSV file placed by Commander4j
|-
| SSCC generation || Yes — generates unique SSCCs automatically || No — SSCC is supplied in the CSV
|-
| User interface || Graphical window with per-line status displays || None — background service only
|-
| Output documents || Produces Production Declaration XML per pallet || No output documents
|}

== How It Works ==

# Commander4j writes a CSV data file to the configured dataset directory when an operator assigns a process order to a production line.
# AutoLab4j monitors that directory. When a CSV file appears, it reads the product data into memory.
# AutoLab4j polls the Modbus coil address for the production line every 250 ms.
# When the coil signal matches the configured trigger value, AutoLab4j reads the semi-pallet coil to determine whether this is a full or semi pallet.
# For each SSCC in the pallet, AutoLab4j generates a unique SSCC number, builds the ZPL label from the template, and sends it to the printer over TCP/IP (port 9100).
# After printing, a Production Declaration XML file is written to the output directory.
# The SSCC sequence number is incremented and persisted to disk.

== SSCC Generation ==

SSCC numbers are generated from a configurable prefix and an incrementing sequence number. The sequence is stored in a per-printer XML file and updated atomically after each print. When the sequence approaches the configured warning limit, AutoLab4j sends an email alert. When it reaches the upper limit, printing stops until the sequence file is reset.

== Pallet and Semi-Pallet Support ==

Two Modbus coil addresses are used per production line:

* A primary coil that signals a pallet is complete and a label should be printed
* A semi-pallet coil that determines whether this is a full pallet or a semi-pallet

Full pallets and semi-pallets can be configured with different quantities of SSCCs per pallet and labels per SSCC.

== Supported Printer Types ==

AutoLab4j communicates with printers using ZPL (Zebra Programming Language) over raw TCP/IP sockets. Any printer that accepts raw ZPL on a configurable IP address and port is supported.

== Multi-Line Support ==

AutoLab4j supports multiple production lines simultaneously. Each line runs its own independent set of threads (dataset monitor, Modbus poller, print handler) and has its own system tray icon showing the current status.

== Label Preview ==

If enabled, AutoLab4j calls the Labelary web API to render each ZPL label as a PNG image and displays it on screen before sending to the printer. This provides a visual confirmation that the correct label is being printed.

== Production Declaration Output ==

After each pallet is printed, AutoLab4j writes an XML Production Declaration file to the configured output directory. This document records the SSCC, product, batch, shelf life, and other details for downstream integration.

See also: [[AutoLab4j Configuration]], [[AutoLab4j Operation]], [[AutoLab4j Dataset CSV]], [[LabelServer4j]]

[[Category:AutoLab4j]]

TreeDoc

2026-04-01T11:29:49Z

Dgarratt: Updated by push_wiki.py

TreeDoc is a desktop utility that generates an ASCII directory tree from a folder you select and displays it in a scrollable text window. The output can be copied to the clipboard or saved as a plain text file.

== Purpose ==

TreeDoc is useful for producing a human-readable snapshot of a folder structure — for example, documenting a Commander4j installation layout, comparing the contents of two directories, or quickly exploring an unfamiliar project. The output uses box-drawing characters (├──, └──, │) to show the hierarchy clearly in any monospace environment.

== Running TreeDoc ==

TreeDoc is a Java 21 desktop (Swing) application:

java -jar Tree.jar

The window opens at 900 × 750 pixels.

== Generating a Tree ==

# Click '''Browse''' to choose the root folder, or type a path directly into the folder field.
# Adjust '''Max Depth''' and '''Max Entries''' if needed (see below).
# Check '''Include Files''' if you want files shown alongside directories.
# Click '''Refresh''' to generate the tree.

The output appears in the central text area. The status bar at the bottom shows the total number of entries printed, and indicates if the output was truncated.

== Options ==

{| class="wikitable"
|-
! Option !! Default !! Description
|-
| Max Depth || 9999 || Maximum folder depth to traverse. Set to a small number (e.g. 3) to get a high-level overview of a deep tree.
|-
| Max Entries || 10,000 || Maximum number of lines to print. Prevents the output from becoming unmanageable for very large trees.
|-
| Include Files || Off || When off, only directory names are shown. When on, files are listed inside their parent directory.
|}

== Output Format ==

The output is plain UTF-8 text using box-drawing characters:

project/
├── src/
│ ├── main/
│ └── test/
├── docs/
└── build.xml

Directories are always included. Files appear indented under their parent directory when '''Include Files''' is enabled.

=== What is Excluded ===

The following are always omitted regardless of settings:

* Hidden files and folders (system hidden flag)
* <code>.DS_Store</code> and <code>.localized</code> (macOS metadata)
* <code>.app</code> bundles (macOS application packages)
* Symbolic links (skipped to prevent infinite loops)

== Saving and Copying Output ==

The right sidebar provides:

* '''Save''' — save the output as a <code>.txt</code> file (default filename: <code>tree.txt</code>, UTF-8 encoded)
* '''Clipboard''' — copy the entire output to the system clipboard
* '''Clear''' — clear the output area

== Configuration ==

TreeDoc saves your last-used folder path and the Include Files checkbox state to <code>xml/config/config.xml</code> automatically on exit. These are restored the next time the application opens.

If the saved folder path no longer exists, TreeDoc prompts you to choose a new folder on startup.

== Log Files ==

Activity is written to <code>logs/TreeDoc.log</code>. Log files rotate at 10 MB and are retained for 14 days.

See also: [[XML Viewer]], [[Menu4j]], [[Downloads]]

[[Category:Commander4j]]

Menu4j

2026-04-01T11:29:48Z

Dgarratt: Updated by push_wiki.py

Menu4j (JMenuTree) is a desktop command launcher that organises shell commands, scripts, and applications into a hierarchical tree menu. It provides a configurable, script-aware alternative to Finder shortcuts and shell aliases, with support for real-time terminal output, multiple linked menu trees, and optional startup password protection.

== Purpose ==

Menu4j is used to organise the day-to-day development and operational commands for the Commander4j suite in a single, structured interface. Menu items can run shell scripts, open applications, pass parameters, capture output, and link to other menu tree files.

== Running Menu4j ==

Menu4j is a Java 21 desktop (Swing) application:

java -jar JMenu.jar

On first launch, if no configuration file is found, Menu4j copies a template configuration from <code>xml/config/init/config.xml</code> and a template menu tree from <code>xml/tree/init/tree.xml</code>.

If a startup password has been configured, you are prompted to enter it before the menu is shown. Three failed attempts close the application.

== The Menu Tree ==

The main window displays a JTree. There are two node types:

{| class="wikitable"
|-
! Type !! Purpose
|-
| Branch || A folder that contains other branches or leaves
|-
| Leaf || An executable item — a command, script, or application
|}

Double-click a leaf to execute it. Double-click a branch to expand or collapse it.

=== Adding and Editing Items ===

The right sidebar toolbar provides:

* '''Add''' — insert a new branch or leaf under the selected node
* '''Edit''' — open the editor for the selected node
* '''Delete''' — remove the selected node
* '''Duplicate''' — copy the selected node

=== Leaf Properties ===

When editing a leaf node, the following properties are available:

{| class="wikitable"
|-
! Property !! Description
|-
| Description || The label shown in the menu tree
|-
| Directory || The working directory for the command
|-
| Command || The executable or system command to run
|-
| Parameters || A list of arguments to pass to the command
|-
| Shell Script Required || Whether to wrap the command in the configured shell wrapper script
|-
| Terminal Window Required || Whether to open a terminal output window to show command output
|-
| Confirm Execute || Whether to show a confirmation prompt before running
|-
| Link to Menu Tree || Whether this item opens a different tree file instead of running a command
|-
| Hint || A tooltip shown when hovering over the item
|-
| Icon || An image file to display next to the item label
|}

== Executing Commands ==

When a leaf is executed:

# Menu4j validates that the directory and command exist
# If '''Shell Script Required''' is set, the command is wrapped using the script configured in Settings (typically a shell wrapper that sources the user's environment)
# If '''Terminal Window Required''' is set, a terminal output window opens and displays stdout and stderr in real time; otherwise the command runs silently in the background
# Environment variables configured in Settings are injected before execution

=== Terminal Output Window ===

The terminal window displays command output with configurable foreground and background colours and font (configured in Settings). A '''Respond''' button allows text to be sent to the command's standard input for interactive commands. When the command completes, the return code is displayed.

== Multiple Tree Files ==

A leaf node can be configured to switch to a different menu tree rather than execute a command. Set '''Link to Menu Tree''' and specify the filename. Double-clicking the leaf saves the current tree's expansion state and loads the linked tree. The application title bar updates to show the active tree filename.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>. This file stores global settings including the active tree filename, shell script settings, colours, fonts, environment variables, system command whitelist, and the encrypted startup password.

=== tree.xml ===

Located at <code>xml/tree/tree.xml</code> (or a different filename if you have switched trees). This is the menu structure file. It is written automatically when you save from the application.

=== tree.xml.state ===

Located alongside the tree file. Records which branches were expanded on the last exit and restores them on next launch.

== Settings ==

Open Settings from the toolbar to configure:

{| class="wikitable"
|-
! Setting !! Description
|-
| Password || Optional startup password (stored AES-encrypted)
|-
| Shell script || Enable/disable the shell wrapper and set the script filename
|-
| Terminal colours || Foreground and background colours for the terminal output window
|-
| Tree colours || Foreground colours for leaf and branch labels
|-
| Fonts || Font choice and size for the terminal window, leaf labels, and branch labels
|-
| Environment variables || Key/value pairs injected into every executed process
|-
| System commands || Whitelist of system commands (such as <code>open</code>) that do not require a file path to be validated
|}

== Tree Navigation ==

The top toolbar provides four buttons for expanding and collapsing the tree:

* Expand All
* Expand Selected Branch
* Collapse Selected Branch
* Collapse All

== Saving ==

Changes to the tree structure are saved using the '''Save''' button in the sidebar toolbar. You are prompted to save if you close the application with unsaved changes.

See also: [[LaunchPad]], [[Downloads]]

[[Category:Commander4j]]

LaunchPad

2026-04-01T11:29:47Z

Dgarratt: Updated by push_wiki.py

LaunchPad is a macOS application organiser and launcher. It provides a tabbed grid interface for grouping macOS applications (.app bundles) into named categories and launching them with a double-click. It is a companion tool to the Commander4j suite, used to organise the suite's tools and supporting applications in a single place.

== Purpose ==

LaunchPad replaces cluttered Dock folders and aliases with a structured, tabbed grid. Each tab is a named category and each cell in the grid holds one application. Applications are added by browsing or dragging from Finder.

== Running LaunchPad ==

LaunchPad is a Java 21 desktop (Swing) application for macOS:

java -jar JLaunchPad.jar

The window opens at 1300 × 900 pixels. Tabs are listed on the left edge; the grid fills the rest of the window.

== Adding Applications ==

=== Single Application ===

Click the '''Add App''' toolbar button. A file chooser opens, defaulting to <code>/Applications</code> and your home directory. Select any <code>.app</code> bundle. If you select <code>/Applications</code>, LaunchPad also scans <code>/System/Applications</code> and <code>/System/Applications/Utilities</code> automatically.

=== Importing a Folder ===

Click '''Import Folder''' to scan a directory recursively for application bundles. LaunchPad filters out uninstall helpers, login item helpers, and background-only bundles, adding only user-facing applications.

=== Drag and Drop ===

Drag a <code>.app</code> bundle from Finder directly onto the grid or onto a tab. An application can only appear once across all tabs — dragging a duplicate has no effect.

== Grid Layout ==

Each tab contains a 7-column grid of 150 × 150 pixel cells. Each cell displays the application icon (120 × 120 pixels) and the application's display name. Click '''Pack Icons''' to remove empty cells from the current tab, compacting the grid.

Applications can be reordered within the grid by dragging from one cell to another. The same drag operation works between tabs.

== Tab Management ==

The toolbar provides buttons for:

* '''Add Tab''' — create a new named category
* '''Edit Tab''' — rename the selected tab
* '''Delete Tab''' — remove the selected tab (with confirmation)
* '''Move Up / Move Down''' — reorder tabs

== Launching Applications ==

Double-click any application icon to launch it. LaunchPad uses the macOS <code>open</code> command to launch the bundle, so the application opens exactly as if you had double-clicked it in Finder.

== Cell Context Menu ==

Right-click any cell or application to access:

* '''Assign Custom Icon...''' — replace the icon with any PNG, JPG, GIF, or ICNS image
* '''Remove App''' — clear the cell
* '''Reveal in Finder''' — open the application's location in Finder

== Icon Resolution ==

When an application is added, LaunchPad attempts to extract its icon automatically. It tries the following in order:

# The <code>.icns</code> file named in the app's <code>Info.plist</code>
# PNG icons listed in <code>Info.plist</code> under <code>CFBundleIcons</code>
# The app's <code>Assets.car</code> (rendered via QuickLook)
# A generic system icon as a last resort

Extracted icons are scaled to 120 × 120 pixels and cached to <code>images/appIcons/</code> on disk. On subsequent launches the cached PNG is used unless the app itself has been updated.

== Configuration ==

LaunchPad saves its state automatically on exit and restores it on the next launch.

=== launchpad.xml ===

Located at <code>xml/config/launchpad.xml</code>. This file records all tabs, their names, and the path of each application in the grid. It is written automatically — you do not need to edit it manually.

=== images/appIcons/ ===

The icon cache directory. Each application has a <code><BundleName>.png</code> file here. If you use '''Assign Custom Icon...''', the cache file for that application is overwritten with your chosen image.

See also: [[Menu4j]], [[ZPLRenderer]], [[Downloads]]

[[Category:Commander4j]]

SocketTest

2026-04-01T11:29:46Z

Dgarratt: Updated by push_wiki.py

SocketTest is a TCP/IP network testing utility with a graphical interface. It acts as both a TCP client and a TCP server, allowing you to send and receive arbitrary data over a socket connection, debug protocol implementations, and simulate network endpoints. It is a companion tool to LabelServer4j, AutoLab4j, and ZPL Renderer, which all communicate with devices over raw TCP/IP sockets.

== Purpose ==

SocketTest is useful when:

* Testing whether a printer or other device is accepting connections on a given IP address and port
* Checking what a device responds with when given a specific command
* Sending raw ZPL or Logopak commands to a printer to verify a script without running the full service
* Acting as a test server to capture what LabelServer4j or AutoLab4j is actually transmitting

== Running SocketTest ==

SocketTest is a Java 21 desktop (Swing) application:

java -jar SocketTest.jar

The main window contains two tabs: '''Client''' and '''Server'''. Both tabs can be used independently or together in proxy mode.

== Client Tab ==

The client tab connects to a remote TCP server.

=== Connecting ===

Enter the IP address and port of the remote server and click '''Connect'''. The IP address dropdown is pre-populated with the network interfaces found on the local machine. The default port is '''9100''' (the standard raw Zebra print port).

=== Sending Data ===

Type or load the message you want to send in the left-hand text area. Use the prefix and suffix dropdowns to select control character sequences that will be prepended or appended to the message:

{| class="wikitable"
|-
! Token !! Character
|-
| (none) || No delimiter
|-
| <code><CR></code> || Carriage return (0x0D)
|-
| <code><LF></code> || Line feed (0x0A)
|-
| <code><CR><LF></code> || Carriage return + line feed
|-
| <code><STX></code> || Start of text (0x02)
|-
| <code><ETX></code> || End of text (0x03)
|-
| <code><ESC></code> || Escape (0x1B)
|-
| <code><ACK></code> || Acknowledge (0x06)
|-
| <code><NAK></code> || Negative acknowledge (0x15)
|}

Click '''Send''' to transmit. The right-hand log pane shows all data sent and received, colour-coded in green on a black background.

=== Loading and Saving Messages ===

Use '''Load''' to populate the input area from a text file, and '''Save''' to persist the input area contents. Use '''Clear''' and '''Save''' on the log pane to manage the communication history.

== Server Tab ==

The server tab listens for incoming TCP connections.

=== Starting the Server ===

Enter the bind IP address (or <code>0.0.0.0</code> to listen on all interfaces) and the port, then click '''Open'''. When a client connects, its hostname and IP address are shown in the panel border. The '''Disconnect''' button closes the current client connection without stopping the server.

=== Sending Responses ===

Once a client is connected you can type a response in the input area and click '''Send''' to transmit it back to the client. All data received from the client is shown in the log pane, colour-coded in white on a black background.

== Proxy Mode ==

The '''Proxy''' button on the server tab enables transparent data relay. When proxy mode is active, data received on the server side is automatically forwarded to whatever the client tab is connected to, and vice versa. This allows SocketTest to sit between a client and a real device and relay all traffic in both directions, which is useful for capturing a complete protocol conversation.

== Control Characters ==

Control characters are entered in human-readable token notation (<code><STX></code>, <code><CR></code>, etc.) in the input area and converted to the actual byte values before transmission. Incoming bytes are decoded back to token notation in the log. SocketTest supports the full standard ASCII control character set (NUL through DEL).

== Configuration ==

SocketTest has no persistent configuration file. IP addresses, ports, and message formatting options are per-session only and reset when the application is closed.

== Log Files ==

SocketTest does not write a log file. All communication history is displayed in the on-screen log panes and can optionally be saved to a text file using the Save button on each pane.

See also: [[LabelServer4j]], [[ZPLRenderer]], [[Production Lines & Labellers]]

[[Category:Commander4j]]

XML Viewer

2026-04-01T11:29:26Z

Dgarratt: Updated by push_wiki.py

XML Viewer is a desktop application for exploring XML documents as an interactive, expandable tree. It supports configurable display modes, multi-language element name translation, and adjustable tree expansion depth. It is designed for viewing structured XML files such as SAP IDoc messages, Commander4j configuration files, and production schedule exports.

== Purpose ==

XML Viewer makes it practical to inspect complex XML files that are difficult to read as raw text. Element names can be translated into plain-language descriptions (for example, the SAP field code <code>ABWKZ</code> becomes "Deviation indicator" in the English translation), and the tree can be expanded to a specific depth to give a high-level overview without showing every leaf value.

== Running XML Viewer ==

XML Viewer is a Java 21 desktop (Swing) application:

java -jar xmlviewer.jar [optional path to XML file]

If a file path is provided on the command line, that file is opened immediately on launch. Otherwise, the last-opened file from the configuration is loaded.

== Loading a Document ==

Click the '''Open XML Document''' button in the right sidebar, or pass a file path on the command line. Only well-formed XML files are supported. Click '''Reload XML Document''' to re-read the current file after it has been changed externally.

== Display Modes ==

=== Standard Mode ===

The XML hierarchy is displayed exactly as it appears in the file — elements nest within their parent elements, forming a tree that mirrors the XML structure.

=== Flat Mode ===

Leaf elements (those containing only text, no child elements) are collapsed into their parent's row rather than appearing as separate tree nodes. Only elements that contain child elements appear as tree nodes. This produces a more compact view of documents with many small leaf values.

Toggle between modes using the '''View Mode''' button in the right sidebar.

== Tree Expansion Control ==

The top toolbar provides four buttons:

* '''Expand All''' — expand every node in the tree
* '''Expand Selected''' — expand only the selected subtree
* '''Collapse Selected''' — collapse the selected subtree
* '''Collapse All''' — collapse everything to root level

The '''−''' and '''+''' buttons in the toolbar adjust the current expansion level (shown as a number between the buttons). Clicking '''Refresh''' after changing the level re-expands the tree to that depth.

The expansion level is saved in the configuration and restored on next launch.

== Translation ==

XML Viewer can replace technical XML element names and values with plain-language descriptions from a translation file.

=== Enabling Translation ===

Toggle translations using the '''View Translations''' button. The '''Translation''' dropdown at the bottom of the window selects which translation file to use. The '''Language''' dropdown selects the language within that file.

=== Built-in Translation Files ===

{| class="wikitable"
|-
! File !! Contents
|-
| matmas05.xml || SAP MATMAS05 IDoc field translations
|-
| zmatmas03.xml || SAP ZMATMAS03 IDoc field translations
|-
| productionschedule.xml || Production schedule export field translations
|-
| config.xml || Commander4j configuration element translations
|-
| default.xml || Generic fallback translations
|}

=== Languages ===

The default installation includes English, French, German, and Italian. The active language can be changed at any time from the Language dropdown.

=== Adding Translations ===

Translation files are XML documents located in <code>xml/translations/</code>. Each file maps element names, attribute names, element values, and attribute values to their translated equivalents for each language. Elements without a translation entry are shown using their original name from the XML file.

== Other Display Options ==

{| class="wikitable"
|-
! Button !! Effect
|-
| View Icons || Show or hide the icon column next to each tree node
|-
| View Brackets || Wrap element values in <code>[ ]</code> brackets to distinguish them from element names
|}

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>. Stores the last-opened file path, selected translation file, selected language, current expansion level, and the state of all four display toggles (mode, translations, brackets, icons). Updated automatically on exit.

=== log4j2.xml ===

Located at <code>xml/log/log4j2.xml</code>. Controls logging to <code>logs/XML_View.log</code>. Log files rotate at 10 MB and are retained for 14 days.

=== fonts.xml / icons ===

Icons are loaded from <code>images/xmlIcons/</code>. If an icon file referenced by a translation is not found, the icon column is left blank for that element without an error.

See also: [[TreeDoc]], [[Middleware4j]], [[Label Template Syntax]]

[[Category:Commander4j]]

SFTPTransfer

2026-04-01T10:31:55Z

Dgarratt: Updated by push_wiki.py

SFTPTransfer is a background file transfer service that moves files between a local filesystem and a remote SFTP server. It is a standalone Java application that runs either as a headless background service or as a desktop application with a minimal GUI, and supports both uploading (PUT) and downloading (GET) in independent threads.

SFTPTransfer replaces the earlier sftpSend and sftpGet tools with a unified, configurable service.

== Purpose ==

SFTPTransfer automates recurring file transfers between Commander4j and external systems — for example, uploading despatch notifications to a customer portal or downloading order files from a supplier. It runs continuously, polling for new files at a configurable interval, and handles authentication, retry, backup, and archiving without operator involvement.

== Startup Modes ==

SFTPTransfer supports two startup modes selected at launch time:

{| class="wikitable"
|-
! Mode !! Behaviour
|-
| '''Start desktop''' || Opens a small GUI window. Transfer threads start in a paused state; the operator must click Start in the interface to begin polling. Useful for testing configuration.
|-
| '''Start service''' || Headless — no GUI window. Transfer threads start immediately on launch. Suitable for production deployment as a background service or scheduled task.
|}

On Windows the service mode can be managed using a wrapper such as WinSW. On Linux/macOS, use systemd, launchd, or nohup.

== Configuration Files ==

All configuration is held in XML files under the <code>xml/config/</code> directory. Changes require a service restart unless hot-reload is triggered (see below).

=== sftp_common.xml ===

Shared settings used by all transfer threads:

{| class="wikitable"
|-
! Setting !! Description
|-
| Poll interval || How often (in seconds) each thread checks for new files. Default: 10 seconds.
|-
| Backup retention || Number of days to keep backed-up files before automatic deletion.
|-
| Log level || Logging verbosity passed to Log4j.
|}

=== sftp_put.xml ===

Configures one or more PUT (upload) profiles. Each profile defines:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether this profile's thread is active.
|-
| Local path || Local directory to watch for outbound files.
|-
| File mask || Wildcard pattern to match files (e.g. <code>*.xml</code>, <code>order_*.csv</code>). Uses Apache Commons IO WildcardFileFilter.
|-
| Remote host || SFTP server hostname or IP address.
|-
| Remote port || SFTP port (default: 22).
|-
| Remote path || Target directory on the remote server.
|-
| Username || SFTP login username.
|-
| Password || AES-encrypted password (see [[#Password Encryption|Password Encryption]]).
|-
| Private key path || Path to SSH private key file (alternative to password authentication).
|-
| Backup path || Local directory where successfully uploaded files are moved.
|-
| Error path || Local directory where files that failed to upload are moved.
|}

=== sftp_get.xml ===

Configures one or more GET (download) profiles. Each profile defines:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether this profile's thread is active.
|-
| Remote host || SFTP server hostname or IP address.
|-
| Remote port || SFTP port (default: 22).
|-
| Remote path || Directory on the remote server to poll for incoming files.
|-
| File mask || Wildcard pattern matched against the remote file listing (server-side ls).
|-
| Local path || Local directory where downloaded files are saved.
|-
| Username || SFTP login username.
|-
| Password || AES-encrypted password.
|-
| Private key path || Path to SSH private key file.
|-
| Delete after download || Whether to delete the remote file after successful download.
|-
| Backup path || Local directory where a copy of each downloaded file is kept.
|}

=== jsch_properties.xml ===

Advanced SSH session parameters passed directly to the JSch library. Used to control host key checking, preferred algorithms, and connection timeouts. In most deployments this file can be left at its defaults.

=== email_properties.xml ===

SMTP settings for error notification emails. When a transfer failure occurs and email notification is enabled, SFTPTransfer sends an alert to the configured address. Fields include SMTP host, port, sender address, recipient address, and AES-encrypted SMTP password.

== Authentication ==

SFTPTransfer supports two authentication methods, configured per profile:

{| class="wikitable"
|-
! Method !! How to configure
|-
| Password || Set the <code>Password</code> field in the profile to an AES-encrypted value. Leave the private key path empty.
|-
| SSH private key || Set the <code>Private key path</code> field to the path of a PEM-format private key file. The password field is ignored.
|}

Both methods use the JSch 2.x SSH library with Bouncy Castle as the cryptographic provider.

=== Password Encryption ===

Passwords stored in configuration files are AES-encrypted. Plain-text passwords are never stored on disk. To encrypt a password, use the password utility included with Commander4j (the same utility used for database passwords in Commander4j's own configuration).

== File Transfer Behaviour ==

=== PUT (Upload) ===

# SFTPTransfer polls the local input directory every 10 seconds (configurable).
# Files matching the file mask are selected for upload.
# Each file is uploaded to the remote path using a temporary name with a <code>.tmp</code> extension.
# On successful transfer, the remote file is renamed to its final name (atomic rename — the remote system never sees a partial file).
# The local source file is moved to the backup directory.
# If the transfer fails, the file is moved to the error directory and an error is logged.

=== GET (Download) ===

# SFTPTransfer lists the remote directory every 10 seconds (configurable).
# Files matching the file mask are selected for download.
# Each file is downloaded to the local path using a <code>.tmp</code> extension.
# On successful download, the local file is renamed to its final name.
# If configured, the remote file is deleted after download.
# A backup copy is optionally saved to the local backup directory.

== Thread Architecture ==

When running, SFTPTransfer maintains the following threads:

{| class="wikitable"
|-
! Thread !! Purpose
|-
| TransferPUT || One thread per enabled PUT profile, each managing its own SFTP connection.
|-
| TransferGET || One thread per enabled GET profile, each managing its own SFTP connection.
|-
| EmailThread || Sends error notification emails asynchronously.
|-
| ArchiveThread || Periodically purges backup files older than the configured retention period.
|}

== Hot Configuration Reload ==

SFTPTransfer supports a configuration reload mode (<code>Mode_CONFIG_UPDATE</code>). When this mode is triggered, running threads re-read their configuration files without requiring a full service restart. This allows profile changes — such as updating a remote path or rotating credentials — to be applied with minimal disruption.

== Logging ==

All activity is written to the Log4j log file. The log records:

* Service startup and configuration loaded
* Each thread starting and its profile settings
* Every file detected, transfer attempted, and outcome
* Every remote connection attempt and disconnect
* File move operations (to backup or error directories)
* Errors and exceptions with full context

Log rotation and retention are configured in the Log4j configuration file included in the distribution.

== Dependencies ==

{| class="wikitable"
|-
! Library !! Version !! Purpose
|-
| JSch || 2.27.9 || SSH/SFTP client
|-
| Bouncy Castle || current || Cryptographic provider for JSch
|-
| Apache Commons IO || current || WildcardFileFilter for local file matching
|-
| Log4j || 2.25.3 || Logging
|}

See also: [[LabelServer4j]], [[Middleware4j]], [[Production Lines & Labellers]]

[[Category:Commander4j]]

LabelServer4j

2026-04-01T10:26:19Z

Dgarratt: Updated by push_wiki.py

'''LabelServer4j''' is a background label printing service that bridges Commander4j and physical label printer devices on a production line. When an operator assigns a [[Process Orders|Process Order]] to a production line, Commander4j exports a data file which LabelServer4j picks up, processes through a configurable script, and uses to drive the printer over TCP/IP.

LabelServer4j supports Zebra ZPL printers, Logopak labellers, and any device that accepts raw TCP/IP text commands. It runs as a headless background service with no graphical interface, and can manage multiple printers simultaneously in independent threads.

== Getting Started ==

{| class="wikitable" style="width:100%"
|-
| [[Overview LabelServer4j]] || What LabelServer4j does and how it differs from AutoLab4j
|-
| [[Downloads]] || Download the latest release
|-
| [[LabelServer4j Configuration]] || Configuring sites, labellers, and database connections
|-
| [[LabelServer4j Folder Structure]] || Directory layout and purpose of each folder
|}

== User Guide ==

{| class="wikitable" style="width:100%"
|-
| [[LabelServer4j Operation]] || End-to-end workflow from order assignment to label printed
|-
| [[LabelServer4j Dataset CSV]] || Fields available in the CSV data file from Commander4j
|-
| [[LabelServer4j Example User Interface]] || Deployment, startup, monitoring, and log file reference
|}

== Related Pages ==

{| class="wikitable" style="width:100%"
|-
| [[Production Lines & Labellers]] || Configuring production lines in Commander4j
|-
| [[Process Order Assign to Labeller]] || Assigning orders to labellers from Commander4j
|-
| [[Zebra ZPL Label]] || ZPL label template syntax reference
|-
| [[Label Template Syntax]] || Commander4j label template language
|-
| [[ZPLRenderer]] || Tool for previewing ZPL labels before printing
|}

[[Category:LabelServer4j]]

LabelServer4j Example User Interface

2026-04-01T10:26:18Z

Dgarratt: Updated by push_wiki.py

LabelServer4j is a headless background service — it has no graphical user interface. All interaction with the service is through configuration files, log files, and (on Windows) the Windows Services control panel.

== Starting LabelServer4j ==

=== Windows ===

LabelServer4j can be installed as a Windows service so that it starts automatically when the server boots and restarts automatically if it crashes. Once installed as a service it is managed through the standard Windows Services management console (<code>services.msc</code>) or the command line:

net start LabelServer4j
net stop LabelServer4j

It can also be started directly from a command prompt for testing:

start_labeller.cmd

=== Linux / macOS ===

Start from the terminal using the provided shell script:

./start_labeller.sh

Or directly:

java -cp ./LabelServer.jar:./lib/devonly/i4jruntime.jar com.commander4j.labeller.Service

The process runs in the foreground. Use a process manager (systemd, launchd, or nohup) for production deployment.

== Monitoring ==

Since there is no GUI, the primary monitoring tool is the log file:

logs/c4jLabelServer.log

The log records every event in detail:

* Service startup and configuration loading
* Each labeller thread starting
* Every CSV file detected and processed
* Every command sent to a printer and every response received
* File operations (upload, download, backup, delete)
* Errors and exceptions with full context

Log files rotate at 10 MB and are retained for 14 days.

=== What to Look For ===

{| class="wikitable"
|-
! Situation !! What to check in the log
|-
| Label not printing || Look for the CSV filename being detected; if absent, check the input path in labellers.xml
|-
| Printer not responding || Look for TCP connection errors or timeout messages for that labeller's IP and port
|-
| Wrong data on label || Check the variable substitution log lines to see what values were sent
|-
| Script error || Look for the script line number and command that caused the failure
|-
| File stuck in input directory || File renamed to <code>.in</code> means the script is running or failed — check for a <code>.error</code> file
|}

== Configuration Changes ==

To change a labeller's IP address, port, command script, or input path, edit the relevant <code>labellers.xml</code> file and restart the service. Changes to configuration files are not picked up at runtime.

To switch site, edit <code>xml/config/config.xml</code> and change the <code>site id</code> attribute, then restart.

== Thread Architecture ==

When running, LabelServer4j maintains the following threads:

* One main service thread (lifecycle management)
* One server thread (configuration and orchestration)
* Per enabled labeller: one labeller thread, one TCP receive thread, one TCP transmit thread

The thread count grows with the number of configured printers. A site with six printers typically runs around 20 threads in total.

== Graceful Shutdown ==

Sending a termination signal (Ctrl+C on Linux/macOS, or stopping the Windows service) triggers the shutdown hook. LabelServer4j signals all labeller threads to stop, waits for any in-progress print jobs to complete, then exits cleanly.

See also: [[Overview LabelServer4j]], [[LabelServer4j Configuration]], [[LabelServer4j Operation]], [[Install Interface Services]]

[[Category:LabelServer4j]]

LabelServer4j Operation

2026-04-01T10:26:16Z

Dgarratt: Updated by push_wiki.py

This page describes the end-to-end operational workflow of LabelServer4j — from an operator assigning a process order in Commander4j through to a label being printed on the production line.

== Step 1 — Assign a Process Order to a Labeller ==

In the Commander4j desktop application, an operator opens the Pallet Labelling screen (or uses the [[Process_Order_Assign_to_Labeller|Process Order Assign to Labeller]] function) and assigns a [[Process Orders|Process Order]] to a configured production line.

Commander4j validates:
* That the operator's workstation is permitted to assign to that line (if workstation validation is enabled)
* That the order's Required Resource matches the line (if resource validation is enabled)

== Step 2 — CSV Export ==

Commander4j writes a CSV data file to the labeller's input directory. The filename follows the format <code>LINE_NAME_PRINTER_NAME.CSV</code>. The file contains a header row and a single data row with all the fields needed to produce the label. See [[LabelServer4j Dataset CSV]] for the full list of fields.

== Step 3 — File Detection ==

LabelServer4j polls the input directory every 250 ms. When the CSV file appears:

# The file is immediately renamed to <code>.in</code> to prevent it being picked up twice.
# The file is parsed using the column headers to map each value to a named variable (e.g. <code>$data_BATCH_SUFFIX</code>, <code>$data_SSCC</code>).

== Step 4 — Script Execution ==

LabelServer4j loads the command script configured for this labeller (a plain text <code>.txt</code> file from the <code>labeller_cmd/</code> directory). The script is executed line by line. Each line consists of a label (for flow control) and a command with its arguments.

During execution, data variables from the CSV are substituted into the commands. Functions such as <code>SUBSTRING()</code>, <code>PADLEFT()</code>, <code>EXTRACT_DATE()</code>, and <code>CODE128SWITCHER()</code> can be used to format values before transmission.

=== Control Flow ===

Scripts support conditional branching and looping:

* <code>GOTO label</code> — unconditional jump
* <code>IF (condition) GOTO label</code> — conditional jump
* Labels can be used to structure sections for different label types within a single script

This allows one script to handle multiple label variants based on a field value in the CSV (for example, switching between a production layout and a rework layout based on <code>$data_MODULE_ID</code>).

=== Database Queries ===

The <code>DB_QUERY</code> command executes a parameterised SQL statement against the Commander4j database and stores the result in a variable. This enriches label data beyond what Commander4j included in the CSV.

=== Sending to the Printer ===

The <code>SEND</code> command transmits a line of text to the printer over the TCP/IP connection. Control characters such as <code><CR></code>, <code><LF></code>, <code><STX></code>, and <code><ETX></code> are encoded in the script and expanded at send time.

<code>WAIT_FOR_REPLY</code> blocks execution until a response is received. <code>CHECK_SUCCESS</code> compares the response against configured success and failure patterns.

=== File Operations ===

For Logopak and similar printers that use stored label templates, LabelServer4j can upload (<code>SEND_FILE_INTELHEX</code>) and download (<code>RECEIVE_FILE_INTELHEX</code>) binary files to and from the printer using Intel Hex encoding. It can also list remote files, delete them, and back them up locally.

== Step 5 — Completion ==

On successful completion of the script, the input CSV file is deleted and a record written to the log. The labeller thread immediately returns to polling for the next file.

If the script fails (invalid response, connection error, or script error), the CSV file is moved to an error directory and an error message is logged. If email notifications are configured, an alert is sent.

== Logging ==

All activity is written to <code>logs/c4jLabelServer.log</code> with rolling rotation (10 MB per file, 14 days retention). The log records every command sent, every response received, and all file operations. This makes diagnosing communication issues straightforward.

== Running Multiple Labellers ==

Each configured labeller runs in its own background thread. All labellers poll and execute simultaneously. A site with six printers runs six independent threads, each managing its own TCP connection and input directory.

See also: [[Overview LabelServer4j]], [[LabelServer4j Configuration]], [[LabelServer4j Dataset CSV]], [[LabelServer4j Folder Structure]], [[Production Lines & Labellers]]

[[Category:LabelServer4j]]

Overview LabelServer4j

2026-04-01T10:26:15Z

Dgarratt: Updated by push_wiki.py

LabelServer4j is a background label printing service that acts as a bridge between Commander4j and physical label printer devices on a production line. It monitors for incoming label requests, processes them through configurable scripts, and communicates with printers over TCP/IP.

== Purpose ==

When an operator assigns a [[Process Orders|Process Order]] to a production line in Commander4j, the system exports a CSV data file containing all the fields needed to print the label — product code, description, batch number, SSCC, expiry date, and so on. LabelServer4j detects this file, reads the data, executes a printer command script, and sends the appropriate commands to the labeller over the network.

This separation means label printing is handled by a dedicated background service rather than by the Commander4j desktop application itself, allowing printers to be driven remotely without any operator interaction beyond assigning the order.

== Difference from AutoLab4j ==

LabelServer4j and AutoLab4j serve related but distinct purposes:

{| class="wikitable"
|-
! Feature !! LabelServer4j !! AutoLab4j
|-
| Typical use || Case labellers, secondary labellers || Pallet labellers
|-
| SSCC generation || No — SSCC is supplied in the CSV || Yes — generates unique SSCCs via Modbus signals from the line
|-
| User interface || None — background service only || Graphical window with printer status displays
|-
| Label trigger || CSV file from Commander4j || Modbus signal from production line equipment
|}

== How It Works ==

# Commander4j writes a CSV file to the configured output directory when an order is assigned to a line.
# LabelServer4j polls that directory every 250 ms.
# When a CSV file is detected, it is locked (renamed to <code>.in</code>), parsed, and its fields loaded as variables.
# A command script (a plain text file) is executed line by line. The script sends ZPL or proprietary printer commands to the labeller, substituting data fields from the CSV.
# The printer responds; LabelServer4j validates the response.
# On success, the CSV file is deleted. On failure, it is moved to an error directory.

== Supported Printer Types ==

LabelServer4j communicates with printers over raw TCP/IP sockets and supports two label command formats:

* '''ZPL (Zebra Programming Language)''' — for Zebra and Videojet printers. Full ZPL commands with GS1 Code 128 barcode support via the built-in <code>CODE128SWITCHER()</code> function.
* '''Logopak format''' — a proprietary command structure using lock/load/field data/end sequences, with binary file transfer using Intel Hex encoding for uploading label templates to the printer.

Any printer that accepts raw TCP/IP text commands on a configurable port can be driven by LabelServer4j, provided an appropriate command script is written.

== Multi-Site and Multi-Printer ==

LabelServer4j supports multiple sites (each with its own <code>labellers.xml</code>) and runs each configured printer in an independent background thread. Multiple printers operate simultaneously without interfering with one another.

== Database Integration ==

LabelServer4j can connect directly to the Commander4j database to perform SQL queries during script execution. This allows label content to be dynamically enriched with data that is not included in the CSV file — for example, querying the current status of an order or looking up a reference value.

See also: [[LabelServer4j Configuration]], [[LabelServer4j Operation]], [[LabelServer4j Dataset CSV]], [[Production Lines & Labellers]]

[[Category:LabelServer4j]]

ZPLRenderer

2026-04-01T10:22:02Z

Dgarratt: Updated by push_wiki.py

ZPL Renderer is a desktop application that interprets ZPL (Zebra Programming Language) commands and renders them as a visual preview of what a label will look like when printed on a physical Zebra printer. It is a companion tool to Commander4j, LabelServer4j, and AutoLab4j.

== Purpose ==

ZPL is a text-based command language used to define label layouts, text, graphics, and barcodes for Zebra label printers. The commands are sent directly to the printer as a stream of characters and are not human-readable. ZPL Renderer allows you to:

* Load a ZPL file and see what the label will look like before sending it to a printer
* Listen on a network socket so that any application sending ZPL to that port renders the label on screen in real time
* Zoom in and out to examine label detail
* Preview multiple labels from a single ZPL stream
* Export the rendered label to PDF
* Print the rendered label directly from the application

== Running ZPL Renderer ==

ZPL Renderer is a Java 21 desktop (Swing) application:

java -jar zplrenderer.jar

On first launch it reads its configuration from <code>xml/config/config.xml</code>.

== Loading a ZPL File ==

Use the '''Open''' toolbar button to load a <code>.zpl</code> text file from disk. The label is rendered immediately. Use '''Refresh''' to reload the file after editing it externally.

Several example ZPL files are included in the <code>examples/</code> directory:

{| class="wikitable"
|-
! File !! Contents
|-
| example1.zpl || Shipping label with QR code, text, and graphics
|-
| example2.zpl || Complex layout with boxes, barcodes, and logo
|-
| barcodes.zpl || Showcase of all supported barcode types
|-
| pallet_labels.zpl || Pallet label examples typical of Commander4j output
|-
| fonts.zpl || Font size and style demonstration
|-
| shipping.zpl || Shipping label sample
|-
| character.zpl || Character set reference
|-
| grid.zpl || Layout grid for alignment reference
|}

== Network Socket Mode ==

ZPL Renderer can listen on a TCP/IP port and render any ZPL label stream sent to it. This allows Commander4j, LabelServer4j, or any other application to use ZPL Renderer as a virtual printer — sending ZPL to the socket and seeing the result on screen instead of printing to paper.

The default port is '''9100''' (the standard Zebra raw print port). The IP address and port are configured in <code>config.xml</code>. Enable listening using the '''Network''' button in the toolbar.

ZPL Renderer extracts complete label blocks from the stream, identified by the standard <code>^XA</code> (start of label) and <code>^XZ</code> (end of label) delimiters.

== Zoom ==

Use the zoom controls in the toolbar to scale the rendered label between 0.10× and 2.00×. The default zoom is configured in <code>config.xml</code> (default: 0.5×). This is useful for examining barcode detail or checking overall label proportions.

== Multiple Labels ==

When a ZPL file or network stream contains multiple labels, ZPL Renderer displays them as pages. Navigation controls allow stepping through each label. The maximum number of pages displayed is configurable (default: 3).

== Export and Print ==

* '''PDF Export''' — saves the rendered label as a vector PDF using Apache PDFBox
* '''Print''' — sends the rendered label to a system printer

== Supported ZPL Commands ==

ZPL Renderer supports over 100 ZPL commands. Key categories:

=== Label Setup ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^XA || Start of label
|-
| ^XZ || End of label
|-
| ^LL || Label length
|-
| ^LH || Label home (origin offset)
|-
| ^LT || Label top offset
|-
| ^PQ || Print quantity
|-
| ^CD || Change delimiter character
|-
| ^CC || Change caret character
|}

=== Text and Fields ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^FO || Field origin (X,Y position from top-left)
|-
| ^FT || Field typeset (X,Y position from bottom-left)
|-
| ^FD || Field data (the text content)
|-
| ^FS || Field separator
|-
| ^FR || Field reverse (inverted colours)
|-
| ^FW || Field orientation/rotation
|-
| ^FX || Comment (ignored in output)
|}

=== Fonts ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^A0–^AZ || Select font by ID
|-
| ^CF || Change default alphanumeric font
|-
| ^CI || Change international character set/encoding
|}

=== Graphics ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^GB || Graphic box (rectangle)
|-
| ^GC || Graphic circle
|-
| ^GD || Graphic diagonal line
|-
| ^GE || Graphic ellipse
|-
| ^GF || Graphic field (embedded image data)
|-
| ^GS || Graphic symbol
|}

=== Barcodes ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^BC || Code 128 / GS1-128 (EAN-128)
|-
| ^BE || EAN-13
|-
| ^B8 || EAN-8
|-
| ^B3 || Code 39
|-
| ^B2 || Interleaved 2 of 5
|-
| ^B1 || Code 11
|-
| ^BQ || QR Code
|-
| ^B7 || PDF417
|-
| ^B0 / ^BO || Aztec
|-
| ^BY || Bar code field defaults (width, ratio, height)
|}

Barcode rendering uses the OkapiBarcode library. GS1 application identifiers are interpreted from <code>xml/config/gs1_app_defs.xml</code>.

== Configuration ==

=== config.xml ===

Located at <code>xml/config/config.xml</code>:

{| class="wikitable"
|-
! Setting !! Description
|-
| Input folder || Default directory for ZPL file loading (default: <code>./examples</code>)
|-
| Port || Network socket port to listen on (default: 9100)
|-
| Default magnification || Starting zoom level (default: 0.5)
|-
| Max pages || Maximum number of label pages to display (default: 3)
|}

=== fonts.xml ===

Located at <code>xml/config/fonts.xml</code>, this file maps ZPL font IDs (0, A–Z) to TrueType font files and defines their pixel dimensions. This allows ZPL Renderer to simulate the fonts installed in a physical Zebra printer.

Included fonts: Bitstream Vera, Anonymous Pro, ATTriumvirate.

If your labels use fonts that differ from the defaults, edit <code>fonts.xml</code> to match the font metrics of your target printer.

== Relationship to Commander4j ==

Commander4j generates ZPL label streams for pallet and case labels. ZPL Renderer allows you to preview these labels before deploying them to production printers, and to verify that label templates produce the correct output after making changes to the template syntax. See [[Label Template Syntax]] and [[Zebra ZPL Label]] for information on ZPL label authoring within Commander4j.

See also: [[Zebra ZPL Label]], [[Label Template Syntax]], [[Printer Queues]], [[Production Lines & Labellers]]

[[Category:Commander4j]]

Middleware4j

2026-04-01T10:17:26Z

Dgarratt: Updated by push_wiki.py

'''Middleware4j''' is a file-based message transformation and routing engine developed as a companion to [[Commander4j]]. It has no dependencies on Commander4j and can be used independently for any system integration requirement.

Its primary purpose is to link systems that use incompatible data formats. It monitors directories for incoming files, transforms them using configurable XSLT stylesheets, and delivers the results to one or more output destinations in the required format — running continuously in the background as a service.

For a full explanation of how the application works, see [[Overview_Middleware4j]].

== Getting Started ==

{| class="wikitable" style="width:100%"
|-
| [[Overview_Middleware4j]] || What Middleware4j does and how it works
|-
| [[Downloads]] || Download the latest release
|-
| [[Installation_Middleware4j]] || How to install and deploy as a Windows service
|}

== User Guide ==

{| class="wikitable" style="width:100%"
|-
| [[Maps]] || Configuring transformation pipelines (the core concept)
|-
| [[Connectors]] || Available input and output connector types
|-
| [[Middleware4j_Example_Configuration]] || Complete worked configuration example
|-
| [[EMAIL]] || Email connector and SMTP configuration
|}

== Connector Reference ==

{| class="wikitable" style="width:100%"
|-
| [[ASCII]] || Fixed-column flat file input and output
|-
| [[CSV]] || Delimiter-separated file input and output
|-
| [[XML]] || XML document input and output with XSLT transformation
|-
| [[RAW]] || Copy or move files without transformation
|-
| [[EMAIL]] || Send files as email attachments or receive via email
|-
| [[SOCKET]] || Transmit data to devices over TCP/IP
|-
| [[PDF_PRINT]] || Automatically print PDF files to a named printer queue
|}

[[Category:Middleware4j]]

PDF PRINT

2026-04-01T10:17:25Z

Dgarratt: Updated by push_wiki.py

The PDF_PRINT connector monitors a directory for incoming PDF files and automatically sends them to a printer. It provides a simple way to automate printing of reports, labels, or documents that are generated as PDF files by Commander4j or any other application.

== How It Works ==

When a PDF file appears in the monitored input directory, Middleware4j reads it using Apache PDFBox and sends it to the configured print queue. The file is then moved out of the input directory. No transformation is applied — the PDF is printed as-is.

== Input Configuration ==

<syntaxhighlight lang="xml">
<input>
<id>in1</id>
<type>PDF_PRINT</type>
<url>
<path>./interface/input/Map06 PDF to PRINT</path>
<mask/>
<pollingInterval>1000</pollingInterval>
</url>
</input>
</syntaxhighlight>

== Output Configuration ==

<syntaxhighlight lang="xml">
<output>
<id>out1</id>
<type>PDF_PRINT</type>
<url>
<path>./interface/output/Map06 PDF to PRINT</path>
</url>
<queueName>HP8600</queueName>
</output>
</syntaxhighlight>

The '''queueName''' element specifies the name of the printer or print queue to use. This must match the printer name as it appears in the operating system's printer list. If <code>queueName</code> is omitted, the system default printer is used.

== Use Cases ==

* Automatically printing JasperReports output from Commander4j as PDF is delivered to the input folder
* Printing documents generated by external systems without manual intervention
* Centralising print routing — other systems drop PDFs to a network share monitored by Middleware4j, which routes them to the correct printer

== Notes ==

* The printer must be accessible from the machine running Middleware4j. For network printers, ensure the service account running Middleware4j has permission to access the print queue.
* If Middleware4j is running as a Windows service under the System account, network printers may not be accessible. Configure the service to run under a domain account with the necessary permissions. See [[Installation Middleware4j]].
* No XSLT transformation is applied — the PDF is sent to the printer unchanged.

See also: [[Connectors]], [[Maps]], [[Installation Middleware4j]]

[[Category:Middleware4j]]

RAW

2026-04-01T10:17:24Z

Dgarratt: Updated by push_wiki.py

The RAW connector copies or moves files from one location to another without any format conversion, transformation, or interpretation of the file contents. Unlike other [[Connectors|connectors]], it does not convert the file into an internal XML representation — the bytes are passed through unchanged.

== When to Use RAW ==

Use the RAW connector when you need to:

* Transfer files between directories or network shares without modifying them
* Monitor a remote file share and pull files to a local directory for processing by another application
* Replicate files to multiple destinations simultaneously
* Move large or binary files efficiently (no XML overhead)

Because RAW bypasses the XML conversion step, it uses significantly less memory and CPU than other connector types — making it the right choice whenever transformation is not required.

== Input Configuration ==

<syntaxhighlight lang="xml">
<input>
<id>in1</id>
<type>RAW</type>
<url>
<path>./interface/input/Map07 RAW to RAW</path>
<mask/>
<pollingInterval>5000</pollingInterval>
</url>
</input>
</syntaxhighlight>

No XSLT stylesheet can be applied to a RAW input, as the file is not converted to XML.

== Output Configuration ==

<syntaxhighlight lang="xml">
<output>
<id>out1</id>
<type>RAW</type>
<url>
<path>./interface/output/Map07 RAW to RAW</path>
</url>
</output>
</syntaxhighlight>

=== Multiple Output Paths ===

The output path can include multiple destinations separated by semicolons. The file will be written to all specified paths:

<syntaxhighlight lang="xml">
<path>./interface/output/Map07 Path1;./interface/output/Map07 Path2;\\server\share\output</path>
</syntaxhighlight>

== Notes ==

* No XSLT transformation is possible with RAW connectors — the data is not parsed.
* The RAW connector supports UNC network paths (<code>\\server\share\path</code>) as well as local paths, making it suitable for file distribution across a network.
* Polling interval can be set longer than other connector types (e.g. 5000 ms) since RAW operations are lightweight.

See also: [[Connectors]], [[Maps]], [[Overview_Middleware4j]]

[[Category:Middleware4j]]

Connectors

2026-04-01T10:17:23Z

Dgarratt: Updated by push_wiki.py

Connectors are the components within Middleware4j responsible for reading from and writing to specific file formats and protocols. Each [[Maps|Map]] has one input connector and one or more output connectors. The connector type determines how the data is read, written, or transmitted.

== How Connectors Work ==

When a file arrives in an input directory, the input connector reads it and converts the data into an internal XML representation. This XML is then optionally transformed by an XSLT stylesheet before being passed to each output connector. The output connector converts the XML back into the required format and writes it to the destination.

== Available Connectors ==

=== [[ASCII]] ===

Reads or writes fixed-column flat files. The key configuration is the '''pattern''' attribute, which specifies which column ranges to extract from (input) or write to (output). For example, <code>1-10,12-21,23-32</code> extracts three fields from columns 1–10, 12–21, and 23–32.

Use this connector when integrating with legacy systems that produce or consume fixed-width files.

=== [[CSV]] ===

Reads or writes delimiter-separated files using the Apache Commons CSV library. Configurable options include the delimiter character, quote character, and whether to handle 8.3 short filenames for legacy compatibility.

Use this connector for comma- or caret-separated files, spreadsheet exports, and similar tabular data.

=== [[XML]] ===

Reads or writes XML files. Because Middleware4j processes all data internally as XML, this connector requires no intermediate conversion — the file is loaded directly as the working document. XSLT stylesheets transform the structure as required.

Use this connector when the source or destination system uses XML, including Commander4j's own interface message format.

=== IDOC ===

Reads or writes SAP IDOC format files. IDOCs are fixed-format flat files used by SAP for data exchange. Middleware4j includes schema definitions for common IDOC types and converts them to XML for processing.

Use this connector when integrating with SAP systems that produce or consume IDOC files.

=== Excel ===

Reads XLS and XLSX spreadsheet files using Apache POI, or writes data to Excel format. Useful for integrating with systems that exchange data via spreadsheet.

=== [[EMAIL]] ===

Sends files as email attachments via SMTP, or monitors an email inbox for incoming attachments. Email distribution lists and SMTP credentials are configured in the separate <code>email.xml</code> file.

Use this connector to deliver reports or notifications by email, or to receive data files submitted via email.

=== [[RAW]] ===

Copies or moves files without any transformation or format conversion. Unlike other connectors, RAW does not convert the file to an XML representation — it passes the bytes through unchanged. This is significantly more efficient for large files or binary content.

Use this connector when you simply need to move or replicate files between directories or file shares without modifying them.

=== [[PDF_PRINT]] ===

Monitors a directory for PDF files and automatically sends them to a named printer queue. The output connector configuration specifies the queue name.

Use this connector to automate printing of reports, labels, or documents that are generated and dropped as PDF files by another system.

=== [[SOCKET]] ===

Transmits the transformed output to a device or service over a TCP/IP socket connection. The host IP address, port number, and optional repeat count are configured on the output connector. Useful for sending data directly to label printers, weighing systems, or other networked devices.

=== MQTT ===

Publishes the transformed output to an MQTT message broker. The broker address, topic, and quality of service level are configurable. Useful for IoT integration and event-driven architectures.

== Connector Configuration Reference ==

Each connector type has its own set of configuration elements within the map's <code><input></code> or <code><output></code> block in <code>config.xml</code>. See the individual connector pages and [[Middleware4j Example Configuration]] for worked examples.

== Error Handling ==

If a connector fails to process a file (for example, because the format is invalid or the destination is unavailable), the input file is renamed with an <code>.error</code> extension and left in the input directory. An email notification is sent if email notifications are enabled for that map.

See also: [[Maps]], [[Middleware4j Example Configuration]], [[Overview_Middleware4j]]

[[Category:Middleware4j]]

Maps

2026-04-01T10:17:22Z

Dgarratt: Updated by push_wiki.py

A Map is the core configuration unit in Middleware4j. Each map defines a complete message transformation pipeline: where to read data from, how to transform it, and where to send the result. Multiple maps can run simultaneously, each in its own background thread.

== Structure ==

Each map consists of:

* One '''input connector''' — monitors a directory and reads incoming files
* One or more '''output connectors''' — writes the transformed result to one or more destinations
* Optional '''XSLT stylesheets''' on input and/or output for data transformation
* Optional '''conditions''' on each output for content-based routing

== How a Map Processes a File ==

# The input connector polls its configured directory at the set interval (default 1000 ms).
# When a file matching the file mask arrives, it is read and converted to an internal XML document by the input connector.
# If an input XSLT stylesheet is configured, it is applied to transform the XML.
# Each output connector is evaluated in turn:
## If a '''condition''' is configured, the output is only activated when the condition evaluates to true.
## If activated, an optional output XSLT stylesheet is applied.
## The result is written to the output destination by the output connector.
# The original input file is moved to a backup location.
# If any step fails, the file is renamed with an <code>.error</code> extension and an email notification is sent (if email is configured).

== Configuration ==

Maps are defined in the main <code>config.xml</code> file. A minimal map looks like this:

<syntaxhighlight lang="xml">
<map>
<id>Map01</id>
<enabled>true</enabled>
<description>ASCII File to CSV</description>
<enableEmailNotifications>true</enableEmailNotifications>
<connectors>
<input>
<id>in1</id>
<type>ASCII</type>
<url>
<path>./interface/input/Map01</path>
<mask/>
<pollingInterval>1000</pollingInterval>
</url>
<xsl>
<XSLT>Map01_ASCII_to_CSV.xsl</XSLT>
</xsl>
<ascii>
<pattern>1-10,12-21,23-32</pattern>
</ascii>
</input>
<output>
<id>out1</id>
<type>CSV</type>
<url>
<path>./interface/output/Map01</path>
</url>
</output>
</connectors>
</map>
</syntaxhighlight>

== Key Settings ==

=== Map Level ===

{| class="wikitable"
|-
! Setting !! Description
|-
| '''id''' || Unique identifier for this map (e.g. Map01)
|-
| '''enabled''' || true/false — disabled maps are loaded but do not run
|-
| '''description''' || Human-readable description shown in the GUI
|-
| '''enableEmailNotifications''' || Whether to send error emails for this map
|}

=== Input Connector ===

{| class="wikitable"
|-
! Setting !! Description
|-
| '''type''' || The connector type: ASCII, CSV, XML, IDOC, Excel, EMAIL, RAW, PDF_PRINT
|-
| '''path''' || The directory to monitor for incoming files
|-
| '''mask''' || File extension filter (leave empty to process all files)
|-
| '''pollingInterval''' || How often to check the directory, in milliseconds
|-
| '''xsl / XSLT''' || Optional XSLT stylesheet to apply after reading
|}

=== Output Connector ===

{| class="wikitable"
|-
! Setting !! Description
|-
| '''type''' || The connector type: ASCII, CSV, XML, SOCKET, MQTT, EMAIL, Excel, PDF_PRINT, RAW, IDOC
|-
| '''path''' || Output directory (multiple directories separated by semicolons)
|-
| '''xsl / XSLT''' || Optional XSLT stylesheet to apply before writing
|-
| '''use83GUID''' || Use short (8.3) GUID filenames for legacy application compatibility
|-
| '''retainOriginalFilename''' || Keep the original input filename on the output file
|}

== Conditional Routing ==

An output connector can be made conditional using an XPath expression evaluated against the internal XML document. This allows a single map to route different messages to different outputs based on their content.

<syntaxhighlight lang="xml">
<condition>
<param1>/message/messageData/storageBin</param1>
<param1_Type>xquery</param1_Type>
<param2>DESPATCH</param2>
<param2_Type>literal</param2_Type>
<comparitor>EQUAL</comparitor>
</condition>
</syntaxhighlight>

Supported comparitors are <code>EQUAL</code> and <code>NOT EQUAL</code>. Either or both parameters can be XPath expressions (<code>xquery</code>) or fixed values (<code>literal</code>).

== Multiple Outputs ==

A single map can have any number of output connectors. All enabled outputs whose conditions are satisfied receive the transformed message. This allows one incoming file to simultaneously update multiple systems in different formats.

== Global Settings ==

Global settings that apply to all maps are defined at the top of <code>config.xml</code>:

{| class="wikitable"
|-
! Setting !! Description
|-
| '''logPath''' || Directory for transformation log files
|-
| '''XSLTPath''' || Directory where XSLT stylesheets are stored
|-
| '''logArchiveRetentionDays''' || How many days to keep old log files
|-
| '''retryOpenFileCount''' || Number of times to retry reading a locked file
|-
| '''retryOpenFileDelay''' || Delay in milliseconds between retries
|-
| '''enableEmailNotifications''' || Global email notification toggle
|-
| '''statusReportTime''' || Time of day to send the daily status report email
|}

See also: [[Connectors]], [[Middleware4j Example Configuration]], [[Overview_Middleware4j]]

[[Category:Middleware4j]]

Overview Middleware4j

2026-04-01T10:17:21Z

Dgarratt: Updated by push_wiki.py

Middleware4j is a file-based message transformation and routing engine. It was originally developed as a companion component to [[Commander4j]], but has no dependencies on it and can be used as a standalone middleware solution for any system integration requirement.

== Purpose ==

Many manufacturing and logistics sites need to exchange data between systems that use incompatible file formats — for example, sending production output data from Commander4j to an ERP system that expects CSV or fixed-column ASCII files, or receiving process orders from SAP in IDOC format and converting them to Commander4j's XML format. Middleware4j handles these conversions automatically, running continuously in the background as a service.

== How It Works ==

Middleware4j monitors a set of input directories for incoming files. When a file arrives, it is read by the appropriate '''connector''', converted to an internal XML representation, optionally transformed by an XSLT stylesheet, and then written to one or more output destinations by one or more output connectors.

This pipeline is defined by a '''[[Maps|Map]]''' — a configuration block that specifies:
* One input connector (how to read the incoming file)
* One or more output connectors (where to send the result and in what format)
* Optional XSLT stylesheets for transforming the data
* Optional conditions for routing to different outputs based on message content

Multiple maps run simultaneously in background threads, each independently monitoring its own input directory.

== Supported Formats ==

{| class="wikitable"
|-
! Format !! Input !! Output
|-
| [[ASCII]] — fixed-column flat files || ✓ || ✓
|-
| [[CSV]] — delimited text files || ✓ || ✓
|-
| [[XML]] — structured XML documents || ✓ || ✓
|-
| IDOC — SAP IDOC format || ✓ || ✓
|-
| Excel — XLS/XLSX spreadsheets || ✓ || ✓
|-
| [[EMAIL]] — email with attachments || ✓ || ✓
|-
| [[RAW]] — unmodified file copy || ✓ || ✓
|-
| [[PDF_PRINT]] — print PDF to a named print queue || ✓ || ✓
|-
| [[SOCKET]] — TCP/IP socket transmission || || ✓
|-
| MQTT — publish to an MQTT broker || || ✓
|}

== XSLT Transformation ==

The transformation engine is built on '''Saxon 12''' (XSLT 2.0). Stylesheets can use standard XPath 2.0 expressions as well as a set of custom Middleware4j extension functions for string manipulation, date formatting, and reading from external reference data files.

Over 60 sample XSLT stylesheets are included covering real-world integration scenarios between Commander4j and common ERP and MES systems (SAP, Sage, Tropos, B2MML S95, and others).

== Deployment Modes ==

Middleware4j can be run in two modes:

{| class="wikitable"
|-
! Mode !! Description
|-
| '''Service''' || Runs as a background daemon (or Windows service) with no user interface. This is the normal production deployment.
|-
| '''GUI''' || Launches a desktop window showing configured maps and real-time message counts. Useful for testing and monitoring.
|}

See [[Installation Middleware4j]] for how to deploy as a Windows service.

== Relationship to Commander4j ==

Middleware4j processes Commander4j's outbound XML messages (such as Production Declarations, Despatch Advice, and Equipment Tracking events) and converts them into whatever format an external system requires. It also handles inbound flows — receiving data from external systems (material masters, process orders, pallet status changes) in their native format and converting them to Commander4j's XML interface format for import.

See also: [[Maps]], [[Connectors]], [[Middleware4j Example Configuration]], [[Installation Middleware4j]]

[[Category:Middleware4j]]