Interface Message Formats

From Commander4j
Revision as of 11:22, 1 April 2026 by Dgarratt (talk | contribs) (Improved by ClaudeAI documentation bot — expanded content)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Commander4j exchanges data with external systems (typically an ERP such as SAP) using XML file-based messages. Each message follows a common envelope structure containing a header section and a messageData payload. Messages are processed by the Interface service running on the Commander4j server.

All dates and times use ISO 8601 format: YYYY-MM-DDTHH:MM:SS.

Common Header Fields

The following fields appear in the outer envelope of every message, regardless of direction or type:

Field Description
hostRef Identifies the source system or service that generated the message.
messageRef A unique reference assigned to this message, used for logging and duplicate detection.
interfaceType Describes the message type — e.g. Production Declaration, Process Order, Material Definition.
messageInformation A brief human-readable summary of the message content, used in the Interface Log.
interfaceDirection Either Input (inbound to Commander4j) or Output (outbound from Commander4j).
messageDate The date and time the message was created.
messageData Contains the type-specific payload described in the sections below.

Output Messages

Production Declaration

Sent by Commander4j to the ERP when a pallet has been confirmed on the Production Declaration screen. Contains the full details of the pallet that has just been produced and confirmed.

Key fields within productionDeclaration:

Field Description
SSCC The unique Serial Shipping Container Code (SSCC / barcode) of the pallet.
processOrder The Process Order number the pallet was produced against.
material The material (product) code.
description The material description.
ean The EAN/GTIN barcode of the material.
batch The batch number assigned to the pallet.
batchStatus The batch quality status — e.g. Unrestricted, Restricted.
expiryDate The best-before or expiry date of the batch.
productionQuantity The quantity produced on this pallet.
productionUOM The unit of measure for the production quantity.
location The location ID where the pallet was produced.
plant The plant code.
confirmed Y if the pallet has been confirmed; N if unconfirmed.
productionDate The date and time the pallet was confirmed.
requiredResource The production line or resource the pallet was produced on.
customerID The customer this pallet is associated with (defaults to SELF for own-stock pallets).

Example: 

<?xml version="1.0" encoding="UTF-8"?>
<message>
   <hostRef>service</hostRef>
   <messageRef>18722440</messageRef>
   <interfaceType>Production Declaration</interfaceType>
   <messageInformation>SSCC=350001615053457609</messageInformation>
   <interfaceDirection>Output</interfaceDirection>
   <messageDate>2024-03-03T16:25:10</messageDate>
   <messageData>
       <productionDeclaration>
           <SSCC>350001615053457609</SSCC>
           <processOrder>28946352</processOrder>
           <material>44219856</material>
           <description>Premium Widget Blue</description>
           <ean>05000161030460</ean>
           <batch>4063093330</batch>
           <batchStatus>Restricted</batchStatus>
           <expiryDate>2026-03-31T00:00:00</expiryDate>
           <productionQuantity>5616.000</productionQuantity>
           <productionUOM>EA</productionUOM>
           <location>WISBECH</location>
           <plant>0933</plant>
           <confirmed>Y</confirmed>
           <productionDate>2024-03-03T16:25:08</productionDate>
           <requiredResource>P1VK12</requiredResource>
           <customerID>SELF</customerID>
       </productionDeclaration>
   </messageData>
</message>

Input Messages

Process Order

Sent from the ERP to Commander4j to create or update a Process Order. Commander4j uses Process Orders to drive label printing and production recording.

Key fields within processOrder:

Field Description
orderNo The Process Order number.
status The order status — e.g. Ready, Running, Discarded.
material The material (product) code to be produced.
description The material description.
requiredQuantity The total quantity required for this order.
requiredUom The unit of measure for the required quantity.
requiredResource The production line or resource this order is assigned to.
dueDate The date and time the order is due to complete.
plant The plant code.
location The storage location for finished goods.
defaultPalletStatus The initial quality status to assign to pallets produced against this order. 
<?xml version="1.0" encoding="UTF-8"?>
<message>
  <hostRef>DEMO</hostRef>
  <interfaceType>Process Order</interfaceType>
  <interfaceDirection>Input</interfaceDirection>
  <messageDate>2024-03-03T15:54:11</messageDate>
  <messageData>
     <processOrder>
        <orderNo>28998413</orderNo>
        <status>Ready</status>
        <material>44066725</material>
        <description>Flux Capacitor</description>
        <requiredQuantity>48480</requiredQuantity>
        <requiredUom>KG</requiredUom>
        <requiredResource>TP3OSL</requiredResource>
        <dueDate>2024-03-03T20:27:35</dueDate>
        <plant>0933</plant>
        <location>FACTORY1</location>
        <defaultPalletStatus>Unrestricted</defaultPalletStatus>
     </processOrder>
  </messageData>
</message>

Process Order Status Change

Updates the status of an existing Process Order in Commander4j without replacing the full order record. Typically used to close or discard an order from the ERP side. 

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <hostRef>DEMO</hostRef>
  <interfaceType>Process Order Status Change</interfaceType>
  <interfaceDirection>Input</interfaceDirection>
  <messageDate>2023-10-06T11:35:23</messageDate>
  <messageData>
     <processOrderStatusChange>
        <orderNo>5000335533</orderNo>
        <status>Discarded</status>
     </processOrderStatusChange>
  </messageData>
</message>

Pallet Status Change

Updates the quality status of one or more pallets already recorded in Commander4j. Allows the ERP to push status decisions (e.g. releasing a restricted batch) back to Commander4j without a full pallet record update. 

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <hostRef>DEMO</hostRef>
  <interfaceType>Pallet Status Change</interfaceType>
  <interfaceDirection>Input</interfaceDirection>
  <messageDate>2024-03-03T16:34:58</messageDate>
  <messageData>
     <palletStatusChange>
        <sscc>350001615053457609</sscc>
        <status>Unrestricted</status>
     </palletStatusChange>
  </messageData>
</message>

Material Definition

Creates or updates a Material record in Commander4j. Typically sent from the ERP when a new product is set up or when material master data changes. Includes unit of measure conversions and EAN barcode assignments.

Key fields within materialDefinition:

Field Description
material The material (product) code.
description The material description.
base_uom The base unit of measure.
gross_weight / net_weight Gross and net weights of the base unit.
weight_uom Unit of measure for the weight values.
shelf_life / shelf_life_uom Shelf life duration and its unit (e.g. 24 / M for 24 months).
enabled Y to make the material active; N to disable it.
materialUOMDefinition Repeating block defining each unit of measure with its EAN barcode, variant and conversion factor.

Pallet Move

Instructs Commander4j to update the location of a pallet. Used when the ERP records a stock movement and needs Commander4j's pallet records to reflect the new location. 

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <hostRef>service</hostRef>
  <interfaceType>Pallet Move</interfaceType>
  <interfaceDirection>Input</interfaceDirection>
  <messageDate>2024-03-03T16:23:38</messageDate>
  <messageData>
     <palletMove>
        <pallet>
           <sscc>350001615053666100</sscc>
           <fromLocation>FACTORY1</fromLocation>
           <toLocation>FACTORY2</toLocation>
        </pallet>
     </palletMove>
  </messageData>
</message>

Batch Status Change

Updates the quality status of a material batch across all pallets in Commander4j that carry that batch number. Useful when an ERP quality decision covers an entire batch rather than individual pallets. 

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <hostRef>DEMO</hostRef>
  <interfaceType>Batch Status Change</interfaceType>
  <interfaceDirection>Input</interfaceDirection>
  <messageDate>2024-03-03T12:33:36</messageDate>
  <messageData>
     <batchStatusChange>
        <batch>4062093355</batch>
        <material>43898974</material>
        <status>Unrestricted</status>
     </batchStatusChange>
  </messageData>
</message>

See also: Interface Admin, Interface Log, Interface Example Data Flow 1, Interface Example Data Flow 2.

Retrieved from ‘https://wiki.commander4j.com/index.php?title=Interface_Message_Formats&oldid=1755’