Commander4j - User contributions [en-gb]

File:Desktop icons.png

2026-11-06T16:31:56Z

Dgarratt: Dgarratt uploaded a new version of File:Desktop icons.png

Template:Menu Applications

2026-11-06T15:58:05Z

Dgarratt: Updated by push_wiki.py

<div style="max-width:980px; margin:0 auto 1.2em auto; padding:1.1em 1.4em; border:1px solid #c8d1e0; border-radius:10px; background:#f4f6fb;">
Commander4j and its companion applications '''bridge the gap between your ERP system and factory-floor labelling.'''

Orders and materials come down from the ERP. Operators print GS1 / SSCC pallet and case labels and record what was made. Production and despatch data go back up. Because Commander4j keeps its own database, labelling carries on when the link to head office is down and catches up when it returns.

'''New here?''' Start with the [[Install Guide]] and you will be logged in within the hour. Everything is free and open source (GPL v3).
</div>

<div class="c4j-fluid" style="max-width:980px; margin:0 auto;">
[[File:Commander4j_How_It_Fits.png|980px|center|link=]]
</div>

=Start here=
{| cellpadding="10" style="width:100%; max-width:980px; margin:0 auto; text-align:center; border-spacing:12px; table-layout:fixed;"
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | '''1. Download''' Which installer file to pick for your PC. [[Downloads|Downloads page]]
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | '''2. Install''' Database, installer and Setup4j, step by step. [[Install Guide|Install Guide]]
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | '''3. First login''' Default user, then set up your first materials and orders. [[First Login|First Login]]
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | '''Already installed?''' Upgrading to a newer version. [[Upgrading|Upgrading]]
|-
| colspan="4" style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | '''What is on a label, and how do I change it?''' Start with [[Label Layouts]] for a plain-language tour of the pallet label, then [[Changing a Label]] to make your first change in half an hour.
|}

=The core suite=
{| cellpadding="10" style="width:100%; max-width:980px; margin:0 auto; text-align:center; border-spacing:12px; table-layout:fixed;"
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:Commander4j_256x256.png|link=[[Commander4j]]|100px]] '''[[Commander4j]]''' Production recording, pallet and case labelling, despatch, quality, waste and weight checks. The core application.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:Middleware4j_256x256.png|link=[[Middleware4j]]|100px]] '''[[Middleware4j]]''' Converts and routes files between your ERP and Commander4j (CSV, XML, IDOC, fixed width).
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:LabelServer4j_256x256.png|link=[[LabelServer4j]]|100px]] '''[[LabelServer4j]]''' Background service that sends label data to case and secondary labellers.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:AutoLab4j_256x256.png|link=[[AutoLab4j]]|100px]] '''[[AutoLab4j]]''' Automatic pallet labelling triggered by the production line (MODBUS).
|}

=Tools and utilities=
{| cellpadding="10" style="width:100%; max-width:980px; margin:0 auto; text-align:center; border-spacing:12px; table-layout:fixed;"
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:ZPLRenderer_256x256.png|link=[[ZPLRenderer]]|100px]] '''[[ZPLRenderer]]''' Renders Zebra ZPL label commands on screen, from a file or over the network. Emulates a printer for testing.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:LogoRenderer_256x256.png|link=[[LogoRenderer]]|100px]] '''[[LogoRenderer]]''' Renders Logopak label templates and emulates a Logopak labeller's TCP protocol for local testing.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:LogoClient_256x256.png|link=[[LogoClient]]|100px]] '''[[LogoClient]]''' Companion to LogoRenderer for developing and testing solutions that talk to Logopak labellers.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:SocketTest_256x256.png|link=[[SocketTest]]|100px]] '''[[SocketTest]]''' Emulate a TCP/IP client or server to test printers, labellers and other network devices.
|-
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:ModbusBridge_256x256.png|link=[[ModbusBridge]]|100px]] '''[[ModbusBridge]]''' Relays values between a Modbus client and server, bridging communication between Modbus devices.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:ModbusClient_256x256.png|link=[[ModbusClient]]|100px]] '''[[ModbusClient]]''' Connect to a Modbus server, then view and change register and coil values.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:ModbusServer_256x256.png|link=[[ModbusServer]]|100px]] '''[[ModbusServer]]''' Run a Modbus server on your PC to simulate line equipment, then view and change its values.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:sftpTransfer_256x256.png|link=[[SFTPTransfer]]|100px]] '''[[SFTPTransfer]]''' Moves files automatically between a local folder and a remote SFTP server in both directions.
|-
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:SFTGet4j_256x256.png|link=[[SFTPGet]]|100px]] '''[[SFTPGet]]''' Watches a remote SFTP folder and moves each file that appears to a local folder.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:SFTPSend4j_256x256.png|link=[[SFTPSend]]|100px]] '''[[SFTPSend]]''' Watches a local folder and moves each file that appears to a remote SFTP folder.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:XMLViewer_256x256.png|link=[[XMLViewer]]|100px]] '''[[XMLViewer]]''' A simple viewer for XML documents, handy for checking interface messages.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:Menu4j_256x256.png|link=[[Menu4j]]|100px]] '''[[Menu4j]]''' Tree-based menu for organising and launching applications and command-line scripts from a single XML file.
|-
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:TreeDoc_256x256.png|link=[[TreeDoc]]|100px]] '''[[TreeDoc]]''' Creates plain-text documents that describe a folder structure.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:LaunchPad_256x256.png|link=[[LaunchPad]]|100px]] '''[[LaunchPad]]''' A replacement for the Launchpad application that Apple removed in macOS 26.
|
|
|}

File:LaunchPad 256x256.png

2026-11-06T15:58:04Z

Dgarratt: Dgarratt uploaded a new version of File:LaunchPad 256x256.png

File:TreeDoc 256x256.png

2026-11-06T15:58:03Z

Dgarratt: Dgarratt uploaded a new version of File:TreeDoc 256x256.png

File:Menu4j 256x256.png

2026-11-06T15:58:02Z

Dgarratt: Dgarratt uploaded a new version of File:Menu4j 256x256.png

File:XMLViewer 256x256.png

2026-11-06T15:58:01Z

Dgarratt: Dgarratt uploaded a new version of File:XMLViewer 256x256.png

File:SFTPSend4j 256x256.png

2026-11-06T15:58:00Z

Dgarratt: Dgarratt uploaded a new version of File:SFTPSend4j 256x256.png

File:SFTGet4j 256x256.png

2026-11-06T15:57:58Z

Dgarratt: Dgarratt uploaded a new version of File:SFTGet4j 256x256.png

File:SftpTransfer 256x256.png

2026-11-06T15:57:57Z

Dgarratt: Dgarratt uploaded a new version of File:SftpTransfer 256x256.png

File:ModbusServer 256x256.png

2026-11-06T15:57:56Z

Dgarratt: Refreshed application icon (Nov 2026)

Refreshed application icon (Nov 2026)

File:ModbusClient 256x256.png

2026-11-06T15:57:55Z

Dgarratt: Refreshed application icon (Nov 2026)

Refreshed application icon (Nov 2026)

File:ModbusBridge 256x256.png

2026-11-06T15:57:54Z

Dgarratt: Refreshed application icon (Nov 2026)

Refreshed application icon (Nov 2026)

File:SocketTest 256x256.png

2026-11-06T15:57:53Z

Dgarratt: Dgarratt uploaded a new version of File:SocketTest 256x256.png

File:LogoClient 256x256.png

2026-11-06T15:57:52Z

Dgarratt: Dgarratt uploaded a new version of File:LogoClient 256x256.png

File:LogoRenderer 256x256.png

2026-11-06T15:57:51Z

Dgarratt: Dgarratt uploaded a new version of File:LogoRenderer 256x256.png

File:ZPLRenderer 256x256.png

2026-11-06T15:57:50Z

Dgarratt: Dgarratt uploaded a new version of File:ZPLRenderer 256x256.png

File:AutoLab4j 256x256.png

2026-11-06T15:57:49Z

Dgarratt: Dgarratt uploaded a new version of File:AutoLab4j 256x256.png

File:LabelServer4j 256x256.png

2026-11-06T15:57:48Z

Dgarratt: Dgarratt uploaded a new version of File:LabelServer4j 256x256.png

File:Middleware4j 256x256.png

2026-11-06T15:57:47Z

Dgarratt: Dgarratt uploaded a new version of File:Middleware4j 256x256.png

File:Commander4j 256x256.png

2026-11-06T15:57:46Z

Dgarratt: Dgarratt uploaded a new version of File:Commander4j 256x256.png

SFTPSend

2026-10-22T11:08:10Z

Dgarratt: Updated by push_wiki.py

<div style="border-left:4px solid #1e40c8; background:#e8edfb; padding:0.7em 1em; margin:0 0 1em 0;">'''sftpSend has been replaced by [[SFTPTransfer]].''' sftpTransfer handles both directions in one application (sending files to an SFTP server as well as collecting them), with a configuration window, a Windows service option, stability checks and email notifications. sftpSend is no longer being developed: existing installations keep working, but new installations should use [[SFTPTransfer|sftpTransfer]] instead.</div>

In summary sftpSend is a utility which is designed to run as a service and it's purpose is to monitor a local folder for a file or files matching a mask and if found upload them to a remote SFTP machine. The local file is then removed.

See the partner program called [[SFTPGet]]

==Installation==
Download the installer for your operating system from [[https://github.com/C4J/sftpSend/releases GitHub]].
Note that the installer for Windows and MacOS contains a private bundled Jave runtime. However the Linux version requires you to have a Java 17 runtime installed on your distro.

I recommend that you don't install into Program Files folder on windows as this will encounter problems with read-only folder permissions.

Once installed you need to configure the application using the two xml config files shown below.

The program can be run from the command line in a terminal window, or configured as a service for unattended operation.

If you want to setup the program to run as a service you need to open a command prompt with Admininstrator permissions, change into the folder where you installed the application and then run the command line as shown below.

sftpSend_Service /install sftp_Send

You will then need to open up the services control panel within windows and change the account which the program uses to run. By default it will be "System" but you will probably need to create a windows account which has permissions to access the folder that you want to monitor for files.

==Configuration==

'''Folder Structure'''

SFTP Send
├── Images
├── lib
│ ├── app
│ ├── license
│ └── mail
├── logs
├── send
│ └── demo
├── ssh
└── xml
└── config

'''config.xml'''
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<config>

<sftpSend2>

<general>
<value id="title" encrypted="no">SFTP Example</value>
<value id="emailEnabled" encrypted="no">false</value>
</general>

<security>
<value id="remoteHost" encrypted="no">1.2.3.4</value>
<value id="remotePort" encrypted="no">22</value>
<value id="checkKnownHosts" encrypted="no">no</value>
<value id="knownHostsFile" encrypted="no">./ssh/known_hosts</value>
<value id="authType" encrypted="no">user password</value>
<value id="username" encrypted="no">testuser</value>
<value id="password" encrypted="no">testpassword</value>
<value id="privateKeyFile" encrypted="no">./ssh/sftpSend</value>
<value id="privateKeyPasswordProtected" encrypted="no">no</value>
<value id="privateKeyPassword" encrypted="no"/>
</security>

<source>
<value id="localDir" encrypted="no">./send/</value>
<value id="localFileMask" encrypted="no">*.xml</value>
<value id="backupDir" encrypted="no"></value>
<value id="pollFrequencySeconds" encrypted="no">5000</value>
</source>

<destination>
<value id="remoteDir" encrypted="no">/remote/</value>
<value id="tempFileExtension" encrypted="no">.tmp</value>
</destination>

</sftpSend2>

</config>
</syntaxhighlight>

{{Email Settings}}

SFTPGet

2026-10-22T11:08:08Z

Dgarratt: Updated by push_wiki.py

<div style="border-left:4px solid #1e40c8; background:#e8edfb; padding:0.7em 1em; margin:0 0 1em 0;">'''sftpGet has been replaced by [[SFTPTransfer]].''' sftpTransfer handles both directions in one application (collecting files from an SFTP server as well as sending them), with a configuration window, a Windows service option, stability checks and email notifications. sftpGet is no longer being developed: existing installations keep working, but new installations should use [[SFTPTransfer|sftpTransfer]] instead.</div>

In summary sftpGet is a utility which is designed to run as a service and it's purpose is to monitor a folder on a remote SFTP server for a file or files matching a mask and if found download them to the local machine. The remote file is then removed.

See the partner program called [[SFTPSend]]

==Installation==
Download the installer for your operating system from [[https://github.com/C4J/sftpGet/releases GitHub]].
Note that the installer for Windows and MacOS contains a private bundled Jave runtime. However the Linux version requires you to have a Java 17 runtime installed on your distro.

I recommend that you don't install into Program Files folder on windows as this will encounter problems with read-only folder permissions.

Once installed you need to configure the application using the two xml config files shown below.

The program can be run from the command line in a terminal window, or configured as a service for unattended operation.

If you want to setup the program to run as a service you need to open a command prompt with Admininstrator permissions, change into the folder where you installed the application and then run the command line as shown below.

sftpGet_Service /install sftp_Get

You will then need to open up the services control panel within windows and change the account which the program uses to run. By default it will be "System" but you will probably need to create a windows account which has permissions to access the folder that you want to monitor for files.

==Configuration==

'''Folder Structure'''

SFTP Get
├── Images
│ └── icons
│ └── SFTP_Get_Icons
│ └── MyIcon.iconset
├── get
│ └── demo
├── lib
│ ├── app
│ ├── license
│ └── mail
├── logs
├── ssh
└── xml
└── config

'''config.xml'''
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<config>

<sftpGet2>

<general>
<value id="title" encrypted="no">SFTP Get from SFTP Server</value>
<value id="emailEnabled" encrypted="no">false</value>
</general>

<security>
<value id="remoteHost" encrypted="no">192.168.1.51</value>
<value id="remotePort" encrypted="no">22</value>
<value id="checkKnownHosts" encrypted="no">no</value>
<value id="knownHostsFile" encrypted="no">./ssh/known_hosts</value>
<value id="authType" encrypted="no">user password</value>
<value id="username" encrypted="no">testuser</value>
<value id="password" encrypted="no">testpassword</value>
<value id="privateKeyFile" encrypted="no">./ssh/sftpSend</value>
<value id="privateKeyPasswordProtected" encrypted="no">no</value>
<value id="privateKeyPassword" encrypted="no"/>
</security>

<source>
<value id="remoteDir" encrypted="no">/My Remote Folder/</value>
<value id="remoteFileMask" encrypted="no">.xml</value>
<value id="pollFrequencySeconds" encrypted="no">20000</value>
</source>

<destination>
<value id="localDir" encrypted="no">./get/</value>
<value id="localFileMask" encrypted="no">*.xml</value>
<value id="backupDir" encrypted="no">./get/backup/</value>
<value id="tempFileExtension" encrypted="no">.tmp</value>
</destination>

</sftpGet2>

</config>
</syntaxhighlight>

{{Email Settings}}

SFTPTransfer

2026-10-22T09:53:43Z

Dgarratt: Updated by push_wiki.py

'''SFTPTransfer''' is a general purpose file transfer utility that moves or synchronises files between a local filesystem and a remote SFTP server. It is a standalone Java application with no dependency on any other Commander4j component: it can be used on its own wherever files need to be exchanged with an SFTP server on a schedule, and it runs on any platform with a Java runtime. It runs either as a headless background service or as a desktop application with a settings window and live log, and it uploads (Put) and downloads (Get) in independent threads.

SFTPTransfer replaces the earlier [[SFTPSend]] and [[SFTPGet]] tools with a single configurable service. Sites running [[Commander4j]] or [[Middleware4j]] typically use it to exchange files with ERP systems, customer portals, suppliers and print-and-apply labellers, but nothing in the program assumes those uses.

This page describes version 6.19.

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

== Purpose ==

SFTPTransfer polls a local folder (Put) and a remote folder (Get) at a configurable interval and transfers any file that matches a file mask. Each direction works in one of two modes:

{| class="wikitable"
|-
! Mode !! Behaviour
|-
| '''Move''' || Every matching file is copied to the other side and the source copy is deleted once the copy has been renamed into place. This is the default (Sync Mode unticked). Put can keep a local backup copy of each file it sends.
|-
| '''Sync''' || One-way mirror. New or changed files are copied, the source is left in place and the modified time is carried across so the file is not copied again. Optionally, files and folders that have disappeared from the source are deleted from the destination.
|}

It handles authentication, retry, backup, archiving, logging and email notification without operator involvement.

== Startup Modes ==

SFTPTransfer supports two startup modes selected by the first command line argument:

{| class="wikitable"
|-
! Mode !! Argument !! Behaviour
|-
| '''Desktop''' || <code>desktop</code> || Opens the settings window. Transfer threads start paused; press Run in the toolbar to begin polling. Used to configure the program and to watch transfers.
|-
| '''Service''' || <code>service</code> || Headless. Transfer threads start immediately and run until the process is stopped. Used for production deployment as a background service.
|}

The program reads its configuration from <code>./xml/config</code> relative to the working directory, so it must be started from its installation folder. To run it by hand:

java -Dlog4j.configurationFile=./xml/config/log4j2.xml -jar sftpTransfer.jar desktop
java -Dlog4j.configurationFile=./xml/config/log4j2.xml -jar sftpTransfer.jar service

The native install packages provide launchers for each mode:

{| class="wikitable"
|-
! Launcher !! Mode !! Use
|-
| <code>sftpTransfer</code> || Desktop || Settings window and live log.
|-
| <code>sftpTransfer_Console</code> || Service, in a console window || Runs the service logic with the log visible on screen. Useful during initial configuration.
|-
| <code>sftpTransfer_Service</code> || Service || On Windows this executable registers and controls the Windows service, see [[#Installing as a Windows Service|Installing as a Windows Service]]. On Linux and macOS use systemd, launchd or nohup with the <code>service</code> argument.
|}

A desktop window and a service can run on the same machine at the same time, see [[#Running the Desktop Beside a Service|Running the Desktop Beside a Service]].

== Installation Folder ==

{| class="wikitable"
|-
! Folder or file !! Contents
|-
| <code>xml/config/</code> || The configuration files described below, plus the runtime files <code>reload.request</code> and <code>service.lock</code>.
|-
| <code>xml/config/examples/</code> || Neutral example copies of every configuration file.
|-
| <code>ssh/</code> || <code>known_hosts</code> and, if key authentication is used, the private and public key files.
|-
| <code>safety/</code> || The template <code>local.safe</code> and <code>remote.safe</code> files copied by the Create buttons, see [[#Safe Files|Safe Files]].
|-
| <code>logs/</code> || <code>sftpTransfer.log</code> and its rolled-over archives.
|-
| <code>send/</code>, <code>receive/</code>, <code>backups/</code> || Default local, download and backup folders used by the example configuration. Any folder can be configured instead.
|}

== Desktop Window ==

The window has the settings tabs on the left and a combined log on the right, separated by a draggable divider.

=== Tabs ===

{| class="wikitable"
|-
! Tab !! Settings
|-
| '''SFTP''' || Title, SFTP host and port, known hosts handling, authentication type, SFTP username and password, private and public key files, email, daily statistics and web log viewer switches, settings password. Saved in <code>sftp_common.xml</code>.
|-
| '''Put Properties''' || Upload settings. Saved in <code>sftp_put.xml</code>.
|-
| '''Get Properties''' || Download settings. Saved in <code>sftp_get.xml</code>.
|-
| '''jsch Properties''' || Advanced SSH session parameters passed to the JSch library. Saved in <code>jsch_properties.xml</code>.
|-
| '''Email Properties''' || SMTP properties and the three distribution lists, plus a Send Test Email button. Saved in <code>email_properties.xml</code> and <code>email_distribution_properties.xml</code>.
|}

=== Toolbar ===

{| class="wikitable"
|-
! Button !! Action
|-
| '''Run / Pause''' || Starts or pauses the transfer threads of this window. A pass that is under way stops at the next file boundary: the file in flight is finished, the remaining files wait for the next poll, and the pass summary and Transfer email record that the pass was paused. Pausing closes the SFTP sessions. Disabled while a service is running on the same machine.
|-
| '''Apply''' || Saves the settings on screen to <code>xml/config</code>, hands them to the running threads and writes a reload request for any service running on this machine. Enabled only when the form differs from what is on disk.
|-
| '''Reload''' || Re-reads the saved files into the form, discarding edits that have not been applied.
|-
| '''Help''' || Opens this page in the default browser.
|-
| '''About''' and '''Licences''' || Version and third party licence information.
|}

Settings are taken up by each thread between passes: a transfer pass that is in progress finishes with the old settings, including any sync deletions, and the status line shows "Waiting for the current transfer to complete" until both threads have changed over. Only Pause and a service stop interrupt a pass; Apply never does. Every Apply drops the SFTP sessions and reconnects with the new settings on the next pass.

The Local Folder, Remote Folder and Backup Folder fields each have a browse button. The remote browse connects with the SFTP settings as typed on the SFTP tab, so the paths can be chosen before anything has been applied or run.

=== Log Panel ===

The log panel shows the Put, Get and System logs merged in time order, each line prefixed <code>[PUT]</code>, <code>[GET]</code> or <code>[SYS]</code>. Long lines wrap. The strip above the log holds:

{| class="wikitable"
|-
! Control !! Action
|-
| '''System / Put / Get''' || Hide or show each log. Hidden lines are kept and reappear when the box is ticked again. All three are ticked at every start.
|-
| '''Clear''' || Empties the log window. The log file and the web viewer are not affected.
|-
| '''Save''' || Writes the lines currently shown to a text file (default <code>logs/sftpTransfer_window_<date>.txt</code>).
|-
| '''Log Level''' || Errors only, Warnings and errors, Normal or Debug. Applies to new lines. Normal hides the polling of the remote folders; Debug shows every <code>ls</code>. The choice is remembered in <code>sftp_common.xml</code>. A running service keeps its level until the next Apply.
|}

Two progress bars beneath the strip, Put (orange) and Get (blue), show the file being transferred, the percentage and the bytes so far. A finished file stays on show until the next one starts.

== Configuration Files ==

All configuration is held in XML files under <code>xml/config/</code>. Every value has an <code>encrypted</code> attribute; passwords are stored encrypted and are set from the desktop window, never typed into the file. Settings added in later versions are optional: a file written by an earlier version is read with the defaults shown below.

=== sftp_common.xml ===

The connection and the program-wide switches, shared by Put and Get:

{| class="wikitable"
|-
! Setting !! Description
|-
| Title || Free text shown in the window title, the web page and email subjects.
|-
| Host Address, Port || SFTP server and port (default 22). There is one server: Put and Get both use it.
|-
| Known Hosts File, Add to Known Hosts File || Path to the <code>known_hosts</code> file (default <code>./ssh/known_hosts</code>) and whether an unknown host key is added automatically.
|-
| Authentication Type || <code>user password</code> or <code>user public key</code>.
|-
| SFTP Username, SFTP Password || SFTP login. The password is set with the Assign SFTP user password button and stored encrypted.
|-
| Private Key File, Public Key File, Key Comment, Private Key Password || Key pair for public key authentication (default <code>./ssh/sftpTransfer</code> and <code>.pub</code>). The Create button generates a new pair. The key password is set with its Assign button and stored encrypted.
|-
| Email Notifications || Master switch for all email, see [[#Email Notifications|Email Notifications]]. Default off.
|-
| Daily Statistics Email, at || Sends the day's transfer counts to the Monitor list once a day at the given time (HH:mm, '''UTC''', not this machine's clock, so servers in different time zones report on the same day boundary). Default off, 06:00.
|-
| Web Log Viewer, Port || Serves the logs as a read-only web page, see [[#Web Log Viewer|Web Log Viewer]]. Default off, port 8080.
|-
| SettingsPassword || Optional. When set, the desktop window asks for it at start-up before the settings can be seen or changed. Set and cleared with its own buttons.
|-
| Log Level || The desktop log level, written whenever the combo is changed.
|}

=== sftp_put.xml ===

The upload (Put) settings:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether the Put thread transfers anything. A disabled side logs a warning at start-up and does nothing.
|-
| Title || Free text, shown in the Put log and emails.
|-
| Local Folder || Folder watched for outbound files. Must contain <code>local.safe</code>.
|-
| Local File Mask || One or more wildcard masks separated by <code>;</code>, for example <code>*.xml;*.csv</code>. See [[#File Masks|File Masks]].
|-
| Backup Folder, Backup Retention || Move mode only. Each sent file is copied here (sub folder structure preserved) before the local copy is deleted, and copies older than the retention period in days are purged. Greyed out in Sync Mode. The purge only runs when a marker file named <code>backup.folder</code> exists in the backup folder.
|-
| Poll Frequency || Seconds between passes, 1 to 86400 (one day). A value outside that range is refused by Apply with a message naming the field. Default 10.
|-
| Remote Folder || Destination folder on the server. Must contain <code>remote.safe</code>.
|-
| Temporary File Extension || Files are uploaded under this extension (default <code>.tmp</code>) and renamed on completion, so the remote side never sees a partial file. Files carrying the extension are never selected for transfer.
|-
| Include Sub Folders || Also send files from folders beneath the local folder, recreating the structure on the server. Default off.
|-
| Sync Mode || Copy new or changed files and leave the local files in place. Unticked means move mode. Default off.
|-
| Overwrite Newer || Sync only. Also replace a newer remote file with an older local one. Default on.
|-
| Sync Deletions || Sync only. Also delete remote files which are no longer in the local folder. Default off.
|-
| Sync Folder Deletions || Sync only, needs Include Sub Folders and Sync Deletions. Also remove remote folders which are no longer in the local folder. Default off.
|-
| Stability Check, Seconds, Retries || Only transfer a file once it has stopped changing for the given number of seconds. A file that is still changing after the wait is checked again, up to Retries times, each after another full wait; only then is it skipped until the next poll. Retries 0 restores the single check. Default off, 5 seconds, 5 retries (an installation upgraded from an earlier version gets 5). With the defaults one file that keeps growing can hold a pass for up to six times the stability seconds.
|}

=== sftp_get.xml ===

The download (Get) settings have the same options seen from the other side:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether the Get thread transfers anything.
|-
| Title || Free text, shown in the Get log and emails.
|-
| Remote Folder || Folder on the server polled for incoming files. Must contain <code>remote.safe</code>.
|-
| Remote File Mask || One or more wildcard masks separated by <code>;</code>, matched against the remote listing.
|-
| Local Folder || Folder where downloaded files are saved. Must contain <code>local.safe</code>.
|-
| Poll Frequency || Seconds between passes, 1 to 86400 (one day). A value outside that range is refused by Apply with a message naming the field. Default 10.
|-
| Temporary File Extension || Files are downloaded under this extension and renamed on completion.
|-
| Include Sub Folders || Also fetch files from folders beneath the remote folder.
|-
| Sync Mode || Copy new or changed files and leave the remote files in place. Unticked means move mode (the remote file is deleted after a completed download).
|-
| Overwrite Newer || Sync only. Also replace a newer local file with an older remote one. Default on.
|-
| Sync Deletions || Sync only. Also delete local files which are no longer in the remote folder.
|-
| Sync Folder Deletions || Sync only. Also remove local folders which are no longer in the remote folder.
|-
| Stability Check, Seconds, Retries || Only fetch a file once the remote listing shows it unchanged for the given number of seconds. A file that is still changing is listed again, up to Retries times, each after another full wait, before it is skipped until the next poll. Retries 0 restores the single check. Default off, 5 seconds, 5 retries.
|}

=== jsch_properties.xml ===

Session parameters passed directly to the JSch library: strict host key checking, preferred authentication methods, key exchange, cipher, MAC and host key algorithm lists, compression and proxy settings. Each row can be enabled or disabled and encrypted individually. The shipped defaults suit most servers; change them only when a server insists on a particular algorithm.

=== email_properties.xml ===

Jakarta Mail SMTP properties. Six rows are always present and cannot be removed: <code>mail.smtp.host</code>, <code>mail.smtp.port</code>, <code>mail.smtp.from</code>, <code>mail.smtp.auth</code>, <code>mail.smtp.user</code> and <code>mail.smtp.password</code>; a file that lacks any of them gains the row, disabled and empty, the next time the desktop is opened. The '''Add Property''' button beside Send Test Email offers the usual TLS, SSL, socket factory, timeout, charset and debug properties with suggested values, or any other name typed in; '''Remove Property''' deletes the selected row and refuses the six required ones. The password row is stored encrypted. Rows with Enable unticked are left out of the session. A server that answers <code>530 ... anonymous mail</code> or a similar authentication error usually needs <code>mail.smtp.auth</code> enabled and set to <code>true</code>.

=== email_distribution_properties.xml ===

The three distribution lists. Each has an address list (comma separated), an Enable flag and a Frequency in minutes, see [[#Email Notifications|Email Notifications]].

=== log4j2.xml ===

Log file location, rollover and retention, see [[#Logging|Logging]].

== Safe Files ==

A transfer pass does nothing unless both of these files exist:

{| class="wikitable"
|-
! File !! Where
|-
| <code>local.safe</code> || In the root of the Local Folder (Put and Get each have their own).
|-
| <code>remote.safe</code> || In the root of the Remote Folder on the server.
|}

The files prove that the configured folders are the intended ones and that any network share or mount behind them is actually present. Without them a mistyped path, an unmounted share or an empty folder could otherwise look like "nothing to send" or, with Sync Deletions on, empty the other side. Only the name matters, not the content.

* The Put and Get tabs have Create (tick) and Remove (cross) buttons beside the Local Folder and Remote Folder fields. Create copies the template from the <code>safety</code> folder into the folder typed in the field, after showing the full path and asking for confirmation. The remote buttons open their own SFTP session.
* A missing safe file is logged once as a warning (<code>Nothing sent, safe file not found : ...</code>) and again after Apply or a restart; transfers resume at the next poll once the file appears.
* The safe files are never transferred, deleted or counted, whatever the file mask.
* The remote check lists the remote folder, so the SFTP account must be permitted to list it.
* Create the local file only while any share it lives on is mounted, otherwise the empty mount point is what gets approved.

When upgrading from a version before 6.10, nothing transfers until the safe files have been created. Where the remote server is owned by another party they will need to place <code>remote.safe</code> for you.

== File Masks ==

The Local File Mask (Put) and Remote File Mask (Get) accept the wildcards <code>*</code> and <code>?</code>. Several masks can be given separated by <code>;</code>, for example <code>*.xml;*.csv</code>; spaces around a mask are ignored.

* Put matching is case-insensitive; Get matching follows the server listing and is case-sensitive.
* A blank mask matches nothing on both sides.
* Files carrying the Temporary File Extension are always skipped, even with a mask of <code>*</code>.
* A folder whose name matches the mask is skipped, never transferred or deleted.
* The mask is also the scope of Sync Deletions: only files matching it are deleted from the destination.

== Transfer Behaviour ==

=== Move Mode ===

Move mode is in force when Sync Mode is unticked.

# Each poll collects the files matching the mask (and, with Include Sub Folders, those in folders beneath).
# With Stability Check on, the thread waits until the collection is the configured number of seconds old, then re-checks each file's size and modified time. A file that has changed is waited for again, up to the configured number of Retries (logged as <code>Still changing ... retry n of m</code>); a file that is still changing after the last retry is skipped with a warning and picked up on the next poll.
# Put: the file is copied to the backup folder if backup is on, uploaded under the temporary extension, renamed to its final name, and only then deleted locally. Get: the file is downloaded under the temporary extension, renamed, and only then deleted from the server. A partial transfer is removed and the source is left in place.
# Sub folders are created on the destination as needed. The configured folders themselves are never created or removed, and emptied source sub folders are left in place.
# A file that keeps failing is retried and logged on every poll. There is no error folder.

=== Sync Mode ===

Sync Mode is a one-way mirror from source to destination; the source is never deleted. For each file the destination copy is compared by size and modified time:

{| class="wikitable"
|-
! Destination copy !! Action
|-
| Missing, older, or same time with a different size || Transferred. The modified time is carried across.
|-
| Identical (same size and time) || Skipped silently.
|-
| Newer than the source || Transferred only when Overwrite Newer is ticked. Otherwise kept, logged at Debug level only.
|}

With Include Sub Folders on, empty folders are created on the destination too.

'''Sync Deletions''': at the end of each folder, a destination file is deleted when it matches the mask, does not carry the temporary extension and no file of that name exists in the matching source folder. Folders are never removed by this option, and folders that exist only at the destination are left alone with their contents. Nothing is deleted when a folder cannot be listed or when the pass is interrupted. An empty source folder (with its safe file present) empties the destination of mask-matching files.

'''Sync Folder Deletions''' (needs Include Sub Folders and Sync Deletions): a folder that exists only at the destination has its mask-matching files deleted and is removed once it is empty. A folder still holding a file the mask does not cover is kept with that file. A folder is only judged to be destination-only when nothing of that name exists at the source, including a file or a link.

Each folder is processed in full (transfers, then deletions) before the next one is started, and a log line <code>Folder <path></code> is written before the first action in a folder.

Points to note:

* Do not tick Sync Deletions on both Put and Get against the same pair of folders.
* Sync Folder Deletions treats every folder beneath the destination as in scope. A "processed" folder created on the server by another system, or an archive folder beneath the receive folder, will lose its mask-matching files.
* On a Mac, Finder's <code>.DS_Store</code> file does not match a mask such as <code>*.xml</code>, so a browsed folder is emptied but not removed.
* Backup is for move mode: in Sync Mode the source file is still there, so the backup row is greyed out and no backup copy is taken.

=== Pass Summary ===

Every pass that transferred, failed or skipped at least one file ends with <code>Transfer finished - n sent, n failed, n skipped in n s</code>. A pass that does not run to its end says instead <code>Transfer interrupted by shutdown</code>, <code>Transfer paused from the window</code> or <code>Transfer abandoned, connection lost</code>, followed by the same counts, and the Transfer email for that pass carries an <code>Outcome</code> row saying so and listing the files that did get through; the rest are sent or fetched on the next poll. A pass with nothing to do writes nothing at the Normal log level, so an idle service produces a quiet log.

Each thread disconnects from the server at the end of every pass and reconnects at the start of the next, so a long poll interval never leaves an idle session for a firewall or the server to drop. The log therefore shows Connecting, Connected and Disconnected on every pass, including an idle one.

== Applying Settings to a Running Service ==

A service reads <code>xml/config</code> at start-up and whenever the file <code>xml/config/reload.request</code> appears. The desktop's Apply button writes the settings and then writes that file; a service on the same machine collects it within a second, re-reads the six configuration files, hands the settings to its threads (between passes) and deletes the file. The desktop status line reports whether a service collected the request.

An empty <code>reload.request</code> created by any other means works too, so settings prepared on another machine can be copied into place and activated without restarting the service. If any configuration file fails to parse, the service logs an error, keeps its current settings and drops the request. A stale request found at service start-up is removed.

== Running the Desktop Beside a Service ==

A service holds an operating system lock on <code>xml/config/service.lock</code> for as long as it runs. A desktop window started in the same installation folder detects it within a couple of seconds and:

* shows a banner "A service is running on this machine - transfers and the web log viewer are its job. Apply hands it the new settings.";
* disables its Run button, and if transfers were running from the window, pauses them at the end of the current pass;
* leaves the web log viewer to the service.

When the service stops, the banner clears and the window's Run button and viewer come back. The browse buttons and safe file buttons work regardless, as they open their own short-lived sessions. The lock file is left behind when the service stops; this is normal.

== Web Log Viewer ==

When Web Log Viewer is ticked on the SFTP tab, the program serves its log on <code>http://<host>:<port>/</code> (default port 8080) in both desktop and service mode. The page shows the same merged Put, Get and System log as the desktop, with a Log Level selector (remembered by the browser), System / Put / Get check boxes, the thread states, a text filter, auto-scroll and Clear. It updates live and recovers the backlog after a reconnect.

Read-only endpoints for monitoring tools:

{| class="wikitable"
|-
! URL !! Returns
|-
| <code>/</code> || The log page.
|-
| <code>/api/status</code> || JSON with version, title and the Put and Get thread states.
|-
| <code>/api/log?dest=put|get|sys</code> || JSON backlog for one log, optionally <code>&after=<seq></code>.
|-
| <code>/events</code> || Server-sent event stream of new log lines.
|}

The viewer has no login and listens on every network interface. Log lines include the SFTP host, username and file names, so keep the port on the LAN or behind a firewall. If the port is in use the program logs a warning and carries on transferring; a service retries the port every few seconds.

== Email Notifications ==

Email is off unless Email Notifications is ticked on the SFTP tab and the SMTP properties are filled in on the Email Properties tab. Messages are routed through three distribution lists:

{| class="wikitable"
|-
! List !! Receives !! Shipped default
|-
| '''Monitor''' || Started and Stopped (service start and shutdown, Run and Pause in the desktop) and the Daily Statistics Email (files and bytes sent and received, failures, errors raised and emailed). || Enabled, frequency 0
|-
| '''Error''' || One message per error event: Connection failed, Connection lost, Upload failed, Download failed, Local folder not found, Remote folder could not be listed, Safe file missing, Local delete failed, Remote delete failed, Backup copy failed. Connection failed is sent once per outage, however many polls fail, and a Connection lost (a session dropped part-way through a pass) opens an outage in the same way. Either is followed by a single Connection restored message (with the time the outage started and its length) when the next connection succeeds. A folder listing that failed because the session dropped is reported as Connection lost alone, not also as Remote folder could not be listed. || Enabled, frequency 15 minutes
|-
| '''Transfer''' || One message per pass that transferred at least one file, listing the files and sizes (Put Files sent, Get Files received). Passes with nothing to do send nothing; failures go to the Error list. || Disabled, frequency 0
|}

Subjects follow the pattern <code>SFTP Transfer <version> [Put|Get] <Event> for [<title>] on <host></code>. The body is an HTML table of label and value rows (Time, Host, Title, Folder, File, Reason, Files and so on; paths are shown in a fixed-width font) followed by a blank gap so that a corporate disclaimer appended by the mail server sits clear of the detail. The Time row is in UTC. The Frequency of a list suppresses a repeat of the same subject within that many minutes, so a file that fails on every poll produces one email per interval rather than one per poll; a suppressed email is noted in the log. A connection that stays down produces one Connection failed email for the whole outage, whatever the Frequency, and one Connection restored email when the link is back; every failed poll in between is logged as an error with a note that the email has already been sent. Because the Transfer list's subject is the same for every pass, '''its frequency must stay at 0''' or whole passes would be suppressed as repeats.

The Send Test Email button on the Email Properties tab sends a message to a chosen list using the settings on screen and reports the result on the status line, without needing Email Notifications to be ticked.

Each distribution list has an Enable flag and a comma separated address list. An installation upgraded from an earlier version gains the Transfer list, disabled, the first time the desktop is opened.

== Installing as a Windows Service ==

The Windows 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'''. You can specify a different name as an optional second parameter, which allows several instances to run from separate installation folders on the same machine. If a custom name is used at install time, the 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>).

Before installing the service, configure and test with the desktop launcher <code>sftpTransfer.exe</code> (threads start paused) or <code>sftpTransfer_Console.exe</code> (service logic with the log in a console window). Once the service is installed, the desktop can still be opened alongside it to change settings, see [[#Running the Desktop Beside a Service|Running the Desktop Beside a Service]].

== Authentication ==

Authentication is configured once on the SFTP tab and used by both directions:

{| class="wikitable"
|-
! Method !! How to configure
|-
| User password || Authentication Type <code>user password</code>. Enter the SFTP Username and set the SFTP Password with its Assign button.
|-
| User public key || Authentication Type <code>user public key</code>. Point Private Key File and Public Key File at an existing pair, or press Create to generate a pair and then install the public key on the server yourself. If the private key is passphrase protected, set the passphrase with the Private Key Password Assign button.
|}

Host keys are checked against the Known Hosts File. With Add to Known Hosts File ticked (or <code>StrictHostKeyChecking</code> set to <code>no</code> in the jsch properties, as shipped) a new server's key is recorded on first connection.

All SSH is handled by the JSch library with Bouncy Castle as the cryptographic provider.

=== Password Encryption ===

The SFTP password, the private key passphrase, the SMTP password and the settings password are stored encrypted in the XML files. They are set through the desktop window: each password field has an Assign button that opens a dialog, and the encrypted value is written when settings are applied. Plain text passwords are never stored. The encrypted values are specific to SFTPTransfer and cannot be copied from the configuration of other Commander4j programs.

== Thread Architecture ==

{| class="wikitable"
|-
! Thread !! Purpose
|-
| TransferPUT || Polls the local folder and uploads. Opens its own SFTP session for each pass and closes it afterwards.
|-
| TransferGET || Polls the remote folder and downloads. Opens its own SFTP session for each pass and closes it afterwards, so Put and Get can fail and reconnect independently.
|-
| EmailThread || Sends queued emails asynchronously so a slow SMTP server never delays a transfer.
|-
| ArchiveThread || Purges backup copies older than the retention period.
|-
| StatsThread || Sends the Daily Statistics Email at the configured time.
|-
| ReloadWatcher || Service mode only. Watches for <code>reload.request</code>.
|}

In the desktop the window's own browse and safe file buttons use a separate short-lived session.

== Logging ==

Every line shown in the window is also written to <code>logs/sftpTransfer.log</code>, in both desktop and service mode, tagged <code>[PUT]</code>, <code>[GET]</code>, <code>[SYS]</code> or <code>[GUI]</code> (the window's own connections). The log records:

* Service or window start and stop, and the settings loaded or applied
* Connecting, Connected (with the server's SSH banner), Disconnected and Connection lost for each session
* Every command sent to the server (<code>ls</code>, <code>stat</code>, <code>put</code>, <code>get</code>, <code>rename</code>, <code>rm</code>, <code>mkdir</code>, <code>rmdir</code>, <code>setstat</code>), with the full paths on failure
* Folder headings, Sending / Sent, Receiving / Received with sizes and durations, stability retries and skips, sync deletions and the pass summary with its outcome
* Safe file warnings, reload requests, service lock and web viewer events
* Errors and exceptions with their reason

The shipped <code>log4j2.xml</code> rolls the file over at 10 MB or daily, keeps 14 days of compressed archives and logs at <code>debug</code>. The listing of the remote folders on an idle poll is written at <code>trace</code>; set the root level to <code>trace</code> to see it in the file.

== Dependencies ==

{| class="wikitable"
|-
! Library !! Version !! Purpose
|-
| JSch || 2.27.9 || SSH / SFTP client
|-
| Bouncy Castle || 1.86 || Cryptographic provider for JSch
|-
| Apache Commons IO || 2.21.0 || Wildcard file matching
|-
| Jakarta Mail / Angus Mail || 2.1.5 / 2.0.5 || Email notifications
|-
| Log4j || 2.25.5 || Logging
|}

Source code and installers: https://github.com/C4J/sftpTransfer

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

[[Category:Commander4j]]

SFTPTransfer

2026-10-20T13:40:07Z

Dgarratt: Updated by push_wiki.py

'''SFTPTransfer''' is a general purpose file transfer utility that moves or synchronises files between a local filesystem and a remote SFTP server. It is a standalone Java application with no dependency on any other Commander4j component: it can be used on its own wherever files need to be exchanged with an SFTP server on a schedule, and it runs on any platform with a Java runtime. It runs either as a headless background service or as a desktop application with a settings window and live log, and it uploads (Put) and downloads (Get) in independent threads.

SFTPTransfer replaces the earlier [[SFTPSend]] and [[SFTPGet]] tools with a single configurable service. Sites running [[Commander4j]] or [[Middleware4j]] typically use it to exchange files with ERP systems, customer portals, suppliers and print-and-apply labellers, but nothing in the program assumes those uses.

This page describes version 6.18.

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

== Purpose ==

SFTPTransfer polls a local folder (Put) and a remote folder (Get) at a configurable interval and transfers any file that matches a file mask. Each direction works in one of two modes:

{| class="wikitable"
|-
! Mode !! Behaviour
|-
| '''Move''' || Every matching file is copied to the other side and the source copy is deleted once the copy has been renamed into place. This is the default (Sync Mode unticked). Put can keep a local backup copy of each file it sends.
|-
| '''Sync''' || One-way mirror. New or changed files are copied, the source is left in place and the modified time is carried across so the file is not copied again. Optionally, files and folders that have disappeared from the source are deleted from the destination.
|}

It handles authentication, retry, backup, archiving, logging and email notification without operator involvement.

== Startup Modes ==

SFTPTransfer supports two startup modes selected by the first command line argument:

{| class="wikitable"
|-
! Mode !! Argument !! Behaviour
|-
| '''Desktop''' || <code>desktop</code> || Opens the settings window. Transfer threads start paused; press Run in the toolbar to begin polling. Used to configure the program and to watch transfers.
|-
| '''Service''' || <code>service</code> || Headless. Transfer threads start immediately and run until the process is stopped. Used for production deployment as a background service.
|}

The program reads its configuration from <code>./xml/config</code> relative to the working directory, so it must be started from its installation folder. To run it by hand:

java -Dlog4j.configurationFile=./xml/config/log4j2.xml -jar sftpTransfer.jar desktop
java -Dlog4j.configurationFile=./xml/config/log4j2.xml -jar sftpTransfer.jar service

The native install packages provide launchers for each mode:

{| class="wikitable"
|-
! Launcher !! Mode !! Use
|-
| <code>sftpTransfer</code> || Desktop || Settings window and live log.
|-
| <code>sftpTransfer_Console</code> || Service, in a console window || Runs the service logic with the log visible on screen. Useful during initial configuration.
|-
| <code>sftpTransfer_Service</code> || Service || On Windows this executable registers and controls the Windows service, see [[#Installing as a Windows Service|Installing as a Windows Service]]. On Linux and macOS use systemd, launchd or nohup with the <code>service</code> argument.
|}

A desktop window and a service can run on the same machine at the same time, see [[#Running the Desktop Beside a Service|Running the Desktop Beside a Service]].

== Installation Folder ==

{| class="wikitable"
|-
! Folder or file !! Contents
|-
| <code>xml/config/</code> || The configuration files described below, plus the runtime files <code>reload.request</code> and <code>service.lock</code>.
|-
| <code>xml/config/examples/</code> || Neutral example copies of every configuration file.
|-
| <code>ssh/</code> || <code>known_hosts</code> and, if key authentication is used, the private and public key files.
|-
| <code>safety/</code> || The template <code>local.safe</code> and <code>remote.safe</code> files copied by the Create buttons, see [[#Safe Files|Safe Files]].
|-
| <code>logs/</code> || <code>sftpTransfer.log</code> and its rolled-over archives.
|-
| <code>send/</code>, <code>receive/</code>, <code>backups/</code> || Default local, download and backup folders used by the example configuration. Any folder can be configured instead.
|}

== Desktop Window ==

The window has the settings tabs on the left and a combined log on the right, separated by a draggable divider.

=== Tabs ===

{| class="wikitable"
|-
! Tab !! Settings
|-
| '''SFTP''' || Title, SFTP host and port, known hosts handling, authentication type, SFTP username and password, private and public key files, email, daily statistics and web log viewer switches, settings password. Saved in <code>sftp_common.xml</code>.
|-
| '''Put Properties''' || Upload settings. Saved in <code>sftp_put.xml</code>.
|-
| '''Get Properties''' || Download settings. Saved in <code>sftp_get.xml</code>.
|-
| '''jsch Properties''' || Advanced SSH session parameters passed to the JSch library. Saved in <code>jsch_properties.xml</code>.
|-
| '''Email Properties''' || SMTP properties and the three distribution lists, plus a Send Test Email button. Saved in <code>email_properties.xml</code> and <code>email_distribution_properties.xml</code>.
|}

=== Toolbar ===

{| class="wikitable"
|-
! Button !! Action
|-
| '''Run / Pause''' || Starts or pauses the transfer threads of this window. A pass that is under way stops at the next file boundary: the file in flight is finished, the remaining files wait for the next poll, and the pass summary and Transfer email record that the pass was paused. Pausing closes the SFTP sessions. Disabled while a service is running on the same machine.
|-
| '''Apply''' || Saves the settings on screen to <code>xml/config</code>, hands them to the running threads and writes a reload request for any service running on this machine. Enabled only when the form differs from what is on disk.
|-
| '''Reload''' || Re-reads the saved files into the form, discarding edits that have not been applied.
|-
| '''Help''' || Opens this page in the default browser.
|-
| '''About''' and '''Licences''' || Version and third party licence information.
|}

Settings are taken up by each thread between passes: a transfer pass that is in progress finishes with the old settings, including any sync deletions, and the status line shows "Waiting for the current transfer to complete" until both threads have changed over. Only Pause and a service stop interrupt a pass; Apply never does. Every Apply drops the SFTP sessions and reconnects with the new settings on the next pass.

The Local Folder, Remote Folder and Backup Folder fields each have a browse button. The remote browse connects with the SFTP settings as typed on the SFTP tab, so the paths can be chosen before anything has been applied or run.

=== Log Panel ===

The log panel shows the Put, Get and System logs merged in time order, each line prefixed <code>[PUT]</code>, <code>[GET]</code> or <code>[SYS]</code>. Long lines wrap. The strip above the log holds:

{| class="wikitable"
|-
! Control !! Action
|-
| '''System / Put / Get''' || Hide or show each log. Hidden lines are kept and reappear when the box is ticked again. All three are ticked at every start.
|-
| '''Clear''' || Empties the log window. The log file and the web viewer are not affected.
|-
| '''Save''' || Writes the lines currently shown to a text file (default <code>logs/sftpTransfer_window_<date>.txt</code>).
|-
| '''Log Level''' || Errors only, Warnings and errors, Normal or Debug. Applies to new lines. Normal hides the polling of the remote folders; Debug shows every <code>ls</code>. The choice is remembered in <code>sftp_common.xml</code>. A running service keeps its level until the next Apply.
|}

Two progress bars beneath the strip, Put (orange) and Get (blue), show the file being transferred, the percentage and the bytes so far. A finished file stays on show until the next one starts.

== Configuration Files ==

All configuration is held in XML files under <code>xml/config/</code>. Every value has an <code>encrypted</code> attribute; passwords are stored encrypted and are set from the desktop window, never typed into the file. Settings added in later versions are optional: a file written by an earlier version is read with the defaults shown below.

=== sftp_common.xml ===

The connection and the program-wide switches, shared by Put and Get:

{| class="wikitable"
|-
! Setting !! Description
|-
| Title || Free text shown in the window title, the web page and email subjects.
|-
| Host Address, Port || SFTP server and port (default 22). There is one server: Put and Get both use it.
|-
| Known Hosts File, Add to Known Hosts File || Path to the <code>known_hosts</code> file (default <code>./ssh/known_hosts</code>) and whether an unknown host key is added automatically.
|-
| Authentication Type || <code>user password</code> or <code>user public key</code>.
|-
| SFTP Username, SFTP Password || SFTP login. The password is set with the Assign SFTP user password button and stored encrypted.
|-
| Private Key File, Public Key File, Key Comment, Private Key Password || Key pair for public key authentication (default <code>./ssh/sftpTransfer</code> and <code>.pub</code>). The Create button generates a new pair. The key password is set with its Assign button and stored encrypted.
|-
| Email Notifications || Master switch for all email, see [[#Email Notifications|Email Notifications]]. Default off.
|-
| Daily Statistics Email, at || Sends the day's transfer counts to the Monitor list once a day at the given time (HH:mm, '''UTC''', not this machine's clock, so servers in different time zones report on the same day boundary). Default off, 06:00.
|-
| Web Log Viewer, Port || Serves the logs as a read-only web page, see [[#Web Log Viewer|Web Log Viewer]]. Default off, port 8080.
|-
| SettingsPassword || Optional. When set, the desktop window asks for it at start-up before the settings can be seen or changed. Set and cleared with its own buttons.
|-
| Log Level || The desktop log level, written whenever the combo is changed.
|}

=== sftp_put.xml ===

The upload (Put) settings:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether the Put thread transfers anything. A disabled side logs a warning at start-up and does nothing.
|-
| Title || Free text, shown in the Put log and emails.
|-
| Local Folder || Folder watched for outbound files. Must contain <code>local.safe</code>.
|-
| Local File Mask || One or more wildcard masks separated by <code>;</code>, for example <code>*.xml;*.csv</code>. See [[#File Masks|File Masks]].
|-
| Backup Folder, Backup Retention || Move mode only. Each sent file is copied here (sub folder structure preserved) before the local copy is deleted, and copies older than the retention period in days are purged. Greyed out in Sync Mode. The purge only runs when a marker file named <code>backup.folder</code> exists in the backup folder.
|-
| Poll Frequency || Seconds between passes, 1 to 86400 (one day). A value outside that range is refused by Apply with a message naming the field. Default 10.
|-
| Remote Folder || Destination folder on the server. Must contain <code>remote.safe</code>.
|-
| Temporary File Extension || Files are uploaded under this extension (default <code>.tmp</code>) and renamed on completion, so the remote side never sees a partial file. Files carrying the extension are never selected for transfer.
|-
| Include Sub Folders || Also send files from folders beneath the local folder, recreating the structure on the server. Default off.
|-
| Sync Mode || Copy new or changed files and leave the local files in place. Unticked means move mode. Default off.
|-
| Overwrite Newer || Sync only. Also replace a newer remote file with an older local one. Default on.
|-
| Sync Deletions || Sync only. Also delete remote files which are no longer in the local folder. Default off.
|-
| Sync Folder Deletions || Sync only, needs Include Sub Folders and Sync Deletions. Also remove remote folders which are no longer in the local folder. Default off.
|-
| Stability Check, Seconds, Retries || Only transfer a file once it has stopped changing for the given number of seconds. A file that is still changing after the wait is checked again, up to Retries times, each after another full wait; only then is it skipped until the next poll. Retries 0 restores the single check. Default off, 5 seconds, 5 retries (an installation upgraded from an earlier version gets 5). With the defaults one file that keeps growing can hold a pass for up to six times the stability seconds.
|}

=== sftp_get.xml ===

The download (Get) settings have the same options seen from the other side:

{| class="wikitable"
|-
! Setting !! Description
|-
| Enabled || Whether the Get thread transfers anything.
|-
| Title || Free text, shown in the Get log and emails.
|-
| Remote Folder || Folder on the server polled for incoming files. Must contain <code>remote.safe</code>.
|-
| Remote File Mask || One or more wildcard masks separated by <code>;</code>, matched against the remote listing.
|-
| Local Folder || Folder where downloaded files are saved. Must contain <code>local.safe</code>.
|-
| Poll Frequency || Seconds between passes, 1 to 86400 (one day). A value outside that range is refused by Apply with a message naming the field. Default 10.
|-
| Temporary File Extension || Files are downloaded under this extension and renamed on completion.
|-
| Include Sub Folders || Also fetch files from folders beneath the remote folder.
|-
| Sync Mode || Copy new or changed files and leave the remote files in place. Unticked means move mode (the remote file is deleted after a completed download).
|-
| Overwrite Newer || Sync only. Also replace a newer local file with an older remote one. Default on.
|-
| Sync Deletions || Sync only. Also delete local files which are no longer in the remote folder.
|-
| Sync Folder Deletions || Sync only. Also remove local folders which are no longer in the remote folder.
|-
| Stability Check, Seconds, Retries || Only fetch a file once the remote listing shows it unchanged for the given number of seconds. A file that is still changing is listed again, up to Retries times, each after another full wait, before it is skipped until the next poll. Retries 0 restores the single check. Default off, 5 seconds, 5 retries.
|}

=== jsch_properties.xml ===

Session parameters passed directly to the JSch library: strict host key checking, preferred authentication methods, key exchange, cipher, MAC and host key algorithm lists, compression and proxy settings. Each row can be enabled or disabled and encrypted individually. The shipped defaults suit most servers; change them only when a server insists on a particular algorithm.

=== email_properties.xml ===

Jakarta Mail SMTP properties. Six rows are always present and cannot be removed: <code>mail.smtp.host</code>, <code>mail.smtp.port</code>, <code>mail.smtp.from</code>, <code>mail.smtp.auth</code>, <code>mail.smtp.user</code> and <code>mail.smtp.password</code>; a file that lacks any of them gains the row, disabled and empty, the next time the desktop is opened. The '''Add Property''' button beside Send Test Email offers the usual TLS, SSL, socket factory, timeout, charset and debug properties with suggested values, or any other name typed in; '''Remove Property''' deletes the selected row and refuses the six required ones. The password row is stored encrypted. Rows with Enable unticked are left out of the session. A server that answers <code>530 ... anonymous mail</code> or a similar authentication error usually needs <code>mail.smtp.auth</code> enabled and set to <code>true</code>.

=== email_distribution_properties.xml ===

The three distribution lists. Each has an address list (comma separated), an Enable flag and a Frequency in minutes, see [[#Email Notifications|Email Notifications]].

=== log4j2.xml ===

Log file location, rollover and retention, see [[#Logging|Logging]].

== Safe Files ==

A transfer pass does nothing unless both of these files exist:

{| class="wikitable"
|-
! File !! Where
|-
| <code>local.safe</code> || In the root of the Local Folder (Put and Get each have their own).
|-
| <code>remote.safe</code> || In the root of the Remote Folder on the server.
|}

The files prove that the configured folders are the intended ones and that any network share or mount behind them is actually present. Without them a mistyped path, an unmounted share or an empty folder could otherwise look like "nothing to send" or, with Sync Deletions on, empty the other side. Only the name matters, not the content.

* The Put and Get tabs have Create (tick) and Remove (cross) buttons beside the Local Folder and Remote Folder fields. Create copies the template from the <code>safety</code> folder into the folder typed in the field, after showing the full path and asking for confirmation. The remote buttons open their own SFTP session.
* A missing safe file is logged once as a warning (<code>Nothing sent, safe file not found : ...</code>) and again after Apply or a restart; transfers resume at the next poll once the file appears.
* The safe files are never transferred, deleted or counted, whatever the file mask.
* The remote check lists the remote folder, so the SFTP account must be permitted to list it.
* Create the local file only while any share it lives on is mounted, otherwise the empty mount point is what gets approved.

When upgrading from a version before 6.10, nothing transfers until the safe files have been created. Where the remote server is owned by another party they will need to place <code>remote.safe</code> for you.

== File Masks ==

The Local File Mask (Put) and Remote File Mask (Get) accept the wildcards <code>*</code> and <code>?</code>. Several masks can be given separated by <code>;</code>, for example <code>*.xml;*.csv</code>; spaces around a mask are ignored.

* Put matching is case-insensitive; Get matching follows the server listing and is case-sensitive.
* A blank mask matches nothing on both sides.
* Files carrying the Temporary File Extension are always skipped, even with a mask of <code>*</code>.
* A folder whose name matches the mask is skipped, never transferred or deleted.
* The mask is also the scope of Sync Deletions: only files matching it are deleted from the destination.

== Transfer Behaviour ==

=== Move Mode ===

Move mode is in force when Sync Mode is unticked.

# Each poll collects the files matching the mask (and, with Include Sub Folders, those in folders beneath).
# With Stability Check on, the thread waits until the collection is the configured number of seconds old, then re-checks each file's size and modified time. A file that has changed is waited for again, up to the configured number of Retries (logged as <code>Still changing ... retry n of m</code>); a file that is still changing after the last retry is skipped with a warning and picked up on the next poll.
# Put: the file is copied to the backup folder if backup is on, uploaded under the temporary extension, renamed to its final name, and only then deleted locally. Get: the file is downloaded under the temporary extension, renamed, and only then deleted from the server. A partial transfer is removed and the source is left in place.
# Sub folders are created on the destination as needed. The configured folders themselves are never created or removed, and emptied source sub folders are left in place.
# A file that keeps failing is retried and logged on every poll. There is no error folder.

=== Sync Mode ===

Sync Mode is a one-way mirror from source to destination; the source is never deleted. For each file the destination copy is compared by size and modified time:

{| class="wikitable"
|-
! Destination copy !! Action
|-
| Missing, older, or same time with a different size || Transferred. The modified time is carried across.
|-
| Identical (same size and time) || Skipped silently.
|-
| Newer than the source || Transferred only when Overwrite Newer is ticked. Otherwise kept, logged at Debug level only.
|}

With Include Sub Folders on, empty folders are created on the destination too.

'''Sync Deletions''': at the end of each folder, a destination file is deleted when it matches the mask, does not carry the temporary extension and no file of that name exists in the matching source folder. Folders are never removed by this option, and folders that exist only at the destination are left alone with their contents. Nothing is deleted when a folder cannot be listed or when the pass is interrupted. An empty source folder (with its safe file present) empties the destination of mask-matching files.

'''Sync Folder Deletions''' (needs Include Sub Folders and Sync Deletions): a folder that exists only at the destination has its mask-matching files deleted and is removed once it is empty. A folder still holding a file the mask does not cover is kept with that file. A folder is only judged to be destination-only when nothing of that name exists at the source, including a file or a link.

Each folder is processed in full (transfers, then deletions) before the next one is started, and a log line <code>Folder <path></code> is written before the first action in a folder.

Points to note:

* Do not tick Sync Deletions on both Put and Get against the same pair of folders.
* Sync Folder Deletions treats every folder beneath the destination as in scope. A "processed" folder created on the server by another system, or an archive folder beneath the receive folder, will lose its mask-matching files.
* On a Mac, Finder's <code>.DS_Store</code> file does not match a mask such as <code>*.xml</code>, so a browsed folder is emptied but not removed.
* Backup is for move mode: in Sync Mode the source file is still there, so the backup row is greyed out and no backup copy is taken.

=== Pass Summary ===

Every pass that transferred, failed or skipped at least one file ends with <code>Transfer finished - n sent, n failed, n skipped in n s</code>. A pass that does not run to its end says instead <code>Transfer interrupted by shutdown</code>, <code>Transfer paused from the window</code> or <code>Transfer abandoned, connection lost</code>, followed by the same counts, and the Transfer email for that pass carries an <code>Outcome</code> row saying so and listing the files that did get through; the rest are sent or fetched on the next poll. A pass with nothing to do writes nothing at the Normal log level, so an idle service produces a quiet log.

Each thread disconnects from the server at the end of every pass and reconnects at the start of the next, so a long poll interval never leaves an idle session for a firewall or the server to drop. The log therefore shows Connecting, Connected and Disconnected on every pass, including an idle one.

== Applying Settings to a Running Service ==

A service reads <code>xml/config</code> at start-up and whenever the file <code>xml/config/reload.request</code> appears. The desktop's Apply button writes the settings and then writes that file; a service on the same machine collects it within a second, re-reads the six configuration files, hands the settings to its threads (between passes) and deletes the file. The desktop status line reports whether a service collected the request.

An empty <code>reload.request</code> created by any other means works too, so settings prepared on another machine can be copied into place and activated without restarting the service. If any configuration file fails to parse, the service logs an error, keeps its current settings and drops the request. A stale request found at service start-up is removed.

== Running the Desktop Beside a Service ==

A service holds an operating system lock on <code>xml/config/service.lock</code> for as long as it runs. A desktop window started in the same installation folder detects it within a couple of seconds and:

* shows a banner "A service is running on this machine - transfers and the web log viewer are its job. Apply hands it the new settings.";
* disables its Run button, and if transfers were running from the window, pauses them at the end of the current pass;
* leaves the web log viewer to the service.

When the service stops, the banner clears and the window's Run button and viewer come back. The browse buttons and safe file buttons work regardless, as they open their own short-lived sessions. The lock file is left behind when the service stops; this is normal.

== Web Log Viewer ==

When Web Log Viewer is ticked on the SFTP tab, the program serves its log on <code>http://<host>:<port>/</code> (default port 8080) in both desktop and service mode. The page shows the same merged Put, Get and System log as the desktop, with a Log Level selector (remembered by the browser), System / Put / Get check boxes, the thread states, a text filter, auto-scroll and Clear. It updates live and recovers the backlog after a reconnect.

Read-only endpoints for monitoring tools:

{| class="wikitable"
|-
! URL !! Returns
|-
| <code>/</code> || The log page.
|-
| <code>/api/status</code> || JSON with version, title and the Put and Get thread states.
|-
| <code>/api/log?dest=put|get|sys</code> || JSON backlog for one log, optionally <code>&after=<seq></code>.
|-
| <code>/events</code> || Server-sent event stream of new log lines.
|}

The viewer has no login and listens on every network interface. Log lines include the SFTP host, username and file names, so keep the port on the LAN or behind a firewall. If the port is in use the program logs a warning and carries on transferring; a service retries the port every few seconds.

== Email Notifications ==

Email is off unless Email Notifications is ticked on the SFTP tab and the SMTP properties are filled in on the Email Properties tab. Messages are routed through three distribution lists:

{| class="wikitable"
|-
! List !! Receives !! Shipped default
|-
| '''Monitor''' || Started and Stopped (service start and shutdown, Run and Pause in the desktop) and the Daily Statistics Email (files and bytes sent and received, failures, errors raised and emailed). || Enabled, frequency 0
|-
| '''Error''' || One message per error event: Connection failed, Connection lost, Upload failed, Download failed, Local folder not found, Remote folder could not be listed, Safe file missing, Local delete failed, Remote delete failed, Backup copy failed. Connection failed is sent once per outage, however many polls fail, and is followed by a Connection restored message (with the time the outage started and its length) when the next connection succeeds. || Enabled, frequency 15 minutes
|-
| '''Transfer''' || One message per pass that transferred at least one file, listing the files and sizes (Put Files sent, Get Files received). Passes with nothing to do send nothing; failures go to the Error list. || Disabled, frequency 0
|}

Subjects follow the pattern <code>SFTP Transfer <version> [Put|Get] <Event> for [<title>] on <host></code>. The body is an HTML table of label and value rows (Time, Host, Title, Folder, File, Reason, Files and so on; paths are shown in a fixed-width font) followed by a blank gap so that a corporate disclaimer appended by the mail server sits clear of the detail. The Time row is in UTC. The Frequency of a list suppresses a repeat of the same subject within that many minutes, so a file that fails on every poll produces one email per interval rather than one per poll; a suppressed email is noted in the log. A connection that stays down produces one Connection failed email for the whole outage, whatever the Frequency, and one Connection restored email when the link is back; every failed poll in between is logged as an error with a note that the email has already been sent. Because the Transfer list's subject is the same for every pass, '''its frequency must stay at 0''' or whole passes would be suppressed as repeats.

The Send Test Email button on the Email Properties tab sends a message to a chosen list using the settings on screen and reports the result on the status line, without needing Email Notifications to be ticked.

Each distribution list has an Enable flag and a comma separated address list. An installation upgraded from an earlier version gains the Transfer list, disabled, the first time the desktop is opened.

== Installing as a Windows Service ==

The Windows 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'''. You can specify a different name as an optional second parameter, which allows several instances to run from separate installation folders on the same machine. If a custom name is used at install time, the 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>).

Before installing the service, configure and test with the desktop launcher <code>sftpTransfer.exe</code> (threads start paused) or <code>sftpTransfer_Console.exe</code> (service logic with the log in a console window). Once the service is installed, the desktop can still be opened alongside it to change settings, see [[#Running the Desktop Beside a Service|Running the Desktop Beside a Service]].

== Authentication ==

Authentication is configured once on the SFTP tab and used by both directions:

{| class="wikitable"
|-
! Method !! How to configure
|-
| User password || Authentication Type <code>user password</code>. Enter the SFTP Username and set the SFTP Password with its Assign button.
|-
| User public key || Authentication Type <code>user public key</code>. Point Private Key File and Public Key File at an existing pair, or press Create to generate a pair and then install the public key on the server yourself. If the private key is passphrase protected, set the passphrase with the Private Key Password Assign button.
|}

Host keys are checked against the Known Hosts File. With Add to Known Hosts File ticked (or <code>StrictHostKeyChecking</code> set to <code>no</code> in the jsch properties, as shipped) a new server's key is recorded on first connection.

All SSH is handled by the JSch library with Bouncy Castle as the cryptographic provider.

=== Password Encryption ===

The SFTP password, the private key passphrase, the SMTP password and the settings password are stored encrypted in the XML files. They are set through the desktop window: each password field has an Assign button that opens a dialog, and the encrypted value is written when settings are applied. Plain text passwords are never stored. The encrypted values are specific to SFTPTransfer and cannot be copied from the configuration of other Commander4j programs.

== Thread Architecture ==

{| class="wikitable"
|-
! Thread !! Purpose
|-
| TransferPUT || Polls the local folder and uploads. Opens its own SFTP session for each pass and closes it afterwards.
|-
| TransferGET || Polls the remote folder and downloads. Opens its own SFTP session for each pass and closes it afterwards, so Put and Get can fail and reconnect independently.
|-
| EmailThread || Sends queued emails asynchronously so a slow SMTP server never delays a transfer.
|-
| ArchiveThread || Purges backup copies older than the retention period.
|-
| StatsThread || Sends the Daily Statistics Email at the configured time.
|-
| ReloadWatcher || Service mode only. Watches for <code>reload.request</code>.
|}

In the desktop the window's own browse and safe file buttons use a separate short-lived session.

== Logging ==

Every line shown in the window is also written to <code>logs/sftpTransfer.log</code>, in both desktop and service mode, tagged <code>[PUT]</code>, <code>[GET]</code>, <code>[SYS]</code> or <code>[GUI]</code> (the window's own connections). The log records:

* Service or window start and stop, and the settings loaded or applied
* Connecting, Connected (with the server's SSH banner), Disconnected and Connection lost for each session
* Every command sent to the server (<code>ls</code>, <code>stat</code>, <code>put</code>, <code>get</code>, <code>rename</code>, <code>rm</code>, <code>mkdir</code>, <code>rmdir</code>, <code>setstat</code>), with the full paths on failure
* Folder headings, Sending / Sent, Receiving / Received with sizes and durations, stability retries and skips, sync deletions and the pass summary with its outcome
* Safe file warnings, reload requests, service lock and web viewer events
* Errors and exceptions with their reason

The shipped <code>log4j2.xml</code> rolls the file over at 10 MB or daily, keeps 14 days of compressed archives and logs at <code>debug</code>. The listing of the remote folders on an idle poll is written at <code>trace</code>; set the root level to <code>trace</code> to see it in the file.

== Dependencies ==

{| class="wikitable"
|-
! Library !! Version !! Purpose
|-
| JSch || 2.27.9 || SSH / SFTP client
|-
| Bouncy Castle || 1.86 || Cryptographic provider for JSch
|-
| Apache Commons IO || 2.21.0 || Wildcard file matching
|-
| Jakarta Mail / Angus Mail || 2.1.5 / 2.0.5 || Email notifications
|-
| Log4j || 2.25.5 || Logging
|}

Source code and installers: https://github.com/C4J/sftpTransfer

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

[[Category:Commander4j]]

Modules

2026-10-15T19:26:57Z

Dgarratt: Updated by push_wiki.py

[[Category: Commander4j]]
The modules database is populated automatically when you install or update the application. Unless you want to make changes to reports you would not normally make any changes to it.

[[file:Modules2.png|link=|400px]]

{| class="wikitable" style="margin:auto"
|+ Categories
|-
! Type !! Description
|-

| Forms || Screens within the Desktop Application or page on the Web page of mobile device
|-
| Functions || Used to enable permissions such as Add, Edit, Delete within Forms
|-
| Menus || Defines a Menu which can have Forms or Reports Assigned to it.
|-
| Reports || Can be a regular report which you can view on screen or a Label which is for barcode labels. A Label module carries the printer settings (Group ID, Printer Type, Language, DPI and Direct Print) that decide which [[Label Printers|label printers]] are offered on the label screens. See [[Printer Queues]].
|-
| Executables || Link to External program
|-
| User Report || Used to allow customisation on the reporting and labelling system
|}

Label Printers

2026-10-15T19:26:56Z

Dgarratt: Updated by push_wiki.py

'''Label Printers''' is where an administrator defines the network label printers that Commander4j talks to directly over TCP/IP: Zebra, Printronix, Logopak and Videojet devices. It is found under ''Pallet Transactions › Setup'' and again under ''Tray & Case Labels › Setup''; both entries open the same screen.

A printer defined here appears in the '''device''' drop-down of the label-printing screens, and it can be attached to a production line so that an external labelling program collects the label data. See [[Production Lines & Labellers]].

[[file:LabelPrinters.png|link=|700px]]

== The list ==

Two filters sit above the list. '''Group''' narrows it to printers used for Pack, Pallet or General labels, or shows All. '''Type''' narrows it to one make, or shows every make when left blank.

The columns are Printer ID, Group, Description, Type, Language, DPI, Paper Size, IP Address, Port, Enabled, Direct, Export, Format and Path. A line under the list shows how many printers match the filters.

== Buttons ==

{| class="wikitable"
! Button !! Permission !! What it does
|-
| '''Add''' || FRM_PRINTER_ADD || Asks for a new Printer ID, then for its Group (Pack, Pallet or General), creates the printer and opens its properties. Cancelling the Group prompt abandons the add without a message.
|-
| '''Edit''' || FRM_PRINTER_EDIT || Opens the properties of the highlighted printer. Double-clicking a row does the same.
|-
| '''Delete''' || FRM_PRINTER_DELETE || After a confirmation, deletes the printer and removes it from every production line it was attached to.
|-
| '''Excel''' || || Exports the filtered list to a spreadsheet.
|-
| '''Print''' || || Prints the list as a report.
|-
| '''Help''', '''Close''' || || Opens this page; closes the screen.
|}

== Printer properties ==

{| class="wikitable"
! Field !! Notes
|-
| Printer ID || Read-only once created. Stored in upper case, at most 30 characters.
|-
| Group ID || Pack, Pallet or General. Fixed when the printer is created; to change it, delete the printer and add it again.
|-
| Enabled || Only enabled printers are offered on the label screens.
|-
| Printer Type || Logopak, Printronix, Videojet or Zebra.
|-
| Direct Print || Tick when Commander4j should send the label to the printer's IP address and port itself, with no operating system print queue. Leave clear when an external labelling program prints from the exported data. See [[Printer Queues]] for how this is set up end to end.
|-
| Language || IGP/PGL, LEAP, ZPL or Zipher. Must match what the printer understands.
|-
| DPI || 200 or 300.
|-
| Paper Size || Width by height, for example 100x150. Stored without spaces.
|-
| Description || Free text shown in the list.
|-
| IP Address, Port || Where the printer listens. The defaults are 127.0.0.1 and 9100. Neither value is checked when saved, so a typing mistake only shows up when a label fails to print.
|-
| Data Export || Tick, then enter or browse to the folder where label data files should be written for an external labelling program, and choose the file Format: CSV, LQF or XML. The folder must be reachable by that program.
|}

'''Save''' is only enabled after something has changed. '''Close''' discards unsaved edits without asking.

== How a printer reaches the label screens ==

Each label-printing screen has a device drop-down listing the print queues on the computer plus the printers defined here. A printer is only offered when it is Enabled, set to Direct Print, and its Type, Group, Language and DPI match the settings of that screen's module in [[Modules]]. The operator's choice is remembered per workstation and per screen. If a printer you expect is missing from a screen's list, compare those five settings first.

When no device has been chosen on a screen, the label goes to the computer's default printer; see [[Select Printer]].

== See also ==

* [[Production Lines & Labellers]]
* [[Process Order Assign to Labeller]]
* [[Select Printer]]
* [[Modules]]

[[Category:Commander4j]]

Case Label

2026-10-15T19:26:55Z

Dgarratt: Updated by push_wiki.py

[[Category:Commander4j]]
[[file:Case_Label.png|link=|700px]]

The above screen is used to print Case Labels.
 
There are two methods to print a label depending on the type of printer or labeller that you want to use. They are described on the [[Pallet Label#Switching to a barcode printer|Pallet Label]] page and in plain language on [[Label Layouts]].

{| class="wikitable" style="margin:auto"
|+ Case Label
|-
! Field !! Description
|-

| 1 || Process Order or Works Order Number can be typed in or picked using the lookup button.
|-
| 2 || Process Order Status is shown in RED if the order is closed.
|-
| 3 || Date of Manufacture will default to the computers system clock but you can amend it manually if necessary. The expiry date of the pallet is calculated by adding the shelf life to the date of manufacture.
|-
| 4 || The screen determines what a full pallet quantity would contain by reference to [[Material UOMs]]
|-
| 5 || Expiry Date is calculated by adding the Shelf Life settings found in the [[Materials]] screen to the Date of Manufacture but you can override if necessary.
|-
| 6 || Preview is only applicable for "Standard" reports which are created for any printer. If you change the RPT_PACK_LABEL module to use a Zebra ZPL compatible Label then you won't be able to preview the label on screen.
|-
| 7 || Number of labels.
|-
| 8 || The Label button is used to generate a label and sent it do the printer from the desktop client and is subtly different to the Assign to Labeller button (10) which is used to drive external labelling applications such as the [[AutoLab4j]] application.
|-
| 9 || This is the print queue or printer that you want the label to be sent to when using the Label button (8). Operating system print queues are listed first, followed by any Direct Print printers defined in [[Label Printers]], which are shown with a different icon and send the label straight to the printer's IP address. It is important to understand the difference between the two label printing mechanisms and the print queue requirements. See [[Printer Queues]]
|-
| 10 || See [[Process Order Assign to Labeller]]
|-
| 11 || The structure - content of the [[Batch Number]] gets its default format from the [[System Keys]] screen. However you can override it on the [[Customers]] screen. This allows the content of the label to be different depending on which customer id is assigned to the [[Process Orders]]
|}

[[file: Case_Label_Preview.png|link=|800px]]

The placeholders available on a case label differ slightly from a pallet label; see [[Label Fields#Case and tray labels|Label Fields]].

Pallet Label

2026-10-15T19:26:54Z

Dgarratt: Updated by push_wiki.py

[[Category:Commander4j]]
See also [[Production Declaration]] and [[Production Confirmation]]

[[file:Pallet label2.png|link=|600px]]

The above screen is used to print Pallet Labels (labels which include a unique Serial Shipping Container Code - SSCC). The number sequence used is define in the [[System Keys]] screen.

There are two methods to print a label depending on the type of printer or labeller that you want to use. They are described in the section [[#Switching to a barcode printer|Switching to a barcode printer]] below, and in plain language on [[Label Layouts]].

{| class="wikitable" style="margin:auto"
|+ Pallet Label
|-
! Field !! Description
|-
| 1 || Process Order or Works Order Number can be typed in or picked using the lookup button.
|-
| 2 || Process Order Status is shown in RED if the order is closed.
|-
| 3 || Date of Manufacture will default to the computers system clock but you can amend it manually if necessary. The expiry date of the pallet is calculated by adding the shelf life to the date of manufacture.
|-
| 4 || The screen determines what a full pallet quantity would contain by reference to [[Material UOMs]]
|-
| 5 || Expiry Date is calculated by adding the Shelf Life settings found in the [[Materials]] screen to the Date of Manufacture but you can override if necessary.
|-
| 6 || Preview is only applicable for "Standard" reports which are created for any printer. If you change the PALLET_LABEL module to use a Zebra ZPL compatible Label then you won't be able to preview the label on screen.
|-
| 7 || Number of SSCC's is not necessarily the same as number of labels. Some reports will print labels in pairs so 1 SSCC = 2 labels which have the same SSCC. This is common place as placing a pallet label on 2 difference faces of a pallet makes it more likely that at least one will be visible at all times.
|-
| 8 || The Label button is used to generate a label and sent it do the printer from the desktop client and is subtly different to the Assign to Labeller button (10) which is used to drive external labelling applications such as the [[AutoLab4j]] application.
|-
| 9 || This is the print queue or printer that you want the label to be sent to when using the Label button (8). Operating system print queues are listed first, followed by any Direct Print printers defined in [[Label Printers]], which are shown with a different icon and send the label straight to the printer's IP address. It is important to understand the difference between the two label printing mechanisms and the print queue requirements. See [[Printer Queues]]
|-
| 10 || See [[Process Order Assign to Labeller]]
|-
| 11 || The [[Confirmed Status]] checkbox is important as it triggers the generation of an outbound Production Declaration message. You have 2 options here. If you want to print all your labels in advance you can leave the confirmed checkbox unselected - you can then confirm each pallet using the Production Confirmation transaction on the desktop or scanner. If you want you can confirm as you print. The deciding factory comes back to traceability. If you want the date of manufacture to be accurate you should not confirm the pallet label when it is printed but do it when the pallet is actually ready to have the label applied.
|-
| 12 || The structure - content of the [[Batch Number]] gets its default format from the [[System Keys]] screen. However you can override it on the [[Customers]] screen. This allows the content of the label to be different depending on which customer id is assigned to the [[Process Orders]]
|}

[[file:Pallet_Label_Preview2.png|link=|600px]]

Examples of a pallet labels Zebra XiIII Plus (300dpi) **left** and Intermec IPL (200dpi) **right**

[[file:Zebra_Intermec_Pallet.png|link=|600px]]

== Switching to a barcode printer ==

Labels designed for barcode printers rather than general reports are text templates held in the <code>labels</code> folder. [[Label Layouts]] explains what is on a label and how the templates work, [[Zebra ZPL Label]] shows the standard template, and [[Label Template Syntax]] is the reference.

You should be aware that there are two main methods for the application to send data to a printer which depends on the type of printer or labeller that you want to use.

The default config after installing will be a label which can be sent to any standard desktop printer and has the advantage that when you print the label you have the option of displaying the label on screen.

If you have a Zebra compatible barcode printer you can amend the configuration so that it sends ZPL commands to that printer. This will be faster to print and the quality of the barcode will be better.

The following screens show how to change the report type. To create or change a layout of your own, follow [[Changing a Label]].

[[file:Module_Admin_Menu.png|link=|600px]]

The screens below show how to switch pallet label types and reports. You should note that the Modules database is used to define screens as well as reports. To help reduce the number of items in the list you can filter them using the module type as shown here.

[[file:Module_Admin1.png|link=|600px]]

Select the report called "RPT_PALLET_LABEL" and click on the edit button.

[[file:Module_Pallet_Report1.png|link=|600px]]

[[file:Module_Pallet_Report2.png|link=|600px]]

Label Layouts

2026-10-15T19:26:53Z

Dgarratt: Updated by push_wiki.py

<div style="max-width:900px; padding:0.9em 1.2em; margin:0 0 1em 0; border:1px solid #c8d1e0; border-left:5px solid #1e40c8; border-radius:0 8px 8px 0; background:#f4f6fb;">
'''This page is the starting point for anyone who wants to know what is printed on a Commander4j label, or who needs to change it.''' You do not need to be a programmer to read it. Where a change does need technical help, the page says so.
</div>

== What a pallet label looks like ==

Every pallet that Commander4j records gets a label like the ones below. The left-hand label was printed on a Zebra printer, the right-hand one on an Intermec printer. Both carry the same information in the layout the [https://www.gs1.org/standards/barcodes/sscc GS1] standard expects, so a customer's warehouse can scan it on arrival.

[[file:Zebra_Intermec_Pallet.png|link=|800px]]

{| class="wikitable"
! What you see !! What it means !! Where the value comes from
|-
| '''My Company''' || Your company or customer name. || The [[Customers]] record attached to the process order.
|-
| '''L1''' || Label number. When two labels are printed per pallet the second one says L2. || Counted automatically as labels are printed.
|-
| '''MATERIAL''' || Your product code. || [[Materials]].
|-
| '''Your Label Header Text''' || An optional line of free text, the same on every label. || The '''LABEL_HEADER_COMMENT''' setting in [[System Keys]].
|-
| '''SSCC''' || The 18-digit Serial Shipping Container Code. This number is unique to the pallet and is what the customer scans. || Generated by Commander4j from the number range in [[System Keys]].
|-
| '''CONTENT''' || The GTIN (EAN) of the case or unit on the pallet. || The unit of measure on the [[Materials]] record.
|-
| '''VARIANT''' || Two-digit GS1 variant for the case. || [[Materials]] unit of measure.
|-
| '''COUNT''' || How many cases are on the pallet. || Entered on the [[Pallet Label]] screen, defaulting to a full pallet.
|-
| '''LAYERS''' || How many layers of cases. || Calculated from the pallet quantity and the per-layer unit of measure on the [[Materials]] record.
|-
| '''DESCRIPTION''' || Product description. || [[Materials]].
|-
| '''BATCH/LOT''' || The batch number. || Built from the batch format in [[System Keys]], or overridden on the [[Customers]] record.
|-
| '''BEST BEFORE''' || The expiry date. || Date of manufacture plus the shelf life held on the [[Materials]] record.
|-
| '''Top barcode''' || A GS1-128 barcode containing the content (02), variant (20), best before (15), count (37) and batch (10). || Built from the values above.
|-
| '''Bottom barcode''' || A GS1-128 barcode containing only the SSCC (00). || The pallet number.
|}

Case and tray labels work the same way but carry no SSCC. See [[Case Label]].

== How a label gets from the screen to the printer ==

There are three ways Commander4j can produce a label, and which one you use decides how the label is designed.

{| class="wikitable"
! Route !! Designed with !! Best for !! Preview on screen?
|-
| '''Standard report''' || [https://community.jaspersoft.com/download-jaspersoft/community-edition/ JasperSoft Studio], a free visual report designer. The label is a <code>.jrxml</code> file in the <code>reports</code> folder. || Any printer that has a normal Windows or Mac print queue, including office laser printers. This is how a fresh install is set up. || Yes
|-
| '''Label template''' || A text file in the <code>labels</code> folder, written in the printer's own command language with Commander4j placeholders for the values. || Industrial barcode printers (Zebra, Intermec, Printronix). Faster, and the barcodes are sharper. || No. Use [[ZPLRenderer|ZPL Renderer]] instead.
|-
| '''External labeller''' || [[AutoLab4j]] prints the same template file on an automatic print-and-apply machine on the line. [[LabelServer4j]] drives case and secondary labellers from its own copy of the label files, kept in its own folders. || Lines where the labeller fires itself when a pallet or case is complete. || No
|}

Most sites start with the standard report and move to a label template when they install a barcode printer. The rest of this page is about label templates.

== Which label file is used ==

Commander4j decides which label to print in this order, and the last match wins:

# The '''DEFAULT_PALLET_REPORT''' setting in [[System Keys]] (the module '''RPT_PALLET_LABEL''' after installation). Case labels use '''DEFAULT_PACK_REPORT'''.
# An override on the [[Material Types|Material Type]].
# If the material type has no override, an override on the [[Materials|Material]] itself.
# An override on the [[Customers|Customer]] attached to the process order.

A module record in the [[Modules]] screen links a name such as RPT_PALLET_LABEL to a file, and says whether that file is a standard report or a label template. That is the screen you change when you want Commander4j to use a different label. [[Changing a Label]] walks through it.

== Which printer language do I have? ==

Label templates are written in the language the printer understands. Look at the make of your printer:

{| class="wikitable"
! Printer make !! Language !! Example template on this wiki !! Preview tool
|-
| Zebra || ZPL || [[Zebra ZPL Label]] || [[ZPLRenderer|ZPL Renderer]] or [https://labelary.com/viewer.html Labelary]
|-
| Intermec / Honeywell || IPL || [[Intermec IPL Label]] || none
|-
| Printronix || IGP/PGL || shipped in the <code>labels</code> folder || none
|-
| Logopak || LEAP || usually driven by [[LabelServer4j]] from its own label files; can also be defined as a direct printer in [[Label Printers]] || [[LogoRenderer]]
|-
| Videojet || Zipher || usually driven by [[LabelServer4j]]; can also be defined as a direct printer in [[Label Printers]] || none
|}

If you are buying a printer and have a free choice, Zebra is the easiest to work with because the free ZPL Renderer shows you the label on screen without printing anything.

== How hard is the change you want to make? ==

{| class="wikitable"
! Change !! Difficulty !! What you need !! Start here
|-
| Change a caption, a date format, or the company name. Move a field a little. Make text bigger or smaller. || '''Easy.''' Half an hour with a text editor. || A copy of the existing template and the list of placeholders. || [[Changing a Label]]
|-
| Add a value that is already in Commander4j to the label, for example the customer's part number. || '''Moderate.''' You need to find the right placeholder and a free space on the label. || [[Label Fields]] and a preview tool. || [[Label Fields]], then [[Changing a Label]]
|-
| Change what goes into a barcode, add a new barcode, or design a label from a blank sheet. || '''Technical.''' Needs knowledge of the printer language and of the GS1 barcode rules. || The printer's programming guide and [[Label Template Syntax]]. || [[Label Template Syntax]] and [[Useful Information]]
|}

If you are on a support contract, the technical changes are the kind of thing to ask for. The easy and moderate ones are well within reach of a line supervisor or IT generalist.

== Pages in this section ==

* [[Changing a Label]] – a step-by-step walk-through of copying a template, changing one thing, previewing it and switching Commander4j over to it.
* [[Label Fields]] – every placeholder you can put on a label, with what it prints.
* [[Label Template Syntax]] – how a template file is put together.
* [[Label Function Syntax]] – the functions for formatting dates, padding numbers and trimming text.
* [[Zebra ZPL Label]] – the standard pallet label, explained block by block.
* [[Intermec IPL Label]] – the same label for an Intermec printer.
* [[Label Printers]] – defining network barcode printers.
* [[Printer Queues]] – how a label reaches the printer: through a raw print queue, or by Direct Print to the printer's IP address.
* [[ZPLRenderer|ZPL Renderer]] – see a Zebra label on screen without a printer.

[[Category:Commander4j]]
[[Category:AutoLab4j]]

Installation

2026-10-15T19:26:52Z

Dgarratt: Updated by push_wiki.py

'''Installation''' covers the server-side components that an IT person sets up once the basics are working. For installing the database, the application and the database connection, follow the step-by-step [[Install Guide]] instead.

{| class="wikitable"
! Task !! Page
|-
| Which file to download || [[Downloads]]
|-
| Install SQL Server Express, MySQL, MariaDB or Oracle || [[Install Database]]
|-
| Run the Commander4j installer (Full or Workstation) || [[Install Commander4j]]
|-
| Connect Commander4j to the database and create the tables || [[Setup4j]]
|-
| Log in for the first time || [[First Login]]
|-
| Move to a newer version || [[Upgrading]]
|}

The sections below are only needed for hand-held scanners, ERP interfaces and barcode printers.

== Install Java ==

The Windows and macOS installers include their own copy of Java, so a normal desktop installation needs nothing extra. You only need to install Java 25 yourself in two cases:

* '''The web component''' (the scanner web application) on the server that runs Apache Tomcat. Tomcat itself needs Java to run.
* '''The desktop application on Linux''', because the Linux installer does not bundle Java.

In both cases install the '''JDK''' (not the smaller JRE). The Azul Zulu JDK 25 from [https://www.azul.com/downloads/?package=jdk#zulu https://www.azul.com/downloads/?package=jdk#zulu] is recommended; on Windows choose the <code>.msi</code> installer and tick the option to set <code>JAVA_HOME</code>, which the Tomcat installer looks for.

'''Note that the web application should be installed on a nominated server machine and not on workstations.'''

== Install Tomcat 11.x ==

Apache Tomcat 11 is required for the web component. Download it from the [https://tomcat.apache.org/download-11.cgi Apache Tomcat site]. On Windows choose the '''32-bit/64-bit Windows Service Installer''' so that Tomcat runs as a service and starts with the machine. The installer asks for the Java location: point it at the JDK you installed above.

== Configure Tomcat / Web Application ==

The web component of Commander4j is a single file, '''c4j_commander4j_web.war''', included with every release from version 12.75 onwards (it replaced the three separate web applications of earlier releases, which are listed below for sites that still run them). It contains the scanner pages and the REST API they use.

The servlet (.war) files shown below are intended to work on Zebra Mobile Computers which have the Zebra Enterprise Browser installed.

{| class="wikitable"
! Servlet !! Purpose !! Environment !! Notes
|-
| '''c4j_commander4j_web.war''' || Pallet Transactions, Quality Grading, Issue / Return || Any Mobile Browser || * Recommended from 12.75
|-
| '''c4j_web_react.war''' || Pallet Transactions || Any Mobile Browser || Earlier releases
|-
| '''c4j_web_WS.war''' || Quality — Product Grading || Any Mobile Browser || Earlier releases; only needed for Quality Control
|-
| '''c4j_web_Issue.war''' || Issue Pallets to Order & Location || Tablet Mobile Browser || Earlier releases; Issue/Return of Stock
|}

Installing the web element of Commander4j is straightforward and requires copying files from the Commander4j install directory into the Tomcat directory:

* Stop the Apache Tomcat service if it is running.
* Copy the file '''chosen_servlet.war''' from the Commander4j directory into the WebApps subdirectory of the Tomcat installation directory.
* Start the Apache Tomcat service.
* You should then notice that the '''chosen_servlet''' directory has been created under WebApps.
* Update the list of hosts the web application can connect to by copying "Commander4j/xml/hosts/hosts.xml" into "Tomcat/WebApps/'''chosen_servlet'''/xml/hosts".
* Confirm this is working by opening the URL '''http://servername:8080/chosen_servlet/'''
* If you update the hosts.xml file for a servlet you will need to either restart Apache Tomcat or stop and start the servlet from the [http://localhost:8080/manager/html Apache Tomcat Manager].
* If you want to connect to a SQL Server database using Windows Integrated Authentication, copy the appropriate version of the auth DLL from the downloaded MS JDBC drivers (e.g. mssql-jdbc_auth-12.10.0.x64.dll) into the Java bin folder.

=== Optional: allow other web servers to call the REST API (CORS) ===

The scanner pages and the REST API are served from the same web application, so browsers need no special permission to use them. If pages served from '''another''' web server (a different host name or port) need to call the API from the browser, Tomcat must be told to allow cross-origin requests. Tomcat includes a filter for this. Add the following inside the <code><web-app></code> element of <code>conf\web.xml</code> in the Tomcat installation folder, then restart the Tomcat service:

<pre>
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>*</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.methods</param-name>
<param-value>GET,POST,PUT,DELETE,HEAD,OPTIONS</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.headers</param-name>
<param-value>Content-Type,X-Requested-With,Accept,Authorization,Origin,Access-Control-Request-Method,Access-Control-Request-Headers</param-value>
</init-param>
<init-param>
<param-name>cors.exposed.headers</param-name>
<param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
</pre>

Two things to be aware of. Placing the filter in <code>conf\web.xml</code> applies it to every web application on that Tomcat, including the Tomcat manager, so only do this on a Tomcat dedicated to Commander4j. And because <code>cors.allowed.origins</code> is <code>*</code>, the filter does not pass the login cookie across origins (Tomcat's <code>cors.support.credentials</code> setting stays at its default of <code>false</code>); a page on another server can therefore only call API functions that do not need a logged-in session. To allow a logged-in session from another server, replace <code>*</code> with that server's exact origin, for example <code>http://scanner-pages.example.local:8080</code>, and add an <code>init-param</code> setting <code>cors.support.credentials</code> to <code>true</code>.

== Create Commander4j Services ==

See [[Install_Interface_Services|Install Interface Services]].

== Install Local Middleware ==

The local middleware service handles the processing of inbound and outbound interface files between Commander4j and external systems such as an ERP. It runs as a background service on the Commander4j server machine and is configured via the [[Interface_Admin|Interface Admin]] screen within the application.

To install the interface service:

* Ensure Commander4j has been installed using the '''Full''' install option, which includes the service wrapper components.
* Open Commander4j, navigate to '''System > Interface Admin''' and verify that your interface definitions are configured correctly.
* Use the '''Assign Service''' function within the application to register the interface process as a Windows service (on Windows) or configure it as a startup process on Linux/macOS.
* Once registered, start the service and monitor the [[Interface_Log|Interface Log]] to confirm that messages are being processed correctly.

If you are using [[Middleware4j]] to transform files before they reach Commander4j, install and configure Middleware4j separately — see the [[Middleware4j]] wiki page for details.

== Install Print Queues ==

Commander4j uses two distinct methods for printing, and each requires a different type of print queue to be set up on the workstation or server.

=== Standard Reports (JasperReports) ===

Standard reports — such as pallet summaries, despatch notes and audit reports — are printed using JasperReports and sent to a regular operating system print queue, exactly as you would print a document from a word processor. Any printer visible to the operating system can be used. The report type is configured in the [[Modules|Modules]] screen.

On Windows, ensure the printer is installed and visible in the Windows Printers & Scanners settings. On Linux, CUPS-managed queues are supported.

=== Barcode Labels (ZPL) ===

Barcode labels — pallet labels, case labels and sample labels — are printed by sending raw ZPL (Zebra Printer Language) commands directly to a ZPL compatible printer. This bypasses the normal print driver rendering pipeline entirely, so the label must reach the printer untouched: either through a raw / pass-through print queue, or by '''Direct Print''', where Commander4j sends the label straight to the printer's IP address and port with no operating system queue at all. Direct Print works on every platform and is described on [[Printer Queues]].

* '''Windows''' — install the printer using the [https://www.seagullscientific.com/support/downloads/drivers/ Seagull Scientific Generic Label] driver, or configure a ''Generic / Text Only'' queue. Do not use a standard Zebra Windows driver, as this will re-interpret the ZPL rather than passing it through.
* '''macOS''' — a standard macOS printer queue will not work for ZPL output. On macOS 26 and earlier a raw queue can be created through the CUPS web interface, following the guidance at [https://qz.io/docs/Setting-Up-A-Raw-Printer-in-OSX qz.io]. From macOS 27 (Golden Gate) Apple has disabled the CUPS web interface, so use Direct Print instead.
* '''Linux''' — configure a CUPS raw queue pointing at the printer's IP address and port 9100.

If a label is accidentally sent to a standard print queue rather than a raw queue, the printer will output pages of ZPL text commands instead of a label. This is harmless but confirms the queue type needs to be changed.

To use Direct Print, define the printer in [[Label Printers]] with its IP address and port and '''Direct Print''' ticked, then tick '''Direct Print''' on the label's report module in [[Modules]] and make sure Group ID, Printer Type, Language and DPI agree on both. The printer then appears in the Print Queue drop-down of the label screens. See [[Printer Queues]] for the full walk-through.

See also: [[Zebra_ZPL_Label|Zebra ZPL Label]], [[Intermec_IPL_Label|Intermec IPL Label]], [[Label_Template_Syntax|Label Template Syntax]].

[[Category:Commander4j]]

Printer Queues

2026-10-15T19:26:51Z

Dgarratt: Updated by push_wiki.py

'''Printer Queues''' explains how a Commander4j report or label reaches a printer. There are three routes, and which one you need depends on the kind of output.

{| class="wikitable"
! Output !! Route !! Set up where
|-
| Standard reports (pallet summaries, despatch notes, audit reports) || A regular operating system print queue || The operating system
|-
| Barcode labels sent to a print queue || A '''raw''' (pass-through) print queue || The operating system
|-
| Barcode labels sent straight to the printer || A '''Direct Print''' printer, addressed by IP address and port || Commander4j, in [[Label Printers]] and [[Modules]]
|}

== Standard reports ==

These reports are produced by JasperReports and use regular print queues, exactly as you would for printing spreadsheets or letters. Any printer the operating system can see will do. The report type is defined on the [[Modules]] screen. See [[Pallet Label]] for more information.

== Labels through a raw print queue ==

A label is a special kind of report. Instead of drawing a page, Commander4j sends the printer's own command language, for example ZPL (Zebra Printer Language), and the printer builds the label itself. Those commands must reach the printer untouched, so the print queue has to be a '''raw''' or pass-through queue that does not try to render the data.

* '''Windows''' – use a driver from [https://www.seagullscientific.com/support/downloads/drivers/ Seagull Scientific] or a ''Generic / Text Only'' printer queue. Do not use a standard Zebra Windows driver, as this will re-interpret the ZPL rather than passing it through.
* '''Linux''' – create a CUPS raw queue pointing at the printer's IP address and port 9100.
* '''macOS''' – raw queues used to be created through the CUPS web interface, as described at [https://qz.io/docs/Setting-Up-A-Raw-Printer-in-OSX qz.io]. '''From macOS 27 (Golden Gate) Apple has disabled the CUPS web interface, so a raw queue can no longer be created this way.''' Use a Direct Print printer instead, as described in the next section.

If you send a label to a regular printer queue you will typically see pages of ZPL commands, which look like a list of numbers and letters, instead of a label. This is harmless but confirms the queue type needs to be changed. If you are interested in the ZPL language, perhaps so you can create your own labels, have a look at the [https://labelary.com/viewer.html Labelary] website or the free [[ZPLRenderer|ZPL Renderer]].

== Labels sent directly to the printer ==

Commander4j can also send a label straight to the labeller's IP address and port, with no operating system print queue involved at all. This is called '''Direct Print'''. It works on every platform, it needs no printer driver, and it is the way to print labels on macOS 27 and later.

Direct Print works for pallet labels and for case and tray labels alike. Two things have to be set up: the printer, and the report module that produces the label.

=== Step 1: define the printer ===

Open '''Pallet Transactions › Setup › Label Printers''' (or '''Tray & Case Labels › Setup › Label Printers''', which is the same screen), press '''Add''' and give the printer an ID and a Group. Then fill in its properties:

* '''Group ID''' – Pallet for pallet labels, Pack for case and tray labels.
* '''Printer Type''', '''Language''' and '''DPI''' – the make, command language and resolution of the printer, for example Zebra, ZPL and 300.
* '''IP Address''' and '''Port''' – where the printer listens on the network. Port 9100 is the usual port for Zebra and most other label printers.
* '''Enabled''' – ticked.
* '''Direct Print''' – ticked. This is what tells Commander4j to send the label to the IP address itself.

[[file:Direct_Printer.png|link=|800px]]

The example above defines a printer called PALLET_LAB1, a 300 dpi Zebra at 10.0.0.166 port 9100, in the Pallet group with Direct Print ticked. Every field is described on the [[Label Printers]] page.

=== Step 2: set the report module to match ===

The label itself is produced by a report module: RPT_PALLET_LABEL for pallet labels, RPT_PACK_LABEL for case and tray labels. Open '''Administration › Setup › Modules''', find the module and press '''Edit'''. On the '''Edit the Module Properties''' screen:

* '''Report Type''' must be '''Label'''.
* '''Group ID''', '''Printer Type''', '''Language''' and '''DPI''' must be the same as the printer you defined in step 1.
* '''Direct Print''' must be ticked.
* '''Report Filename''' names the label template in the <code>labels</code> folder, for example <code>zebra_300dpi_pallet_label_a5_npp.lbl</code>.

[[file:Direct_Module.png|link=|800px]]

=== How the two fit together ===

A printer is only offered on a label screen when its settings agree with the module's. Group ID, Printer Type, Language, DPI and Direct Print must all match, the printer must be Enabled, and the module's Report Type must be Label. If any one of these differs the printer silently stays off the list, so this is the first place to look when a printer you expect is missing.

[[file:Direct_Config.png|link=|900px]]

In the picture the Printer Type, Language and DPI of the printer (left, red) must agree with the same three settings on the module (right, red), the Group ID of the printer must agree with the module's Group ID (green), and Direct Print must be ticked on both (blue).

=== What the operator sees ===

On the [[Pallet Label]] and [[Case Label]] screens the '''Print Queue''' drop-down lists the operating system print queues first, each with a queue icon, followed by any Direct Print printers that match the module. A Direct Print printer is shown with a different icon and as its Printer ID and Description, for example ''PALLET_LAB1 - Pallet Labeller 1''.

[[file:Pallet_Print_Direct_Queue.png|link=|700px]]

Choose the Direct Print printer and press '''Label''' as usual. The choice is remembered per workstation and per screen, so operators only pick it once. When a Direct Print printer is chosen, Commander4j writes the finished label to its <code>spool</code> folder and a background sender delivers it to the printer's IP address and port.

To try Direct Print without using label stock, point a printer definition at [[ZPLRenderer|ZPL Renderer]] instead of a real printer. [[Changing a Label]] walks through that from start to finish.

== See also ==

* [[Label Printers]] – every field on the printer screen.
* [[Modules]] – where the report module is edited.
* [[Select Printer]] – choosing the computer's default print queue.
* [[Label Layouts]] – what is on a label and how templates work.
* [[Installation]] – server and workstation set-up, including print queues.

[[Category:Commander4j]]

File:Pallet Print Direct Queue.png

2026-10-15T19:26:50Z

Dgarratt: Pallet Label screen showing a Direct Print printer in the Print Queue list

Pallet Label screen showing a Direct Print printer in the Print Queue list

File:Direct Config.png

2026-10-15T19:26:48Z

Dgarratt: How printer and module settings must match for Direct Print

How printer and module settings must match for Direct Print

File:Direct Module.png

2026-10-15T19:26:47Z

Dgarratt: Module properties for RPT_PALLET_LABEL with Direct Print ticked

Module properties for RPT_PALLET_LABEL with Direct Print ticked

File:Direct Printer.png

2026-10-15T19:26:45Z

Dgarratt: Label Printers screen with Direct Print ticked

Label Printers screen with Direct Print ticked

Changing a Label

2026-10-15T09:40:19Z

Dgarratt: Updated by push_wiki.py

'''Changing a Label''' walks through the smallest useful change to a pallet label: copying the standard Zebra template, altering one thing, telling Commander4j to use it, and checking the result on screen. It takes about half an hour the first time. If you have never seen a label template before, read [[Label Layouts]] first.

The walk-through uses a Zebra printer because the free [[ZPLRenderer|ZPL Renderer]] lets you see the result without printing anything. The steps are the same for other printer makes except that you cannot preview.

== Before you start ==

* You can log in to Commander4j with a user that has access to '''Administration › Setup › Modules''' and '''Pallet Transactions › Setup › Label Printers'''.
* You know where Commander4j is installed. The label templates live in the <code>labels</code> folder underneath it; see [[Folder Structure]].
* You have a plain text editor. Notepad on Windows or TextEdit on a Mac is fine. Do not use Word.
* Install [[ZPLRenderer|ZPL Renderer]] from the [[Downloads]] page on any PC on the same network. The Commander4j PC itself is simplest. It will act as a pretend printer so you can see each change without using label stock.

== Step 1. Copy the standard template ==

In the <code>labels</code> folder find

zebra_300dpi_pallet_label_a5_standard.lbl

and copy it to a new name, for example

zebra_300dpi_pallet_label_mysite.lbl

Always work on a copy. The standard file is replaced when Commander4j is upgraded, and a copy with your own name is left alone.

== Step 2. Make one change ==

Open your copy in the text editor. It is a mixture of three things:

* Lines beginning with <code>/*</code> are comments. They describe the block that follows and are never sent to the printer.
* Zebra commands such as <code>^FO</code> (position) and <code>^A0N,100,100</code> (font and size). Each line draws one thing.
* Placeholders such as <code><nowiki><*DESCRIPTION*></nowiki></code>, which Commander4j swaps for the real value. The full list is on [[Label Fields]].

Here are three safe changes. Pick one.

'''Change a caption.''' Find the line

^FO900,1300^A0N,50,50^CI27^FDBEST BEFORE (MM YYYY)^FS

The text after <code>^FD</code> is what prints. Change it to <code>USE BY (MM YYYY)</code>. Leave everything before <code>^FD</code> alone.

'''Change a date format.''' Find the line

^FO1085,1360^A0N,100,100^CI27^FD<EXPIRYDATE(MM)> <EXPIRYDATE(yyyy)>^FS

and replace the two functions with one: <code><nowiki><EXPIRYDATE(dd/MM/yyyy)></nowiki></code>. The caption above it should then be changed to match. The letters inside the brackets are explained in [[Label Function Syntax]].

'''Make text bigger.''' In <code>^A0N,100,75</code> the two numbers are the height and width of the characters in printer dots. Increase both to make the text larger, and remember that wider text needs more room before it runs into the next field.

Save the file as plain text with the <code>.lbl</code> extension.

Do not open the <code>.lbl</code> file in ZPL Renderer directly. The template contains Commander4j directives and placeholders that a renderer does not understand, so the result would be misleading. The way to check a template is to let Commander4j print it, which is what the next two steps set up.

== Step 3. Tell Commander4j to use your file ==

# Log in to Commander4j and open '''Administration › Setup › Modules'''.
# Set the type filter to '''Reports''' and find '''RPT_PALLET_LABEL'''. Double-click it, or select it and press '''Edit'''.
# Set '''Report Type''' to '''Label'''. This tells Commander4j the file is a printer template rather than a standard report. Print Preview is not available for labels.
# In '''Report Filename''' press the '''...''' button and choose your file from the <code>labels</code> folder.
# Beneath Report Type are the printer settings for the label: '''Group ID''' (Pallet), '''Printer Type''' (Zebra), '''Language''' (ZPL) and '''DPI''' (300), with '''Direct Print''' on the right. These must match the printer you will choose in the next step, otherwise the printer is not offered on the Pallet Label screen.
# Press '''Save'''.

[[file:Module_Pallet_Report2.png|link=|600px]]

If several labels are in use at your site, check [[Label Layouts#Which label file is used|which label file is used]] before editing RPT_PALLET_LABEL, because a material type, material or customer may be pointing at a different module.

== Step 4. Print to ZPL Renderer and review ==

This step uses ZPL Renderer as a pretend printer, so you see the label filled in with a real pallet's values without using any label stock.

# In ZPL Renderer set the DPI to 300 and the label size to match your stock, then press the '''Network''' button. It now listens on port 9100, the same port a real Zebra printer uses.
# In Commander4j open '''Pallet Transactions › Setup › Label Printers''' and press '''Add'''. Give it an ID such as PREVIEW and choose the '''Pallet''' group.
# Set Printer Type to Zebra, Language to ZPL, DPI to 300, a paper size that matches your stock, the IP address of the PC running ZPL Renderer (127.0.0.1 if it is the same PC) and port 9100. Tick '''Enabled''' and '''Direct Print''', then '''Save'''.
# Open the '''Pallet Label''' screen, pick a process order, choose PREVIEW in the device drop-down and press '''Label'''.

The filled-in label appears in ZPL Renderer. Check the position, font size, spelling and the barcode text. To try another change, edit the <code>.lbl</code> file, save it and press '''Label''' again; Commander4j reads the file afresh each time.

If PREVIEW is missing from the drop-down, compare the five settings on the printer with the ones on the module in step 3; they have to agree. See [[Label Printers]].

Note that printing to PREVIEW still creates a pallet record and uses an SSCC number, exactly as a real print would. Use a test process order.

== Step 5. Go live ==

Once you are happy, choose the real printer on the Pallet Label screen instead of PREVIEW. You can leave the PREVIEW printer defined for next time, or untick '''Enabled''' so operators do not pick it by mistake.

Keep a copy of your <code>.lbl</code> file somewhere outside the Commander4j folder. It is the only record of your label design.

== Going further ==

* To add a value that is not on the standard label, find its name on [[Label Fields]], copy an existing text line and change the position and placeholder.
* To change what is encoded in a barcode, read the DEFINE BARCODE section of [[Label Template Syntax]] first. The GS1 rules are strict and a customer's scanner will reject a barcode that breaks them.
* [[Zebra ZPL Label]] explains the standard template block by block.
* The [https://support.zebra.com/cpws/docs/zpl/zpl-zbi2-pm-en.pdf Zebra ZPL Programming Guide] describes every command.

[[Category:Commander4j]]

Changing a Label

2026-10-15T09:36:33Z

Dgarratt: Updated by push_wiki.py

'''Changing a Label''' walks through the smallest useful change to a pallet label: copying the standard Zebra template, altering one thing, checking it on screen, and telling Commander4j to use it. It takes about half an hour the first time. If you have never seen a label template before, read [[Label Layouts]] first.

The walk-through uses a Zebra printer because the free [[ZPLRenderer|ZPL Renderer]] lets you see the result without printing anything. The steps are the same for other printer makes except that you cannot preview.

== Before you start ==

* You can log in to Commander4j with a user that has access to '''Administration › Setup › Modules''' and '''Pallet Transactions › Setup › Label Printers'''.
* You know where Commander4j is installed. The label templates live in the <code>labels</code> folder underneath it; see [[Folder Structure]].
* You have a plain text editor. Notepad on Windows or TextEdit on a Mac is fine. Do not use Word.
* For the preview step, install [[ZPLRenderer|ZPL Renderer]] from the [[Downloads]] page on any PC on the same network. The Commander4j PC itself is simplest.

== Step 1. Copy the standard template ==

In the <code>labels</code> folder find

zebra_300dpi_pallet_label_a5_standard.lbl

and copy it to a new name, for example

zebra_300dpi_pallet_label_mysite.lbl

Always work on a copy. The standard file is replaced when Commander4j is upgraded, and a copy with your own name is left alone.

== Step 2. Make one change ==

Open your copy in the text editor. It is a mixture of three things:

* Lines beginning with <code>/*</code> are comments. They describe the block that follows and are never sent to the printer.
* Zebra commands such as <code>^FO</code> (position) and <code>^A0N,100,100</code> (font and size). Each line draws one thing.
* Placeholders such as <code><nowiki><*DESCRIPTION*></nowiki></code>, which Commander4j swaps for the real value. The full list is on [[Label Fields]].

Here are three safe changes. Pick one.

'''Change a caption.''' Find the line

^FO900,1300^A0N,50,50^CI27^FDBEST BEFORE (MM YYYY)^FS

The text after <code>^FD</code> is what prints. Change it to <code>USE BY (MM YYYY)</code>. Leave everything before <code>^FD</code> alone.

'''Change a date format.''' Find the line

^FO1085,1360^A0N,100,100^CI27^FD<EXPIRYDATE(MM)> <EXPIRYDATE(yyyy)>^FS

and replace the two functions with one: <code><nowiki><EXPIRYDATE(dd/MM/yyyy)></nowiki></code>. The caption above it should then be changed to match. The letters inside the brackets are explained in [[Label Function Syntax]].

'''Make text bigger.''' In <code>^A0N,100,75</code> the two numbers are the height and width of the characters in printer dots. Increase both to make the text larger, and remember that wider text needs more room before it runs into the next field.

Save the file as plain text with the <code>.lbl</code> extension.

== Step 3. Check the layout on screen ==

Open [[ZPLRenderer|ZPL Renderer]], set the DPI to 300 and the label size to match your stock, and open your <code>.lbl</code> file with the '''Open''' button. You will see the label with the placeholder names printed where the values will go, and the barcodes will not be meaningful because they have not yet been filled in. That is expected. This check is for position, font size and spelling only.

Edit the file, save it, and press '''Refresh''' in ZPL Renderer to see the change.

== Step 4. Tell Commander4j to use your file ==

# Log in to Commander4j and open '''Administration › Setup › Modules'''.
# Set the type filter to '''Reports''' and find '''RPT_PALLET_LABEL'''. Double-click it, or select it and press '''Edit'''.
# Set '''Report Type''' to '''Label'''. This tells Commander4j the file is a printer template rather than a standard report. Print Preview is not available for labels.
# In '''Report Filename''' press the '''...''' button and choose your file from the <code>labels</code> folder.
# Beneath Report Type are the printer settings for the label: '''Group ID''' (Pallet), '''Printer Type''' (Zebra), '''Language''' (ZPL) and '''DPI''' (300), with '''Direct Print''' on the right. These must match the printer you will choose in the next step, otherwise the printer is not offered on the Pallet Label screen.
# Press '''Save'''.

[[file:Module_Pallet_Report2.png|link=|600px]]

If several labels are in use at your site, check [[Label Layouts#Which label file is used|which label file is used]] before editing RPT_PALLET_LABEL, because a material type, material or customer may be pointing at a different module.

== Step 5. Print with real data to the screen ==

This step uses ZPL Renderer as a pretend printer, so you see the label filled in with a real pallet's values without using any label stock.

# In ZPL Renderer press the '''Network''' button. It now listens on port 9100, the same port a real Zebra printer uses.
# In Commander4j open '''Pallet Transactions › Setup › Label Printers''' and press '''Add'''. Give it an ID such as PREVIEW and choose the '''Pallet''' group.
# Set Printer Type to Zebra, Language to ZPL, DPI to 300, a paper size that matches your stock, the IP address of the PC running ZPL Renderer (127.0.0.1 if it is the same PC) and port 9100. Tick '''Enabled''' and '''Direct Print''', then '''Save'''.
# Open the '''Pallet Label''' screen, pick a process order, choose PREVIEW in the device drop-down and press '''Label'''.

The filled-in label appears in ZPL Renderer. If PREVIEW is missing from the drop-down, compare the five settings on the printer with the ones on the module in step 4; they have to agree. See [[Label Printers]].

Note that printing to PREVIEW still creates a pallet record and uses an SSCC number, exactly as a real print would. Use a test process order.

== Step 6. Go live ==

Once you are happy, choose the real printer on the Pallet Label screen instead of PREVIEW. You can leave the PREVIEW printer defined for next time, or untick '''Enabled''' so operators do not pick it by mistake.

Keep a copy of your <code>.lbl</code> file somewhere outside the Commander4j folder. It is the only record of your label design.

== Going further ==

* To add a value that is not on the standard label, find its name on [[Label Fields]], copy an existing text line and change the position and placeholder.
* To change what is encoded in a barcode, read the DEFINE BARCODE section of [[Label Template Syntax]] first. The GS1 rules are strict and a customer's scanner will reject a barcode that breaks them.
* [[Zebra ZPL Label]] explains the standard template block by block.
* The [https://support.zebra.com/cpws/docs/zpl/zpl-zbi2-pm-en.pdf Zebra ZPL Programming Guide] describes every command.

[[Category:Commander4j]]

File:Module Pallet Report2.png

2026-10-15T09:36:32Z

Dgarratt: Dgarratt uploaded a new version of File:Module Pallet Report2.png

Label Template Syntax

2026-10-15T09:26:40Z

Dgarratt: Updated by push_wiki.py

'''Label Template Syntax''' describes how a label template file is put together. A template is the file that Commander4j, and [[AutoLab4j]], send to a barcode printer after filling in the values for a pallet or case. If you only want to make a small change to an existing label, [[Changing a Label]] is a gentler starting point; this page is the reference behind it.

== The idea in one paragraph ==

A label template is a plain text file in the <code>labels</code> folder. Most of it is written in the printer's own language, ZPL for Zebra or IPL for Intermec, exactly as you would find in the printer's programming guide. Wherever a value should change from one pallet to the next, the template contains a placeholder instead of a fixed value. When a label is printed, Commander4j reads the template, swaps every placeholder for the real value, works out the barcode code-set switching, and sends the result to the printer as one stream of text. The printer never sees the placeholders.

Two worked examples are on this wiki: [[Zebra ZPL Label]] and [[Intermec IPL Label]].

== What a template contains ==

{| class="wikitable"
! Kind of line !! Looks like !! What happens to it
|-
| Comment || <code>/* Product description */</code> || Any line that starts with <code>/*</code> is dropped before the label is sent. Use comments to label each block. Putting <code>/*</code> at the start of a printer command is a handy way to switch that line off without deleting it.
|-
| Printer command || <code>^FO80,1070^A0N,50,50^FDDESCRIPTION^FS</code> || Sent to the printer unchanged, apart from placeholders and functions inside it.
|-
| Placeholder || <code><nowiki><*DESCRIPTION*></nowiki></code> || Replaced by the value of that field. The available names are listed on [[Label Fields]].
|-
| Function || <code><nowiki><PADLEFT(<*EAN*>,14,0)></nowiki></code> || Formats a value before it is printed. Functions can be nested; the innermost runs first. See [[Label Function Syntax]].
|-
| Directive || <code>DEFINE BARCODE BARCODE2 00<nowiki><*SSCC*></nowiki></code> || An instruction to Commander4j itself. Directives are read and removed; they are never sent to the printer. They are described below.
|}

Blank lines are ignored and leading spaces are trimmed, so the file can be laid out for readability.

== Placeholders ==

A placeholder is a field name between <code><nowiki><*</nowiki></code> and <code><nowiki>*></nowiki></code>:

<*SSCC*> <*QUANTITY*> <*DESCRIPTION*>

Dates and numbers accept a format after a <code>^</code> character:

<*DATE_OF_MANUFACTURE^dd/MM/yyyy*>
<*QUANTITY^000000*>

Without a format a date prints as yyyy-MM-dd and a number is padded to four digits. The format is ignored for text fields.

Three rules worth knowing:

* A placeholder whose name is not available on this screen prints the name followed by '''not found!''' so the mistake is visible on the label.
* Round brackets inside a text value are printed as curly braces, because round brackets have a meaning in function syntax.
* Names defined with DEFINE BARCODE take precedence over database fields of the same name.

== Directives ==

Directives are lines that Commander4j acts on and removes. They are normally placed at the top of the file. A directive must be the first thing on its line.

{| class="wikitable"
! Directive !! Purpose
|-
| <code>DEFINE BARCODE name value</code> || Creates a barcode variable. Explained in detail below.
|-
| <code>DEFINE BARCODE COUNT_MODE ZPL</code> || Tells Commander4j to send the label once and let the printer make the copies. Pair it with <code><nowiki>^PQ<*ZPL_LABEL_COUNT*></nowiki></code> in the template, which prints the number of copies the operator asked for. Without this directive Commander4j sends the whole label once per copy and ZPL_LABEL_COUNT is always 1.
|-
| <code>SUPPRESS EOL</code> || Joins all the lines together with no line endings. Needed by some printer languages.
|-
| <code>SUPPRESS UNICODE</code> || Stops accented and other non-ASCII characters being converted to the <code>_XX</code> hex escape form that Zebra printers read after <code>^FH</code>. Use it only for printers that do not use this escape form.
|-
| <code>SUPPRESS ASCII ENCODE</code> || Normally the control-character names <code><STX></code>, <code><ETX></code>, <code><ESC></code> and so on are translated into the real control characters before the label is sent. With this directive they are sent to the device exactly as written. When writing a template for a non-Zebra printer, copy the directives from the shipped template for that printer make rather than working them out from scratch.
|}

== DEFINE BARCODE in detail ==

This is the part of a template that needs the most care, and it only matters when you are changing what is encoded in a barcode. For a caption or date change you can leave it alone.

DEFINE BARCODE BARCODE1 02<PADLEFT(<*EAN*>,14,0)>20<PADLEFT(<*VARIANT*>,2,0)>15<EXPIRYDATE(yy)><EXPIRYDATE(MM)><EXPIRYDATE(dd)>37<*QUANTITY^0000*>^10<*BATCH_NUMBER*>

This line is used to create a barcode variable. You may wonder why you cannot use the same string to print the label and skip this step. The reason that using the Zebra ZPL language, when encoding in the Code 128 barcode symbology you need to determine what type of data is in the barcode. Numeric data can be compressed when it appears in pairs (even number) of characters. Alphabetic characters have to use a different encoding.

So - the purpose of the DEFINE BARCODE directive it to let Commander4j look at the complete barcode string in advance and insert the appropriate commands to switch Code Sets before the data is sent to the barcode printer.

The Printer Commands which are used to switch between modes are also defined below.

DEFINE BARCODE BARCODE2 00<*SSCC*>

This is another example of a barcode variable.

DEFINE BARCODE FNC1 >8

FNC1 is required only at the end of variable length data section. It is not required as the last character in the bar code.

DEFINE BARCODE CODEA >9

Subset A supports numbers, upper-case letters, and control characters, such as tab and new-line

DEFINE BARCODE CODEB >6

Subset B supports numbers, upper- and lower-case letters and some additional characters.

DEFINE BARCODE CODEC >;

Subset C supports numbers only. It must have an even number of digits.

DEFINE BARCODE END *END*

This is used to indicate the end of the DEFINE section of the label.

Because a DEFINE BARCODE line is split on spaces, the value must not contain a space.

== See also ==

* [[Label Layouts]]
* [[Changing a Label]]
* [[Label Fields]]
* [[Label Function Syntax]]
* [[Zebra ZPL Label]]
* [[Intermec IPL Label]]
* [[Useful Information]]

[[Category:Commander4j]]
[[Category:AutoLab4j]]

Label Layouts

2026-10-15T09:08:29Z

Dgarratt: Updated by push_wiki.py

<div style="max-width:900px; padding:0.9em 1.2em; margin:0 0 1em 0; border:1px solid #c8d1e0; border-left:5px solid #1e40c8; border-radius:0 8px 8px 0; background:#f4f6fb;">
'''This page is the starting point for anyone who wants to know what is printed on a Commander4j label, or who needs to change it.''' You do not need to be a programmer to read it. Where a change does need technical help, the page says so.
</div>

== What a pallet label looks like ==

Every pallet that Commander4j records gets a label like the ones below. The left-hand label was printed on a Zebra printer, the right-hand one on an Intermec printer. Both carry the same information in the layout the [https://www.gs1.org/standards/barcodes/sscc GS1] standard expects, so a customer's warehouse can scan it on arrival.

[[file:Zebra_Intermec_Pallet.png|link=|800px]]

{| class="wikitable"
! What you see !! What it means !! Where the value comes from
|-
| '''My Company''' || Your company or customer name. || The [[Customers]] record attached to the process order.
|-
| '''L1''' || Label number. When two labels are printed per pallet the second one says L2. || Counted automatically as labels are printed.
|-
| '''MATERIAL''' || Your product code. || [[Materials]].
|-
| '''Your Label Header Text''' || An optional line of free text, the same on every label. || The '''LABEL_HEADER_COMMENT''' setting in [[System Keys]].
|-
| '''SSCC''' || The 18-digit Serial Shipping Container Code. This number is unique to the pallet and is what the customer scans. || Generated by Commander4j from the number range in [[System Keys]].
|-
| '''CONTENT''' || The GTIN (EAN) of the case or unit on the pallet. || The unit of measure on the [[Materials]] record.
|-
| '''VARIANT''' || Two-digit GS1 variant for the case. || [[Materials]] unit of measure.
|-
| '''COUNT''' || How many cases are on the pallet. || Entered on the [[Pallet Label]] screen, defaulting to a full pallet.
|-
| '''LAYERS''' || How many layers of cases. || Calculated from the pallet quantity and the per-layer unit of measure on the [[Materials]] record.
|-
| '''DESCRIPTION''' || Product description. || [[Materials]].
|-
| '''BATCH/LOT''' || The batch number. || Built from the batch format in [[System Keys]], or overridden on the [[Customers]] record.
|-
| '''BEST BEFORE''' || The expiry date. || Date of manufacture plus the shelf life held on the [[Materials]] record.
|-
| '''Top barcode''' || A GS1-128 barcode containing the content (02), variant (20), best before (15), count (37) and batch (10). || Built from the values above.
|-
| '''Bottom barcode''' || A GS1-128 barcode containing only the SSCC (00). || The pallet number.
|}

Case and tray labels work the same way but carry no SSCC. See [[Case Label]].

== How a label gets from the screen to the printer ==

There are three ways Commander4j can produce a label, and which one you use decides how the label is designed.

{| class="wikitable"
! Route !! Designed with !! Best for !! Preview on screen?
|-
| '''Standard report''' || [https://community.jaspersoft.com/download-jaspersoft/community-edition/ JasperSoft Studio], a free visual report designer. The label is a <code>.jrxml</code> file in the <code>reports</code> folder. || Any printer that has a normal Windows or Mac print queue, including office laser printers. This is how a fresh install is set up. || Yes
|-
| '''Label template''' || A text file in the <code>labels</code> folder, written in the printer's own command language with Commander4j placeholders for the values. || Industrial barcode printers (Zebra, Intermec, Printronix). Faster, and the barcodes are sharper. || No. Use [[ZPLRenderer|ZPL Renderer]] instead.
|-
| '''External labeller''' || [[AutoLab4j]] prints the same template file on an automatic print-and-apply machine on the line. [[LabelServer4j]] drives case and secondary labellers from its own copy of the label files, kept in its own folders. || Lines where the labeller fires itself when a pallet or case is complete. || No
|}

Most sites start with the standard report and move to a label template when they install a barcode printer. The rest of this page is about label templates.

== Which label file is used ==

Commander4j decides which label to print in this order, and the last match wins:

# The '''DEFAULT_PALLET_REPORT''' setting in [[System Keys]] (the module '''RPT_PALLET_LABEL''' after installation). Case labels use '''DEFAULT_PACK_REPORT'''.
# An override on the [[Material Types|Material Type]].
# If the material type has no override, an override on the [[Materials|Material]] itself.
# An override on the [[Customers|Customer]] attached to the process order.

A module record in the [[Modules]] screen links a name such as RPT_PALLET_LABEL to a file, and says whether that file is a standard report or a label template. That is the screen you change when you want Commander4j to use a different label. [[Changing a Label]] walks through it.

== Which printer language do I have? ==

Label templates are written in the language the printer understands. Look at the make of your printer:

{| class="wikitable"
! Printer make !! Language !! Example template on this wiki !! Preview tool
|-
| Zebra || ZPL || [[Zebra ZPL Label]] || [[ZPLRenderer|ZPL Renderer]] or [https://labelary.com/viewer.html Labelary]
|-
| Intermec / Honeywell || IPL || [[Intermec IPL Label]] || none
|-
| Printronix || IGP/PGL || shipped in the <code>labels</code> folder || none
|-
| Logopak || LEAP || usually driven by [[LabelServer4j]] from its own label files; can also be defined as a direct printer in [[Label Printers]] || [[LogoRenderer]]
|-
| Videojet || Zipher || usually driven by [[LabelServer4j]]; can also be defined as a direct printer in [[Label Printers]] || none
|}

If you are buying a printer and have a free choice, Zebra is the easiest to work with because the free ZPL Renderer shows you the label on screen without printing anything.

== How hard is the change you want to make? ==

{| class="wikitable"
! Change !! Difficulty !! What you need !! Start here
|-
| Change a caption, a date format, or the company name. Move a field a little. Make text bigger or smaller. || '''Easy.''' Half an hour with a text editor. || A copy of the existing template and the list of placeholders. || [[Changing a Label]]
|-
| Add a value that is already in Commander4j to the label, for example the customer's part number. || '''Moderate.''' You need to find the right placeholder and a free space on the label. || [[Label Fields]] and a preview tool. || [[Label Fields]], then [[Changing a Label]]
|-
| Change what goes into a barcode, add a new barcode, or design a label from a blank sheet. || '''Technical.''' Needs knowledge of the printer language and of the GS1 barcode rules. || The printer's programming guide and [[Label Template Syntax]]. || [[Label Template Syntax]] and [[Useful Information]]
|}

If you are on a support contract, the technical changes are the kind of thing to ask for. The easy and moderate ones are well within reach of a line supervisor or IT generalist.

== Pages in this section ==

* [[Changing a Label]] – a step-by-step walk-through of copying a template, changing one thing, previewing it and switching Commander4j over to it.
* [[Label Fields]] – every placeholder you can put on a label, with what it prints.
* [[Label Template Syntax]] – how a template file is put together.
* [[Label Function Syntax]] – the functions for formatting dates, padding numbers and trimming text.
* [[Zebra ZPL Label]] – the standard pallet label, explained block by block.
* [[Intermec IPL Label]] – the same label for an Intermec printer.
* [[Label Printers]] – defining network barcode printers.
* [[Printer Queues]] – why a label template needs a raw print queue.
* [[ZPLRenderer|ZPL Renderer]] – see a Zebra label on screen without a printer.

[[Category:Commander4j]]
[[Category:AutoLab4j]]

Label Fields

2026-10-15T09:08:28Z

Dgarratt: Updated by push_wiki.py

'''Label Fields''' lists every value you can place on a label template. This is the page to open when you want to add something to a label and need to know what it is called.

A value is placed on the label by writing its name between <code><nowiki><*</nowiki></code> and <code><nowiki>*></nowiki></code>. When the label is printed, Commander4j replaces the placeholder with the real value for that pallet or case.

^FD<*DESCRIPTION*>^FS

prints the product description. Names are written in capitals exactly as listed below. See [[Label Template Syntax]] for how a whole template is put together and [[Label Function Syntax]] for ways to format a value before it is printed.

Which names are available depends on which screen prints the label, because each screen reads a different set of data. The tables below are split the same way. If a name is used that is not available, the label prints the name followed by '''not found!''' in its place, so a mistake is visible on paper rather than silent.

== Pallet labels ==

These fields are available on labels printed from the [[Pallet Label]] screen and from the other pallet screens that can print a label: [[Production Declaration]], [[Pallet Issue]], [[Pallet Return]], [[Split Pallet]] and the pallet label re-print dialog. The values are read from the pallet record together with its material, batch and customer.

{| class="wikitable"
! Field !! Type !! What it prints
|-
| SSCC || text || The 18-digit pallet number.
|-
| MATERIAL || text || Product code.
|-
| DESCRIPTION || text || Product description from [[Materials]].
|-
| OLD_MATERIAL || text || The previous product code held on the material, if you use one.
|-
| EAN || text || GTIN of the unit on the pallet. Usually wrapped in PADLEFT to make it 14 digits: <code><nowiki><PADLEFT(<*EAN*>,14,0)></nowiki></code>
|-
| VARIANT || text || GS1 variant of the unit on the pallet, usually padded to 2 digits.
|-
| QUANTITY || number || Number of units on the pallet. Printed as a whole number padded to 4 digits unless a format is given, for example <code><nowiki><*QUANTITY^0*></nowiki></code> for no padding.
|-
| UOM || text || Unit of measure for QUANTITY.
|-
| LAYERS || number || Number of layers on the pallet.
|-
| BATCH_NUMBER || text || Batch or lot number.
|-
| PROCESS_ORDER || text || Process order number.
|-
| REQUIRED_RESOURCE || text || Production line or resource from the process order.
|-
| DATE_OF_MANUFACTURE || date || Date of manufacture. Prefer the [[Label Function Syntax#PRODDATE|PRODDATE]] function, which formats it for you.
|-
| EXPIRY_DATE || date || Expiry date held against the batch. Prefer the [[Label Function Syntax#EXPIRYDATE|EXPIRYDATE]] function, which picks the batch or pallet date according to the '''EXPIRY DATE MODE''' setting.
|-
| SSCC_EXPIRY_DATE || date || Expiry date held against the pallet. Only populated when EXPIRY DATE MODE is SSCC.
|-
| DATE_CREATED || date and time || When the pallet record was created. Prefer the [[Label Function Syntax#DATE_CREATED|DATE_CREATED]] function.
|-
| DATE_UPDATED || date and time || When the pallet record was last changed.
|-
| CREATED_BY_USER_ID, UPDATED_BY_USER_ID || text || Who created or last changed the pallet record.
|-
| CUSTOMER_ID || text || Customer code from the process order.
|-
| CUSTOMER_NAME || text || Customer name from [[Customers]].
|-
| PRINT_ON_LABEL || text || The customer's print-on-label flag from [[Customers]].
|-
| LOCATION_ID || text || Where the pallet currently is.
|-
| STATUS || text || Pallet status.
|-
| CONFIRMED || text || Y once the pallet has been confirmed, otherwise N.
|-
| DESPATCH_NO || text || Despatch number, blank until the pallet is despatched.
|-
| MHN_NUMBER, DECISION || text || Master hold notice number and quality decision, if the pallet is on hold.
|-
| EQUIPMENT_TYPE || text || The pallet or equipment type.
|-
| GROSS_WEIGHT, NET_WEIGHT, WEIGHT_UOM || number, number, text || Weights held on the material record. For the total pallet weight use the [[Label Function Syntax#PALLET_WEIGHT_TEXT|PALLET_WEIGHT_TEXT]] function.
|-
| PART_NO || text || The customer's part number for this material, from [[Customer Data]].
|-
| CASE_CONTENT || text || Free text describing the case contents, from [[Customer Data]].
|-
| ALT_TEXT_1 || text || Spare free text for this material and customer, from [[Customer Data]].
|-
| BASE_EAN, BASE_VARIANT || text || GTIN and variant of the base unit of the material.
|-
| BASE_UOM || text || The base unit of measure.
|-
| BASE_QUANTITY || number || Pallet quantity converted into base units.
|}

== Case and tray labels ==

These fields are available on labels printed from the [[Case Label]] screen. Note that several names differ from the pallet list: the GTIN is '''PROD_EAN''' here rather than EAN, the description is '''MATERIAL_DESCRIPTION''', and there is no SSCC or LAYERS. A pallet template used as a case label prints "not found!" for those.

{| class="wikitable"
! Field !! Type !! What it prints
|-
| UNIQUE_ID || text || Internal identifier for this print request.
|-
| MATERIAL || text || Product code.
|-
| MATERIAL_DESCRIPTION || text || Product description.
|-
| MATERIAL_TYPE || text || Material type code.
|-
| PROD_EAN, PROD_VARIANT || text || GTIN and variant of the unit being labelled.
|-
| PROD_QUANTITY || number || Quantity being labelled.
|-
| PROD_UOM || text || Unit of measure for PROD_QUANTITY.
|-
| BASE_EAN, BASE_VARIANT, BASE_QUANTITY, BASE_UOM || mixed || The same values for the base unit.
|-
| BATCH_NUMBER || text || Batch number as printed.
|-
| BATCH_PREFIX, BATCH_SUFFIX || text || The parts added to the batch number, when used.
|-
| OVERRIDE_BATCH_PREFIX, OVERRIDE_MANUFACTURE_DATE, OVERRIDE_EXPIRY_DATE || text || Y when the operator overrode the default, otherwise N.
|-
| PROCESS_ORDER || text || Process order number.
|-
| REQUIRED_RESOURCE || text || Production line or resource.
|-
| LINE || text || The production line chosen on the screen.
|-
| LOCATION_ID || text || Location from the process order.
|-
| DATE_OF_MANUFACTURE || date || Date of manufacture. Add a format, for example <code><nowiki><*DATE_OF_MANUFACTURE^dd/MM/yyyy*></nowiki></code>.
|-
| EXPIRY_DATE || date || Expiry date. Add a format in the same way.
|-
| EXPIRY_MODE || text || BATCH or SSCC.
|-
| CUSTOMER_ID, CUSTOMER_NAME || text || Customer code and name.
|-
| PART_NO, ALT_TEXT_1 || text || Customer-specific text from [[Customer Data]].
|-
| LABEL_TYPE || text || Pack or Pallet.
|-
| MODULE_ID || text || The report module that produced the label.
|-
| PRINT_DATE || date and time || When the label was requested.
|-
| PRINT_COPIES || number || Number of copies requested.
|-
| PRINT_QUEUE_NAME || text || The queue or printer chosen.
|-
| USER_ID, WORKSTATION_ID || text || Who printed it and from which PC.
|}

Labels printed by the [[Quality Control Sample]] screen use their own, smaller set of fields and are not covered here.

== Fields that are always available ==

These are added by Commander4j for every label template, whichever screen prints it.

{| class="wikitable"
! Field !! What it prints
|-
| LABEL_NO || The copy number, 1 for the first label of a pallet, 2 for the second and so on. The standard label prints it as L1, L2.
|-
| HEADER_COMMENT || The text of the '''LABEL_HEADER_COMMENT''' system key, but only when the header text tick box on the printing screen is ticked. It is ticked by default. Otherwise blank.
|-
| PLANT || The '''PLANT''' system key.
|-
| EXPIRY_DATE_MODE || The '''EXPIRY DATE MODE''' system key, BATCH or SSCC.
|-
| ZPL_LABEL_COUNT || The number of copies requested, for use with the ZPL <code>^PQ</code> command. See the DEFINE BARCODE COUNT_MODE note in [[Label Template Syntax]].
|}

Values that are not fields but are useful on a label, such as the current user, the date and time of printing, and the Commander4j version, come from [[Label Function Syntax|functions]]: <code><nowiki><USERNAME()></nowiki></code>, <code><nowiki><TIMESTAMP(dd/MM/yyyy HH:mm)></nowiki></code> and <code><nowiki><VERSION()></nowiki></code>.

== Formatting a value ==

A format can follow the field name after a <code>^</code> character. It applies to dates, times and numbers only, and is ignored for text.

{| class="wikitable"
! Example !! Prints
|-
| <code><nowiki><*DATE_OF_MANUFACTURE*></nowiki></code> || 2026-03-01 (the default date format is yyyy-MM-dd)
|-
| <code><nowiki><*DATE_OF_MANUFACTURE^dd/MM/yyyy*></nowiki></code> || 01/03/2026
|-
| <code><nowiki><*PRINT_DATE^HH:mm*></nowiki></code> || 16:46
|-
| <code><nowiki><*QUANTITY*></nowiki></code> || 0224 (the default number format is 0000)
|-
| <code><nowiki><*QUANTITY^0*></nowiki></code> || 224
|-
| <code><nowiki><*QUANTITY^000000*></nowiki></code> || 000224
|}

Date formats use the Java pattern letters: dd day, MM month, yy or yyyy year, HH hour, mm minute, ss second. Number formats use 0 for a digit that is always printed and # for a digit that is printed only when needed.

Two things to be aware of:

* Round brackets in a text value are printed as curly braces, so a description of <code>Widget (Blue)</code> appears as <code>Widget {Blue}</code>. This protects the function syntax, which uses round brackets.
* If a date format is invalid the label prints the field name and an error message in place of the date.

== AutoLab4j ==

[[AutoLab4j]] prints the same template files with the same placeholders and the same [[Label Function Syntax|functions]], but it is not connected to the database. Its values come from the dataset CSV file that Commander4j writes when a process order is assigned to a line, and the field names are the column headings of that file. The list is on [[AutoLab4j Dataset CSV]]. The <code>^format</code> suffix described above is not applied by AutoLab4j, so dates and numbers are printed exactly as they appear in the CSV.

[[LabelServer4j]] keeps its own copy of the label files, in its own folders, one set per site. They are not shared with the Commander4j <code>labels</code> folder, so a change made to a Commander4j template has to be repeated in the LabelServer4j copy. Its command scripts can carry the same printer commands, but a value is written as <code>$data_NAME</code>, where NAME is a column of the dataset CSV, and formatted with functions such as <code>SUBSTRING</code>, <code>REPLACE</code> and <code>EXTRACT_DATE</code>. See [[LabelServer4j Operation]] and [[LabelServer4j Dataset CSV]].

== Barcode variables ==

A name defined with '''DEFINE BARCODE''' at the top of the template can also be used as a field. In the standard label, <code><nowiki><*BARCODE1*></nowiki></code> and <code><nowiki><*BARCODE2*></nowiki></code> are the two GS1-128 barcodes with their code-set switching already worked out. This is explained in [[Label Template Syntax]].

== For database administrators ==

The pallet fields are the columns of the database view '''VIEW_PALLET_EXPIRY''' and the case fields are the columns of '''VIEW_LABEL_DATA'''. The columns are the same on MySQL, Microsoft SQL Server and Oracle. A site that needs an extra value on its labels can have these views extended, but the change is overwritten by upgrades, so talk to support first.

== See also ==

* [[Label Layouts]]
* [[Changing a Label]]
* [[Label Template Syntax]]
* [[Label Function Syntax]]

[[Category:Commander4j]]
[[Category:AutoLab4j]]

Template:Commander4j

2026-10-15T09:03:41Z

Dgarratt: Updated by push_wiki.py

<div style="max-width:900px; padding:0.9em 1.2em; margin:0 0 1em 0; border:1px solid #c8d1e0; border-left:5px solid #1e40c8; border-radius:0 8px 8px 0; background:#f4f6fb;">
'''New here?''' Three steps get you from download to logged in: '''[[Downloads]]''' → '''[[Install Guide]]''' → '''[[First Login]]'''. The guide leads with Windows and Microsoft SQL Server Express, the most common setup, and covers macOS, Linux, MySQL and Oracle too. Already running Commander4j? See [[Upgrading]].
</div>
=Getting Started=
*[[Introduction]]
*[[Overview]]
*[[Requirements]]
*[[Downloads]]
*[[Install Guide]]
**[[Install Database]]
**[[Install Commander4j]]
**[[Setup4j|Setup4j (database connection)]]
**[[First Login]]
*[[Installation|Server components (Tomcat, services, printing)]]
*[[Upgrading|Upgrade]]
*[[Starting]]
*[[Logon]]
*[[Navigation]]
*[[Example Screens]]
*[[Getting Started|What to set up first]]
*[[Folder Structure]]
*[[Select Printer|Printer (choosing where labels and reports print)]]
*[[Label Layouts|Labels (what is printed and how to change it)]]
=User Guide=
''Sections follow the application's main menu.''
===Pallet Transactions===
*[[Pallet Label]]
**[[Production Declaration]]
**[[Process Order Assign to Labeller|Assign a process order to a labeller]]
*[[Production Confirmation|Confirm]]
*[[Despatch]]
*[[Pallet Admin|Pallet Info]]
*[[Pallet Issue]]
*[[Pallet Return]]
*[[Split Pallet]]
*[[Pallet History|History]]
*Setup
**[[Journeys]]
**[[Equipment Admin|Equipment]]
**[[Production Lines & Labellers|Production Lines]]
**[[Label Printers]]
===Tray & Case Labels===
*[[Case Label|Case Label Printing]]
*Setup
**[[Production Lines & Labellers|Production Lines]]
**[[Label Printers]]
===Waste===
*[[Waste Recording|Overview]]
*[[Waste Log]]
*[[Waste Reporting]]
**[[Waste Reports Examples]]
*Setup
**[[Waste Transactions|Transactions]]
**[[Waste Containers|Containers]]
**[[Waste Locations|Locations]]
**[[Waste Reporting Groups|Reporting Groups]]
**[[Waste Reporting IDs|Reporting IDs]]
**[[Waste Materials|Materials]]
**[[Waste Types|Types]]
**[[Waste Reasons|Reasons]]
**[[Link Location to Reporting ID|Location Link to Reporting ID]]
**[[Link Reporting ID to Location|Reporting ID Link to Location]]
===Quality Management===
*'''Panel Samples'''
**[[Quality Control Sample|Print Sample Labels]]
**[[Update Samples|Update Sample Results]]
**[[Results Enquiry]]
**[[Edit Sample]]
**[[Panel Results]]
**[[Results Analysis and Reporting|Results Analysis]]
**Setup
***[[Selection Lists]]
***[[Inspections]]
***[[Dictionary]]
*'''Weight Checks'''
**[[Weight Checks Module|Overview]]
**[[Weight Checks Data Capture|Weight Checks]]
**[[Weight Check Reports|Weight Report]]
**Setup
***[[Sample Point Admin|Sample Points]]
***[[Scale Admin|Scales]]
***[[Workstation Admin|Workstations]]
***[[Tolerable Negative Errors]]
***[[Product Groups]]
***[[Container Codes]]
*'''Sorting'''
**[[Pallet Samples & Faults]]
**[[Pallet Samples Enquiries & Reports|Enquiries & Reports]]
**Setup
***[[Pallet Sample Defect Types|Defect Types]]
***[[Pallet Sample Defect IDs|Defect IDs]]
***[[Sample Point Admin|Sample Points]]
***[[Pallet Sample Reasons|Sample Reasons]]
***[[Pallet Sample Shift Names|Shift Names]]
***[[Pallet Sample Packing Lines|Packing Lines]]
***[[Pallet Sample Supplier Admin|Suppliers]]
***[[Pallet Sample Operatives|Operatives]]
*'''Master Holds'''
**[[Isolate]]
**Setup
***[[Quality Control Decisions|Decisions]]
***[[Quality Control Reasons|Reasons]]
===Master Data===
*[[Customers]]
**[[Customer Data]]
*[[Locations]]
*[[Materials]]
*[[Material Locations]]
*[[Material Types]]
*[[Units of Measure|Units]]
*[[Material Batches|Batches]]
*[[Required Resources|Resources]]
*[[Process Orders|Orders]]
**[[Process Order Barcode]]
*[[Bill of Materials]]
**[[View / Edit]]
**[[Enquiries]]
**Setup
***[[Defaults]]
***[[Elements]]
***[[Structure]]
***[[Lists]]
===Administration===
*'''Customise Application'''
**[[Customising|Overview]]
**[[Menu Maintenance]]
**[[Toolbar Maintenance]]
**[[Scanner Menu Maintenance|RF Menu Maintenance]]
*'''Permissions'''
**[[Permissions|How permissions work]]
**[[Users]]
**[[Groups]]
**[[Audit Reports|Audit Log]]
*'''Setup'''
**[[System Keys|Settings]]
**[[Modules]]
**[[Language & Translations|Translations]]
**[[Email Settings]]
*'''Interfaces'''
**[[Interface Admin]]
**[[Process Messages]]
**[[Interface Log]]
**[[Request Queue]]
**[[Interface Service]]
**[[Install Interface Services]]
**[[Interface Message Formats]]
**[[Interface Example Data Flow 1]]
**[[Interface Example Data Flow 2]]
*'''Tools'''
**[[Report Admin|User Reports]]
***[[Report Properties]]
***[[Schema Browser]]
**[[Standard Reports]]
**[[Automatic Data Archiving|Archive Admin]]
**[[Clone4j]]
===Scanner web application===
*[[Web Applications Overview]]
*[[Quality Panel Web Interface]]
===Reference===
*'''Barcode labels'''
**[[Label Layouts|Overview]]
**[[Changing a Label]]
**[[Label Fields]]
**[[Label Template Syntax]]
**[[Label Function Syntax]]
**[[Zebra ZPL Label]]
**[[Intermec IPL Label]]
**[[Printer Queues]]
**[[Useful Information]]
*[[Database Schema used by Panel Samples]]

[[Category:Commander4j]]

Template:Menu Applications

2026-10-15T09:03:40Z

Dgarratt: Updated by push_wiki.py

<div style="max-width:980px; margin:0 auto 1.2em auto; padding:1.1em 1.4em; border:1px solid #c8d1e0; border-radius:10px; background:#f4f6fb;">
Commander4j and its companion applications '''bridge the gap between your ERP system and factory-floor labelling.'''

Orders and materials come down from the ERP. Operators print GS1 / SSCC pallet and case labels and record what was made. Production and despatch data go back up. Because Commander4j keeps its own database, labelling carries on when the link to head office is down and catches up when it returns.

'''New here?''' Start with the [[Install Guide]] and you will be logged in within the hour. Everything is free and open source (GPL v3).
</div>

<div class="c4j-fluid" style="max-width:980px; margin:0 auto;">
[[File:Commander4j_How_It_Fits.png|980px|center|link=]]
</div>

=Start here=
{| cellpadding="10" style="width:100%; max-width:980px; margin:0 auto; text-align:center; border-spacing:12px; table-layout:fixed;"
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | '''1. Download''' Which installer file to pick for your PC. [[Downloads|Downloads page]]
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | '''2. Install''' Database, installer and Setup4j, step by step. [[Install Guide|Install Guide]]
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | '''3. First login''' Default user, then set up your first materials and orders. [[First Login|First Login]]
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | '''Already installed?''' Upgrading to a newer version. [[Upgrading|Upgrading]]
|-
| colspan="4" style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | '''What is on a label, and how do I change it?''' Start with [[Label Layouts]] for a plain-language tour of the pallet label, then [[Changing a Label]] to make your first change in half an hour.
|}

=The core suite=
{| cellpadding="10" style="width:100%; max-width:980px; margin:0 auto; text-align:center; border-spacing:12px; table-layout:fixed;"
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:Commander4j_256x256.png|link=[[Commander4j]]|100px]] '''[[Commander4j]]''' Production recording, pallet and case labelling, despatch, quality, waste and weight checks. The core application.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:Middleware4j_256x256.png|link=[[Middleware4j]]|100px]] '''[[Middleware4j]]''' Converts and routes files between your ERP and Commander4j (CSV, XML, IDOC, fixed width).
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:LabelServer4j_256x256.png|link=[[LabelServer4j]]|100px]] '''[[LabelServer4j]]''' Background service that sends label data to case and secondary labellers.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:AutoLab4j_256x256.png|link=[[AutoLab4j]]|100px]] '''[[AutoLab4j]]''' Automatic pallet labelling triggered by the production line (MODBUS).
|}

=Tools and utilities=
{| cellpadding="10" style="width:100%; max-width:980px; margin:0 auto; text-align:center; border-spacing:12px; table-layout:fixed;"
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:ZPLRenderer_256x256.png|link=[[ZPLRenderer]]|100px]] '''[[ZPLRenderer]]''' Renders Zebra ZPL label commands on screen, from a file or over the network. Emulates a printer for testing.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:LogoRenderer_256x256.png|link=[[LogoRenderer]]|100px]] '''[[LogoRenderer]]''' Renders Logopak label templates and emulates a Logopak labeller's TCP protocol for local testing.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:LogoClient_256x256.png|link=[[LogoClient]]|100px]] '''[[LogoClient]]''' Companion to LogoRenderer for developing and testing solutions that talk to Logopak labellers.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:SocketTest_256x256.png|link=[[SocketTest]]|100px]] '''[[SocketTest]]''' Emulate a TCP/IP client or server to test printers, labellers and other network devices.
|-
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:Modbus_256x256.png|link=[[ModbusBridge]]|100px]] '''[[ModbusBridge]]''' Relays values between a Modbus client and server, bridging communication between Modbus devices.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:Modbus_256x256.png|link=[[ModbusClient]]|100px]] '''[[ModbusClient]]''' Connect to a Modbus server, then view and change register and coil values.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:Modbus_256x256.png|link=[[ModbusServer]]|100px]] '''[[ModbusServer]]''' Run a Modbus server on your PC to simulate line equipment, then view and change its values.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:sftpTransfer_256x256.png|link=[[SFTPTransfer]]|100px]] '''[[SFTPTransfer]]''' Moves files automatically between a local folder and a remote SFTP server in both directions.
|-
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:SFTGet4j_256x256.png|link=[[SFTPGet]]|100px]] '''[[SFTPGet]]''' Watches a remote SFTP folder and moves each file that appears to a local folder.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:SFTPSend4j_256x256.png|link=[[SFTPSend]]|100px]] '''[[SFTPSend]]''' Watches a local folder and moves each file that appears to a remote SFTP folder.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:XMLViewer_256x256.png|link=[[XMLViewer]]|100px]] '''[[XMLViewer]]''' A simple viewer for XML documents, handy for checking interface messages.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:Menu4j_256x256.png|link=[[Menu4j]]|100px]] '''[[Menu4j]]''' Tree-based menu for organising and launching applications and command-line scripts from a single XML file.
|-
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:TreeDoc_256x256.png|link=[[TreeDoc]]|100px]] '''[[TreeDoc]]''' Creates plain-text documents that describe a folder structure.
| style="border:1px solid #c8d1e0; border-radius:10px; background:#fff; vertical-align:top;" | [[File:LaunchPad_256x256.png|link=[[LaunchPad]]|100px]] '''[[LaunchPad]]''' A replacement for the Launchpad application that Apple removed in macOS 26.
|
|
|}

Case Label

2026-10-15T09:03:39Z

Dgarratt: Updated by push_wiki.py

[[Category:Commander4j]]
[[file:Case_Label.png|link=|700px]]

The above screen is used to print Case Labels.
 
There are two methods to print a label depending on the type of printer or labeller that you want to use. They are described on the [[Pallet Label#Switching to a barcode printer|Pallet Label]] page and in plain language on [[Label Layouts]].

{| class="wikitable" style="margin:auto"
|+ Case Label
|-
! Field !! Description
|-

| 1 || Process Order or Works Order Number can be typed in or picked using the lookup button.
|-
| 2 || Process Order Status is shown in RED if the order is closed.
|-
| 3 || Date of Manufacture will default to the computers system clock but you can amend it manually if necessary. The expiry date of the pallet is calculated by adding the shelf life to the date of manufacture.
|-
| 4 || The screen determines what a full pallet quantity would contain by reference to [[Material UOMs]]
|-
| 5 || Expiry Date is calculated by adding the Shelf Life settings found in the [[Materials]] screen to the Date of Manufacture but you can override if necessary.
|-
| 6 || Preview is only applicable for "Standard" reports which are created for any printer. If you change the RPT_PACK_LABEL module to use a Zebra ZPL compatible Label then you won't be able to preview the label on screen.
|-
| 7 || Number of labels.
|-
| 8 || The Label button is used to generate a label and sent it do the printer from the desktop client and is subtly different to the Assign to Labeller button (10) which is used to drive external labelling applications such as the [[AutoLab4j]] application.
|-
| 9 || This is the name of the print queue that you want the label to be sent to when using the Label button (8). It is important to understand the difference between the type types of label printing mechanisms and the print queue requirements. See [[Printer Queues]]
|-
| 10 || See [[Process Order Assign to Labeller]]
|-
| 11 || The structure - content of the [[Batch Number]] gets its default format from the [[System Keys]] screen. However you can override it on the [[Customers]] screen. This allows the content of the label to be different depending on which customer id is assigned to the [[Process Orders]]
|}

[[file: Case_Label_Preview.png|link=|800px]]

The placeholders available on a case label differ slightly from a pallet label; see [[Label Fields#Case and tray labels|Label Fields]].

Pallet Label

2026-10-15T09:03:38Z

Dgarratt: Updated by push_wiki.py

[[Category:Commander4j]]
See also [[Production Declaration]] and [[Production Confirmation]]

[[file:Pallet label2.png|link=|600px]]

The above screen is used to print Pallet Labels (labels which include a unique Serial Shipping Container Code - SSCC). The number sequence used is define in the [[System Keys]] screen.

There are two methods to print a label depending on the type of printer or labeller that you want to use. They are described in the section [[#Switching to a barcode printer|Switching to a barcode printer]] below, and in plain language on [[Label Layouts]].

{| class="wikitable" style="margin:auto"
|+ Pallet Label
|-
! Field !! Description
|-
| 1 || Process Order or Works Order Number can be typed in or picked using the lookup button.
|-
| 2 || Process Order Status is shown in RED if the order is closed.
|-
| 3 || Date of Manufacture will default to the computers system clock but you can amend it manually if necessary. The expiry date of the pallet is calculated by adding the shelf life to the date of manufacture.
|-
| 4 || The screen determines what a full pallet quantity would contain by reference to [[Material UOMs]]
|-
| 5 || Expiry Date is calculated by adding the Shelf Life settings found in the [[Materials]] screen to the Date of Manufacture but you can override if necessary.
|-
| 6 || Preview is only applicable for "Standard" reports which are created for any printer. If you change the PALLET_LABEL module to use a Zebra ZPL compatible Label then you won't be able to preview the label on screen.
|-
| 7 || Number of SSCC's is not necessarily the same as number of labels. Some reports will print labels in pairs so 1 SSCC = 2 labels which have the same SSCC. This is common place as placing a pallet label on 2 difference faces of a pallet makes it more likely that at least one will be visible at all times.
|-
| 8 || The Label button is used to generate a label and sent it do the printer from the desktop client and is subtly different to the Assign to Labeller button (10) which is used to drive external labelling applications such as the [[AutoLab4j]] application.
|-
| 9 || This is the name of the print queue that you want the label to be sent to when using the Label button (8). It is important to understand the difference between the type types of label printing mechanisms and the print queue requirements. See [[Printer Queues]]
|-
| 10 || See [[Process Order Assign to Labeller]]
|-
| 11 || The [[Confirmed Status]] checkbox is important as it triggers the generation of an outbound Production Declaration message. You have 2 options here. If you want to print all your labels in advance you can leave the confirmed checkbox unselected - you can then confirm each pallet using the Production Confirmation transaction on the desktop or scanner. If you want you can confirm as you print. The deciding factory comes back to traceability. If you want the date of manufacture to be accurate you should not confirm the pallet label when it is printed but do it when the pallet is actually ready to have the label applied.
|-
| 12 || The structure - content of the [[Batch Number]] gets its default format from the [[System Keys]] screen. However you can override it on the [[Customers]] screen. This allows the content of the label to be different depending on which customer id is assigned to the [[Process Orders]]
|}

[[file:Pallet_Label_Preview2.png|link=|600px]]

Examples of a pallet labels Zebra XiIII Plus (300dpi) **left** and Intermec IPL (200dpi) **right**

[[file:Zebra_Intermec_Pallet.png|link=|600px]]

== Switching to a barcode printer ==

Labels designed for barcode printers rather than general reports are text templates held in the <code>labels</code> folder. [[Label Layouts]] explains what is on a label and how the templates work, [[Zebra ZPL Label]] shows the standard template, and [[Label Template Syntax]] is the reference.

You should be aware that there are two main methods for the application to send data to a printer which depends on the type of printer or labeller that you want to use.

The default config after installing will be a label which can be sent to any standard desktop printer and has the advantage that when you print the label you have the option of displaying the label on screen.

If you have a Zebra compatible barcode printer you can amend the configuration so that it sends ZPL commands to that printer. This will be faster to print and the quality of the barcode will be better.

The following screens show how to change the report type. To create or change a layout of your own, follow [[Changing a Label]].

[[file:Module_Admin_Menu.png|link=|600px]]

The screens below show how to switch pallet label types and reports. You should note that the Modules database is used to define screens as well as reports. To help reduce the number of items in the list you can filter them using the module type as shown here.

[[file:Module_Admin1.png|link=|600px]]

Select the report called "RPT_PALLET_LABEL" and click on the edit button.

[[file:Module_Pallet_Report1.png|link=|600px]]

[[file:Module_Pallet_Report2.png|link=|600px]]

Zebra ZPL Label

2026-10-15T09:03:37Z

Dgarratt: Updated by push_wiki.py

'''Zebra ZPL Label''' is the standard pallet label that ships with Commander4j, shown first as it prints and then as the template that produces it. The template is the file <code>zebra_300dpi_pallet_label_a5_standard.lbl</code> in the <code>labels</code> folder. If you want to change it, [[Changing a Label]] takes you through the steps; this page explains what each block does.

The label on the left below was printed from this template on a 300 dpi Zebra printer. The one on the right is the [[Intermec IPL Label|Intermec equivalent]].

[[file:Zebra_Intermec_Pallet.png|link=|800px]]

== The template block by block ==

The template is divided into blocks by comment lines (<code>/* ... */</code>). The table follows the file from top to bottom. Positions are in printer dots from the top-left corner; at 300 dpi there are about 12 dots to a millimetre.

{| class="wikitable"
! Block !! What it prints !! Notes for anyone editing it
|-
| DEFINE BARCODE lines || Nothing directly. They build the two barcode values and declare the code-set switching characters. || Leave alone unless you are changing what the barcodes contain. Explained in [[Label Template Syntax]].
|-
| Label initialisation || <code>^XA</code> starts the label, <code>^LT0060</code> shifts the whole label down slightly, <code>^PW1800</code> sets the print width to 1800 dots (6 inches at 300 dpi). || Change <code>^PW</code> if your label stock is a different width.
|-
| Heading || The customer name top left (<code><nowiki><*CUSTOMER_NAME*></nowiki></code>) and the label number top right (L1, L2). || To print a fixed company name instead, replace the placeholder with the text.
|-
| Product codes || The caption MATERIAL and the product code underneath. || The caption is plain text after <code>^FD</code> and can be changed to anything.
|-
| MAFF statement || The optional header text (<code><nowiki><*HEADER_COMMENT*></nowiki></code>) from the LABEL_HEADER_COMMENT system key. || Blank if the header text box on the screen is unticked.
|-
| Printed by || "Commander4j" and the version number in small type. || Can be removed.
|-
| Horizontal bar and sight lines || A rule across the label with short vertical marks at each end. This block repeats between sections. || <code>^GB</code> draws boxes and lines. The last number is the line thickness.
|-
| Pallet number SSCC || The caption SSCC and the 18-digit number in large type, split into four groups with SUBSTRING so it is easy to read. || The groups are 3, 5, 5 and 5 digits. Keep them if your customers read the number by eye.
|-
| Content, EAN, variant, quantity and layers || Four captions and the GTIN (padded to 14 digits), variant, case count and layer count. || A line that starts with <code>/*</code> inside this block is a disabled command, kept for reference.
|-
| Product description || The caption DESCRIPTION and the description text. || Long descriptions can run off the label. Reduce the font width (the second number after <code>^A0N,</code>) if they do.
|-
| Batch and best before || Captions BATCH/LOT and BEST BEFORE (MM YYYY), then the batch number and the expiry month and year. || The expiry format is set by the EXPIRYDATE function. <code><nowiki><EXPIRYDATE(dd/MM/yyyy)></nowiki></code> prints a full date.
|-
| Top barcode || The GS1-128 barcode for content, variant, best before, count and batch, with the human-readable text underneath in brackets. || <code>^BCN,350</code> sets the barcode height to 350 dots. The text line underneath must match what is in the barcode.
|-
| Bottom barcode || The GS1-128 barcode for the SSCC alone, with (00) and the number underneath. || This is the barcode most customers scan. Do not reduce its size without checking with them.
|-
| End of label || <code>^XZ</code> ends the label. The lines after it are part of the original design and print nothing. || Leave as is.
|}

== The complete template ==

In the code below you will find a mix of standard Zebra ZPL printer commands and Commander4j specific instructions, plus some comments. For information on the ZPL commands see the [[Useful Information]] page. The Commander4j instructions are described in [[Label Template Syntax]] and the placeholders in [[Label Fields]].

Pallet Label - Zebra - ZPL - 300dpi

DEFINE BARCODE BARCODE1 02<PADLEFT(<*EAN*>,14,0)>20<PADLEFT(<*VARIANT*>,2,0)>15<EXPIRYDATE(yy)><EXPIRYDATE(MM)> <EXPIRYDATE(dd)>37<*QUANTITY^0000*>^10<*BATCH_NUMBER*>
DEFINE BARCODE BARCODE2 00<*SSCC*>
DEFINE BARCODE FNC1 >8
DEFINE BARCODE CODEA >9
DEFINE BARCODE CODEB >6
DEFINE BARCODE CODEC >;
DEFINE BARCODE END *END*

/* Label initialisation /*

^XA^LT0060^XZ^XA
^PW1800
/* =====================================LABEL 1=========================================================================== */

/* Heading for Label 1 */

^FO60,0002^A0N,120,110^CI27^FH^FD<*CUSTOMER_NAME*>^FS

^FO1625,0002^A0N,120,110^CI27^FDL<*LABEL_NO*>^FS

/* CS3 and SAP Product Codes */

^FO80,0190^A0N,50,50^CI27^FDMATERIAL^FS

^FO80,0250^A0N,100,100^CI27^FD<*MATERIAL*>^FS

/* MAFF Statement */

^FO0080,0370^A0N,50,50^CI27^FH^FD<*HEADER_COMMENT*>^FS

/* Printed by xxxxxxxxxxxxxxxx * /

^FO1400,0400^A0N,30,30^CI27^FDCommander4j <VERSION()>^FS

/* Horizontal Bar and Sight Lines */

^FO25,0420^GB0,80,9^FS
^FO1770,0420^GB0,80,9^FS
^FO55,0450^GB1690,0,6^FS

/* Pallet Number SSCC */

^FO80,0490^A0N,50,50^CI27^FDSSCC^FS
^FO080,0550^A0N,240,160^CI27^FD<SUBSTRING(<*SSCC*>,1,3)>^FS
^FO390,0550^A0N,240,160^CI27^FD<SUBSTRING(<*SSCC*>,4,5)>^FS
^FO850,0550^A0N,240,160^CI27^FD<SUBSTRING(<*SSCC*>,9,5)>^FS
^FO1300,0550^A0N,240,160^CI27^FD<SUBSTRING(<*SSCC*>,14,5)>^FS

/* Horizontal Bar and Sight Lines */

^FO25,0760^GB0,80,9^FS
^FO1770,0760^GB0,80,9^FS
^FO55,0790^GB1690,0,6^FS

/* Content EAN Variant Quantity & Layers*/

^FO80,0830^A0N,50,50^CI27^FDCONTENT^FS
^FO830,0830^A0N,50,50^CI27^FDVARIANT^FS
^FO1100,0830^A0N,50,50^CI27^FDCOUNT^FS
^FO1450,0830^A0N,50,50^CI27^FDLAYERS^FS

^FO80,0890^A0N,100,100^CI27^FD<PADLEFT(<*EAN*>,14,0)>^FS

/* ^FO830,0890^A0N,100,100^CI27^FD/^FS
^FO830,0890^A0N,100,100^CI27^FD<PADLEFT(<*VARIANT*>,2,0)>^FS
^FO1100,0890^A0N,100,100^CI27^FD<*QUANTITY*>^FS
^FO1450,0890^A0N,100,100^CI27^FD<*LAYERS*>^FS

/* Product Description */

^FO80,1070^A0N,50,50^CI27^FDDESCRIPTION^FS
^FO080,1130^A0N,100,75^CI27^FH^FD<*DESCRIPTION*>^FS

/* Horizontal Bar and Sight Lines */

^FO25,1220^GB0,80,9^FS
^FO1770,1220^GB0,80,9^FS
^FO55,1250^GB1690,0,6^FS

/* Batch (Works Order) and Best Before End Date */

^FO200,1300^A0N,50,50^CI27^FDBATCH/LOT^FS

^FO900,1300^A0N,50,50^CI27^FDBEST BEFORE (MM YYYY)^FS

^FO200,1360^A0N,100,100^CI27^FD<*BATCH_NUMBER*>^FS
^FO1085,1360^A0N,100,100^CI27^FD<EXPIRYDATE(MM)> <EXPIRYDATE(yyyy)>^FS

/* Horizontal Bar and Sight Lines */

^FO25,1450^GB0,80,9^FS
^FO1770,1450^GB0,80,9^FS
^FO55,1480^GB1690,0,6^FS

/* Top Barcode */

^BY5,3.0^FO100,1533^BCN,350,N,N,Y,N^FR^FD<*BARCODE1*>^FS
^FO150,1886^A0N,56,52^CI27^FR^FD(02)<PADLEFT(<*EAN*>,14,0)>(20)<PADLEFT(<*VARIANT*>,2,0)>(15)<EXPIRYDATE(yy)> <EXPIRYDATE(MM)><EXPIRYDATE(dd)>(37)<*QUANTITY*>(10)<*BATCH_NUMBER*>^FS

/* Bottom Barcode */

^BY9,3.0^FO175,1990^BCN,380,N,N,Y,N^FR^FD<*BARCODE2*>^FS
^FO600,2373^A0N,56,52^CI27^FR^FD(00)<*SSCC*>^FS

/* Horizontal Bar and Sight Lines */

^FO25,2420^GB0,80,9^FS
^FO1770,2420^GB0,80,9^FS
^FO55,2450^GB1690,0,6^FS

^XZ

/* End of Label */

^XA^LT0060^XZ^XA

/* End of Label */

== See also ==

* [[Label Layouts]]
* [[Changing a Label]]
* [[Label Fields]]
* [[Label Template Syntax]]
* [[Intermec IPL Label]]
* [[ZPLRenderer|ZPL Renderer]]

[[Category:Commander4j]]
[[Category:LabelServer4j]]
[[Category:AutoLab4j]]

Label Function Syntax

2026-10-15T09:03:36Z

Dgarratt: Updated by push_wiki.py

'''Label Function Syntax''' is the reference for the functions that can be used inside a label template to format a value before it is printed: trimming text, padding numbers with zeros, and printing dates in the format a customer asks for. The same functions work in Commander4j and [[AutoLab4j]].

If you are new to label templates, start with [[Label Layouts]]. The names of the values you can format are listed on [[Label Fields]], and [[Label Template Syntax]] explains how a template file is put together.

There are a number of functions which you can embed in your barcode label template to help format the data before sending to a labeller.

Referencing field names uses this syntax.

<*fieldname*>

for example

<*SSCC*> <*QUANTITY*> <*DESCRIPTION*>

Functions are resolved innermost-first, so they can be nested. The result of an inner function is passed as the input to the function which encloses it.

<PADLEFT(<SUBSTRING(<*BATCH*>,1,3)>,5,0)>

If a function is given the wrong number of parameters it returns the function name followed by '''[Incorrect number of parameters]''', and a function given an invalid date/time format returns the function name followed by '''[Incorrect date/time format]'''. This makes mistakes visible on the printed label rather than failing silently.

===DATE_CREATED===

This function returns the date & time when the pallet record was created in the database and allows you to specify the format that you want it formatted in the label.

Example usage

<DATE_CREATED(ddMMyy)>
<DATE_CREATED(dd/MM/yyyy)>

If the value of the DATE_CREATED field is null or blank it will return spaces instead of date.

===DATETIME===

The function allows you to format a datetime/timestamp field value from the database and display it in the label using the format specified.

<DATETIME(fieldname,dd/MM/yyyy HH:mm:ss)>

===EXPIRYDATE===

When a label is printed Commander4j will automatically calculate the expiry date of the product. It is important to realise however that the application has 2 modes for recording the expiry date. It can be associated with the individual pallet number (SSCC) or it can be associated with the batch number. The mode that the system is using is defined in [[System Keys]] using the setting called '''EXPIRY DATE MODE'''

This function will retrieve the value from the appropriate table based on the setting above.

<EXPIRYDATE(MM yyyy)>
<EXPIRYDATE(MM)>
<EXPIRYDATE(yy)>
<EXPIRYDATE(dd)> <EXPIRYDATE(MM)> <EXPIRYDATE(yyyy)>

===IIF===

<IIF(param1,param2,param3,param4)>

IF param1 = param2 then
return param3
else
return param4

===JULIAN_YJJJ===

This function returns the production / manufacturing data in the format {last digit of year}{Julian day number}

<JULIAN_YJJJ()>

===LEFT===

<LEFT(fieldname,5)>

===LOWERCASE===

<LOWERCASE(fieldname)>

===LTRIM===

<LTRIM(fieldname)>

===PADLEFT===

<PADLEFT(fieldname,14,0)>

This function pads out the size of a string to the length specified using the character specified.

It adds any additional characters to the left size of the string.

===PADRIGHT===

<PADRIGHT(fieldname,14,0)>

This function pads out the size of a string to the length specified using the character specified.

It adds any additional characters to the right size of the string.

===PALLET_WEIGHT_BARCODE===

<PALLET_WEIGHT_BARCODE(KG,3)>

This function returns the total weight of the pallet (looked up from the pallet's SSCC) formatted to the number of decimal places specified, but with the decimal point '''removed''' so that the value can be embedded directly in a barcode.

The first parameter is the unit of measure for the weight; if it is left blank it defaults to '''KG'''. The second parameter is the number of decimal places.

For example a weight of 123.456 KG would produce '''123456'''

<PALLET_WEIGHT_BARCODE(KG,3)>

See also [[#PALLET_WEIGHT_TEXT|PALLET_WEIGHT_TEXT]], which is identical but keeps the decimal point for human-readable display.

===PALLET_WEIGHT_TEXT===

<PALLET_WEIGHT_TEXT(KG,3)>

This function returns the total weight of the pallet (looked up from the pallet's SSCC) formatted to the number of decimal places specified, for display as human-readable text on the label.

The first parameter is the unit of measure for the weight; if it is left blank it defaults to '''KG'''. The second parameter is the number of decimal places.

For example a weight of 123.456 KG would produce '''123.456'''

<PALLET_WEIGHT_TEXT(KG,3)>

This is the same as [[#PALLET_WEIGHT_BARCODE|PALLET_WEIGHT_BARCODE]] except that the decimal point is retained.

===PRODDATE===

This function returns the production / date of manufacture of the pallet and allows you to specify the format that you want it displayed in on the label.

<PRODDATE(dd/MM/yyyy)>
<PRODDATE(ddMMyy)>

If the format is left blank it defaults to '''dd/MM/yyyy'''. If the date of manufacture is null it returns spaces of the same length as the format specified instead of a date.

===RIGHT===

<RIGHT(fieldname,5)>

===RTRIM===

<RTRIM(fieldname)>

===SUBSTRING===

<SUBSTRING(fieldname,start,length)>

This function returns part of a string. '''start''' is the position of the first character to extract (the first character is position 1) and '''length''' is the number of characters to return.

<SUBSTRING(fieldname,1,3)>

would return the first 3 characters of the field. The function is bounds-safe; if the input is shorter than requested it returns as many characters as are available rather than producing an error.

===SUBTR_LPAD===

<SUBTR_LPAD(fieldname,start,length,size,padchar)>

This function first left-pads the input value out to '''size''' characters using '''padchar''', and then returns a substring of the padded value starting at position '''start''' (the first character is position 1) for '''length''' characters.

For example, if a field contains '''12''':

<SUBTR_LPAD(fieldname,1,4,4,0)>

would first pad the value to '''0012''' and then return the first 4 characters '''0012'''.

===TIMESTAMP===

This function returns the current system date & time at the moment the label is printed, formatted using the format specified.

<TIMESTAMP(dd/MM/yyyy HH:mm:ss)>
<TIMESTAMP(ddMMyy)>

If the format is left blank it defaults to '''dd/MM/yyyy HH:mm:ss'''.

===TRIM===

<TRIM(fieldname)>

===UPPERCASE===

<UPPERCASE(fieldname)>

===USERNAME===

This function returns the name of the user currently logged on to Commander4j, in upper case.

<USERNAME()>

===VERSION===

This function returns the version number of the Commander4j application.

<VERSION()>

== See also ==

* [[Label Layouts]]
* [[Label Fields]]
* [[Label Template Syntax]]
* [[Changing a Label]]

[[Category:Commander4j]]
[[Category:AutoLab4j]]

Label Template Syntax

2026-10-15T09:03:35Z

Dgarratt: Updated by push_wiki.py

'''Label Template Syntax''' describes how a label template file is put together. A template is the file that Commander4j, and [[AutoLab4j]], send to a barcode printer after filling in the values for a pallet or case. If you only want to make a small change to an existing label, [[Changing a Label]] is a gentler starting point; this page is the reference behind it.

== The idea in one paragraph ==

A label template is a plain text file in the <code>labels</code> folder. Most of it is written in the printer's own language, ZPL for Zebra or IPL for Intermec, exactly as you would find in the printer's programming guide. Wherever a value should change from one pallet to the next, the template contains a placeholder instead of a fixed value. When a label is printed, Commander4j reads the template, swaps every placeholder for the real value, works out the barcode code-set switching, and sends the result to the printer as one stream of text. The printer never sees the placeholders.

Two worked examples are on this wiki: [[Zebra ZPL Label]] and [[Intermec IPL Label]].

== What a template contains ==

{| class="wikitable"
! Kind of line !! Looks like !! What happens to it
|-
| Comment || <code>/* Product description */</code> || Any line that starts with <code>/*</code> is dropped before the label is sent. Use comments to label each block. Putting <code>/*</code> at the start of a printer command is a handy way to switch that line off without deleting it.
|-
| Printer command || <code>^FO80,1070^A0N,50,50^FDDESCRIPTION^FS</code> || Sent to the printer unchanged, apart from placeholders and functions inside it.
|-
| Placeholder || <code><nowiki><*DESCRIPTION*></nowiki></code> || Replaced by the value of that field. The available names are listed on [[Label Fields]].
|-
| Function || <code><nowiki><PADLEFT(<*EAN*>,14,0)></nowiki></code> || Formats a value before it is printed. Functions can be nested; the innermost runs first. See [[Label Function Syntax]].
|-
| Directive || <code>DEFINE BARCODE BARCODE2 00<nowiki><*SSCC*></nowiki></code> || An instruction to Commander4j itself. Directives are read and removed; they are never sent to the printer. They are described below.
|}

Blank lines are ignored and leading spaces are trimmed, so the file can be laid out for readability.

== Placeholders ==

A placeholder is a field name between <code><nowiki><*</nowiki></code> and <code><nowiki>*></nowiki></code>:

<*SSCC*> <*QUANTITY*> <*DESCRIPTION*>

Dates and numbers accept a format after a <code>^</code> character:

<*DATE_OF_MANUFACTURE^dd/MM/yyyy*>
<*QUANTITY^000000*>

Without a format a date prints as yyyy-MM-dd and a number is padded to four digits. The format is ignored for text fields.

Three rules worth knowing:

* A placeholder whose name is not available on this screen prints the name followed by '''not found!''' so the mistake is visible on the label.
* Round brackets inside a text value are printed as curly braces, because round brackets have a meaning in function syntax.
* Names defined with DEFINE BARCODE take precedence over database fields of the same name.

== Directives ==

Directives are lines that Commander4j acts on and removes. They are normally placed at the top of the file. A directive must be the first thing on its line.

{| class="wikitable"
! Directive !! Purpose
|-
| <code>DEFINE BARCODE name value</code> || Creates a barcode variable. Explained in detail below.
|-
| <code>DEFINE BARCODE COUNT_MODE ZPL</code> || Tells Commander4j to send the label once and let the printer make the copies. Pair it with <code><nowiki>^PQ<*ZPL_LABEL_COUNT*></nowiki></code> in the template, which prints the number of copies the operator asked for. Without this directive Commander4j sends the whole label once per copy and ZPL_LABEL_COUNT is always 1.
|-
| <code>SUPPRESS EOL</code> || Joins all the lines together with no line endings. Needed by some printer languages.
|-
| <code>SUPPRESS UNICODE</code> || Stops accented and other non-ASCII characters being converted to the <code>_XX</code> hex escape form that Zebra printers read after <code>^FH</code>. Use it only for printers that do not use this escape form.
|-
| <code>SUPPRESS ASCII ENCODE</code> || Switches off the conversion of control-character names such as <code><STX></code> and <code><ETX></code> into the real control characters before the label is sent. The shipped Intermec templates start with this line. When writing a template for a non-Zebra printer, copy the directives from the shipped template for that printer make rather than working them out from scratch.
|}

== DEFINE BARCODE in detail ==

This is the part of a template that needs the most care, and it only matters when you are changing what is encoded in a barcode. For a caption or date change you can leave it alone.

DEFINE BARCODE BARCODE1 02<PADLEFT(<*EAN*>,14,0)>20<PADLEFT(<*VARIANT*>,2,0)>15<EXPIRYDATE(yy)><EXPIRYDATE(MM)><EXPIRYDATE(dd)>37<*QUANTITY^0000*>^10<*BATCH_NUMBER*>

This line is used to create a barcode variable. You may wonder why you cannot use the same string to print the label and skip this step. The reason that using the Zebra ZPL language, when encoding in the Code 128 barcode symbology you need to determine what type of data is in the barcode. Numeric data can be compressed when it appears in pairs (even number) of characters. Alphabetic characters have to use a different encoding.

So - the purpose of the DEFINE BARCODE directive it to let Commander4j look at the complete barcode string in advance and insert the appropriate commands to switch Code Sets before the data is sent to the barcode printer.

The Printer Commands which are used to switch between modes are also defined below.

DEFINE BARCODE BARCODE2 00<*SSCC*>

This is another example of a barcode variable.

DEFINE BARCODE FNC1 >8

FNC1 is required only at the end of variable length data section. It is not required as the last character in the bar code.

DEFINE BARCODE CODEA >9

Subset A supports numbers, upper-case letters, and control characters, such as tab and new-line

DEFINE BARCODE CODEB >6

Subset B supports numbers, upper- and lower-case letters and some additional characters.

DEFINE BARCODE CODEC >;

Subset C supports numbers only. It must have an even number of digits.

DEFINE BARCODE END *END*

This is used to indicate the end of the DEFINE section of the label.

Because a DEFINE BARCODE line is split on spaces, the value must not contain a space.

== See also ==

* [[Label Layouts]]
* [[Changing a Label]]
* [[Label Fields]]
* [[Label Function Syntax]]
* [[Zebra ZPL Label]]
* [[Intermec IPL Label]]
* [[Useful Information]]

[[Category:Commander4j]]
[[Category:AutoLab4j]]

Changing a Label

2026-10-15T09:03:34Z

Dgarratt: Updated by push_wiki.py

'''Changing a Label''' walks through the smallest useful change to a pallet label: copying the standard Zebra template, altering one thing, checking it on screen, and telling Commander4j to use it. It takes about half an hour the first time. If you have never seen a label template before, read [[Label Layouts]] first.

The walk-through uses a Zebra printer because the free [[ZPLRenderer|ZPL Renderer]] lets you see the result without printing anything. The steps are the same for other printer makes except that you cannot preview.

== Before you start ==

* You can log in to Commander4j with a user that has access to '''Administration › Setup › Modules''' and '''Pallet Transactions › Setup › Label Printers'''.
* You know where Commander4j is installed. The label templates live in the <code>labels</code> folder underneath it; see [[Folder Structure]].
* You have a plain text editor. Notepad on Windows or TextEdit on a Mac is fine. Do not use Word.
* For the preview step, install [[ZPLRenderer|ZPL Renderer]] from the [[Downloads]] page on any PC on the same network. The Commander4j PC itself is simplest.

== Step 1. Copy the standard template ==

In the <code>labels</code> folder find

zebra_300dpi_pallet_label_a5_standard.lbl

and copy it to a new name, for example

zebra_300dpi_pallet_label_mysite.lbl

Always work on a copy. The standard file is replaced when Commander4j is upgraded, and a copy with your own name is left alone.

== Step 2. Make one change ==

Open your copy in the text editor. It is a mixture of three things:

* Lines beginning with <code>/*</code> are comments. They describe the block that follows and are never sent to the printer.
* Zebra commands such as <code>^FO</code> (position) and <code>^A0N,100,100</code> (font and size). Each line draws one thing.
* Placeholders such as <code><nowiki><*DESCRIPTION*></nowiki></code>, which Commander4j swaps for the real value. The full list is on [[Label Fields]].

Here are three safe changes. Pick one.

'''Change a caption.''' Find the line

^FO900,1300^A0N,50,50^CI27^FDBEST BEFORE (MM YYYY)^FS

The text after <code>^FD</code> is what prints. Change it to <code>USE BY (MM YYYY)</code>. Leave everything before <code>^FD</code> alone.

'''Change a date format.''' Find the line

^FO1085,1360^A0N,100,100^CI27^FD<EXPIRYDATE(MM)> <EXPIRYDATE(yyyy)>^FS

and replace the two functions with one: <code><nowiki><EXPIRYDATE(dd/MM/yyyy)></nowiki></code>. The caption above it should then be changed to match. The letters inside the brackets are explained in [[Label Function Syntax]].

'''Make text bigger.''' In <code>^A0N,100,75</code> the two numbers are the height and width of the characters in printer dots. Increase both to make the text larger, and remember that wider text needs more room before it runs into the next field.

Save the file as plain text with the <code>.lbl</code> extension.

== Step 3. Check the layout on screen ==

Open [[ZPLRenderer|ZPL Renderer]], set the DPI to 300 and the label size to match your stock, and open your <code>.lbl</code> file with the '''Open''' button. You will see the label with the placeholder names printed where the values will go, and the barcodes will not be meaningful because they have not yet been filled in. That is expected. This check is for position, font size and spelling only.

Edit the file, save it, and press '''Refresh''' in ZPL Renderer to see the change.

== Step 4. Tell Commander4j to use your file ==

# Log in to Commander4j and open '''Administration › Setup › Modules'''.
# Set the type filter to '''Reports''' and find '''RPT_PALLET_LABEL'''. Double-click it, or select it and press '''Edit'''.
# Set '''Report Type''' to '''Label'''. This tells Commander4j the file is a printer template rather than a standard report. Print Preview is not available for labels.
# In '''Report Filename''' press the '''...''' button and choose your file from the <code>labels</code> folder.
# The lower part of the screen holds the printer settings for the label: '''Group ID''' (Pallet), '''Printer Type''' (Zebra), '''Language''' (ZPL), '''DPI''' (300) and '''Direct Print'''. These must match the printer you will choose in the next step, otherwise the printer is not offered on the Pallet Label screen.
# Press '''Save'''.

If several labels are in use at your site, check [[Label Layouts#Which label file is used|which label file is used]] before editing RPT_PALLET_LABEL, because a material type, material or customer may be pointing at a different module.

== Step 5. Print with real data to the screen ==

This step uses ZPL Renderer as a pretend printer, so you see the label filled in with a real pallet's values without using any label stock.

# In ZPL Renderer press the '''Network''' button. It now listens on port 9100, the same port a real Zebra printer uses.
# In Commander4j open '''Pallet Transactions › Setup › Label Printers''' and press '''Add'''. Give it an ID such as PREVIEW and choose the '''Pallet''' group.
# Set Printer Type to Zebra, Language to ZPL, DPI to 300, a paper size that matches your stock, the IP address of the PC running ZPL Renderer (127.0.0.1 if it is the same PC) and port 9100. Tick '''Enabled''' and '''Direct Print''', then '''Save'''.
# Open the '''Pallet Label''' screen, pick a process order, choose PREVIEW in the device drop-down and press '''Label'''.

The filled-in label appears in ZPL Renderer. If PREVIEW is missing from the drop-down, compare the five settings on the printer with the ones on the module in step 4; they have to agree. See [[Label Printers]].

Note that printing to PREVIEW still creates a pallet record and uses an SSCC number, exactly as a real print would. Use a test process order.

== Step 6. Go live ==

Once you are happy, choose the real printer on the Pallet Label screen instead of PREVIEW. You can leave the PREVIEW printer defined for next time, or untick '''Enabled''' so operators do not pick it by mistake.

Keep a copy of your <code>.lbl</code> file somewhere outside the Commander4j folder. It is the only record of your label design.

== Going further ==

* To add a value that is not on the standard label, find its name on [[Label Fields]], copy an existing text line and change the position and placeholder.
* To change what is encoded in a barcode, read the DEFINE BARCODE section of [[Label Template Syntax]] first. The GS1 rules are strict and a customer's scanner will reject a barcode that breaks them.
* [[Zebra ZPL Label]] explains the standard template block by block.
* The [https://support.zebra.com/cpws/docs/zpl/zpl-zbi2-pm-en.pdf Zebra ZPL Programming Guide] describes every command.

[[Category:Commander4j]]

Label Fields

2026-10-15T09:03:33Z

Dgarratt: Updated by push_wiki.py

'''Label Fields''' lists every value you can place on a label template. This is the page to open when you want to add something to a label and need to know what it is called.

A value is placed on the label by writing its name between <code><nowiki><*</nowiki></code> and <code><nowiki>*></nowiki></code>. When the label is printed, Commander4j replaces the placeholder with the real value for that pallet or case.

^FD<*DESCRIPTION*>^FS

prints the product description. Names are written in capitals exactly as listed below. See [[Label Template Syntax]] for how a whole template is put together and [[Label Function Syntax]] for ways to format a value before it is printed.

Which names are available depends on which screen prints the label, because each screen reads a different set of data. The tables below are split the same way. If a name is used that is not available, the label prints the name followed by '''not found!''' in its place, so a mistake is visible on paper rather than silent.

== Pallet labels ==

These fields are available on labels printed from the [[Pallet Label]] screen and from the other pallet screens that can print a label: [[Production Declaration]], [[Pallet Issue]], [[Pallet Return]], [[Split Pallet]] and the pallet label re-print dialog. The values are read from the pallet record together with its material, batch and customer.

{| class="wikitable"
! Field !! Type !! What it prints
|-
| SSCC || text || The 18-digit pallet number.
|-
| MATERIAL || text || Product code.
|-
| DESCRIPTION || text || Product description from [[Materials]].
|-
| OLD_MATERIAL || text || The previous product code held on the material, if you use one.
|-
| EAN || text || GTIN of the unit on the pallet. Usually wrapped in PADLEFT to make it 14 digits: <code><nowiki><PADLEFT(<*EAN*>,14,0)></nowiki></code>
|-
| VARIANT || text || GS1 variant of the unit on the pallet, usually padded to 2 digits.
|-
| QUANTITY || number || Number of units on the pallet. Printed as a whole number padded to 4 digits unless a format is given, for example <code><nowiki><*QUANTITY^0*></nowiki></code> for no padding.
|-
| UOM || text || Unit of measure for QUANTITY.
|-
| LAYERS || number || Number of layers on the pallet.
|-
| BATCH_NUMBER || text || Batch or lot number.
|-
| PROCESS_ORDER || text || Process order number.
|-
| REQUIRED_RESOURCE || text || Production line or resource from the process order.
|-
| DATE_OF_MANUFACTURE || date || Date of manufacture. Prefer the [[Label Function Syntax#PRODDATE|PRODDATE]] function, which formats it for you.
|-
| EXPIRY_DATE || date || Expiry date held against the batch. Prefer the [[Label Function Syntax#EXPIRYDATE|EXPIRYDATE]] function, which picks the batch or pallet date according to the '''EXPIRY DATE MODE''' setting.
|-
| SSCC_EXPIRY_DATE || date || Expiry date held against the pallet. Only populated when EXPIRY DATE MODE is SSCC.
|-
| DATE_CREATED || date and time || When the pallet record was created. Prefer the [[Label Function Syntax#DATE_CREATED|DATE_CREATED]] function.
|-
| DATE_UPDATED || date and time || When the pallet record was last changed.
|-
| CREATED_BY_USER_ID, UPDATED_BY_USER_ID || text || Who created or last changed the pallet record.
|-
| CUSTOMER_ID || text || Customer code from the process order.
|-
| CUSTOMER_NAME || text || Customer name from [[Customers]].
|-
| PRINT_ON_LABEL || text || The customer's print-on-label flag from [[Customers]].
|-
| LOCATION_ID || text || Where the pallet currently is.
|-
| STATUS || text || Pallet status.
|-
| CONFIRMED || text || Y once the pallet has been confirmed, otherwise N.
|-
| DESPATCH_NO || text || Despatch number, blank until the pallet is despatched.
|-
| MHN_NUMBER, DECISION || text || Master hold notice number and quality decision, if the pallet is on hold.
|-
| EQUIPMENT_TYPE || text || The pallet or equipment type.
|-
| GROSS_WEIGHT, NET_WEIGHT, WEIGHT_UOM || number, number, text || Weights held on the material record. For the total pallet weight use the [[Label Function Syntax#PALLET_WEIGHT_TEXT|PALLET_WEIGHT_TEXT]] function.
|-
| PART_NO || text || The customer's part number for this material, from [[Customer Data]].
|-
| CASE_CONTENT || text || Free text describing the case contents, from [[Customer Data]].
|-
| ALT_TEXT_1 || text || Spare free text for this material and customer, from [[Customer Data]].
|-
| BASE_EAN, BASE_VARIANT || text || GTIN and variant of the base unit of the material.
|-
| BASE_UOM || text || The base unit of measure.
|-
| BASE_QUANTITY || number || Pallet quantity converted into base units.
|}

== Case and tray labels ==

These fields are available on labels printed from the [[Case Label]] screen. Note that several names differ from the pallet list: the GTIN is '''PROD_EAN''' here rather than EAN, the description is '''MATERIAL_DESCRIPTION''', and there is no SSCC or LAYERS. A pallet template used as a case label prints "not found!" for those.

{| class="wikitable"
! Field !! Type !! What it prints
|-
| UNIQUE_ID || text || Internal identifier for this print request.
|-
| MATERIAL || text || Product code.
|-
| MATERIAL_DESCRIPTION || text || Product description.
|-
| MATERIAL_TYPE || text || Material type code.
|-
| PROD_EAN, PROD_VARIANT || text || GTIN and variant of the unit being labelled.
|-
| PROD_QUANTITY || number || Quantity being labelled.
|-
| PROD_UOM || text || Unit of measure for PROD_QUANTITY.
|-
| BASE_EAN, BASE_VARIANT, BASE_QUANTITY, BASE_UOM || mixed || The same values for the base unit.
|-
| BATCH_NUMBER || text || Batch number as printed.
|-
| BATCH_PREFIX, BATCH_SUFFIX || text || The parts added to the batch number, when used.
|-
| OVERRIDE_BATCH_PREFIX, OVERRIDE_MANUFACTURE_DATE, OVERRIDE_EXPIRY_DATE || text || Y when the operator overrode the default, otherwise N.
|-
| PROCESS_ORDER || text || Process order number.
|-
| REQUIRED_RESOURCE || text || Production line or resource.
|-
| LINE || text || The production line chosen on the screen.
|-
| LOCATION_ID || text || Location from the process order.
|-
| DATE_OF_MANUFACTURE || date || Date of manufacture. Add a format, for example <code><nowiki><*DATE_OF_MANUFACTURE^dd/MM/yyyy*></nowiki></code>.
|-
| EXPIRY_DATE || date || Expiry date. Add a format in the same way.
|-
| EXPIRY_MODE || text || BATCH or SSCC.
|-
| CUSTOMER_ID, CUSTOMER_NAME || text || Customer code and name.
|-
| PART_NO, ALT_TEXT_1 || text || Customer-specific text from [[Customer Data]].
|-
| LABEL_TYPE || text || Pack or Pallet.
|-
| MODULE_ID || text || The report module that produced the label.
|-
| PRINT_DATE || date and time || When the label was requested.
|-
| PRINT_COPIES || number || Number of copies requested.
|-
| PRINT_QUEUE_NAME || text || The queue or printer chosen.
|-
| USER_ID, WORKSTATION_ID || text || Who printed it and from which PC.
|}

Labels printed by the [[Quality Control Sample]] screen use their own, smaller set of fields and are not covered here.

== Fields that are always available ==

These are added by Commander4j for every label template, whichever screen prints it.

{| class="wikitable"
! Field !! What it prints
|-
| LABEL_NO || The copy number, 1 for the first label of a pallet, 2 for the second and so on. The standard label prints it as L1, L2.
|-
| HEADER_COMMENT || The text of the '''LABEL_HEADER_COMMENT''' system key, but only when the header text tick box on the printing screen is ticked. It is ticked by default. Otherwise blank.
|-
| PLANT || The '''PLANT''' system key.
|-
| EXPIRY_DATE_MODE || The '''EXPIRY DATE MODE''' system key, BATCH or SSCC.
|-
| ZPL_LABEL_COUNT || The number of copies requested, for use with the ZPL <code>^PQ</code> command. See the DEFINE BARCODE COUNT_MODE note in [[Label Template Syntax]].
|}

Values that are not fields but are useful on a label, such as the current user, the date and time of printing, and the Commander4j version, come from [[Label Function Syntax|functions]]: <code><nowiki><USERNAME()></nowiki></code>, <code><nowiki><TIMESTAMP(dd/MM/yyyy HH:mm)></nowiki></code> and <code><nowiki><VERSION()></nowiki></code>.

== Formatting a value ==

A format can follow the field name after a <code>^</code> character. It applies to dates, times and numbers only, and is ignored for text.

{| class="wikitable"
! Example !! Prints
|-
| <code><nowiki><*DATE_OF_MANUFACTURE*></nowiki></code> || 2026-03-01 (the default date format is yyyy-MM-dd)
|-
| <code><nowiki><*DATE_OF_MANUFACTURE^dd/MM/yyyy*></nowiki></code> || 01/03/2026
|-
| <code><nowiki><*PRINT_DATE^HH:mm*></nowiki></code> || 16:46
|-
| <code><nowiki><*QUANTITY*></nowiki></code> || 0224 (the default number format is 0000)
|-
| <code><nowiki><*QUANTITY^0*></nowiki></code> || 224
|-
| <code><nowiki><*QUANTITY^000000*></nowiki></code> || 000224
|}

Date formats use the Java pattern letters: dd day, MM month, yy or yyyy year, HH hour, mm minute, ss second. Number formats use 0 for a digit that is always printed and # for a digit that is printed only when needed.

Two things to be aware of:

* Round brackets in a text value are printed as curly braces, so a description of <code>Widget (Blue)</code> appears as <code>Widget {Blue}</code>. This protects the function syntax, which uses round brackets.
* If a date format is invalid the label prints the field name and an error message in place of the date.

== AutoLab4j ==

[[AutoLab4j]] prints the same template files with the same placeholders and the same [[Label Function Syntax|functions]], but it is not connected to the database. Its values come from the dataset CSV file that Commander4j writes when a process order is assigned to a line, and the field names are the column headings of that file. The list is on [[AutoLab4j Dataset CSV]]. The <code>^format</code> suffix described above is not applied by AutoLab4j, so dates and numbers are printed exactly as they appear in the CSV.

[[LabelServer4j]] does not use these template files. It drives Logopak and similar labellers with its own command scripts, which share the same family of functions; see [[LabelServer4j Operation]].

== Barcode variables ==

A name defined with '''DEFINE BARCODE''' at the top of the template can also be used as a field. In the standard label, <code><nowiki><*BARCODE1*></nowiki></code> and <code><nowiki><*BARCODE2*></nowiki></code> are the two GS1-128 barcodes with their code-set switching already worked out. This is explained in [[Label Template Syntax]].

== For database administrators ==

The pallet fields are the columns of the database view '''VIEW_PALLET_EXPIRY''' and the case fields are the columns of '''VIEW_LABEL_DATA'''. The columns are the same on MySQL, Microsoft SQL Server and Oracle. A site that needs an extra value on its labels can have these views extended, but the change is overwritten by upgrades, so talk to support first.

== See also ==

* [[Label Layouts]]
* [[Changing a Label]]
* [[Label Template Syntax]]
* [[Label Function Syntax]]

[[Category:Commander4j]]
[[Category:AutoLab4j]]