Overview
This is an API to create a shipment transaction in the MES transaction queue.
A shipment transaction can do one or more of the following:
-
Palletize trade items: put them on a pallet (the pallet can be created at the same time).
-
Reserve trade items to a Delivery Agreement (Wisefish).
-
Ship standard items on a BC Sales Order (and post the shipment, if set up).
-
Finish the shipment on a Delivery Agreement (a transaction without lines).
Working with a shipment has two steps (details in How it works):
-
Endpoint: the MES posts to the endpoint, and the MES transaction is created. Nothing else is changed in BC yet.
-
Processing: the MES processor (job queue) error checks the transaction and does the palletizing, reservation or shipment in BC.
See more information about the workflow: MES Use Case: Production
|
Endpoint name |
|
|
Source table |
|
|
Fixed view/defaults |
This endpoint will only create/show transactions with Type = Shipment. |
|
Requests allowed |
|
|
Primary key |
The primary key of a transaction line is |
|
Record ID |
The record ID is |
|
Procedures |
None |
Data
Field List
|
Property |
Type |
Format |
Description |
|
|---|---|---|---|---|
|
|
string |
uuid |
The automatic system ID, which is in GUID format. |
record id non-editable |
|
|
integer |
|
The Transaction this line belongs to.
|
PRIMARY KEY OPTIONAL |
|
|
integer |
|
The sequence number of this line, within the transaction which has ID = |
PRIMARY KEY non-editable |
|
|
string |
max 10 |
The terminal will indicate from which manufacturing unit or machine this entry comes from. This is mandatory, but if there is only one terminal, this can be set up as a default on page API Base Setup. |
OPTIONAL |
|
|
string |
max 10 |
The sender needs to use their own reference, because every transaction needs to be unique. The same external reference can be used repeatedly in order to add a line to a transaction already created. |
Mandatory |
|
|
string |
enum |
Values:
If skipped, it is found from |
OPTIONAL |
|
|
string |
max 20 |
The Delivery Agreement No. or Sales Order No. Skip it when only palletizing. If When adding a line to a current Transaction, the |
OPTIONAL |
|
|
integer |
|
The line of the Delivery Agreement or Sales Order. If not given, a matching line is found. |
OPTIONAL |
|
|
string |
date |
The date of the palletizing, reservation or shipment. If not given, today. |
OPTIONAL |
|
|
string |
max 10 |
The location where the items are found. If not given, the location of the transaction (see How it works > Endpoint). |
Mandatory * |
|
|
string |
max 20 |
Item No. |
Mandatory |
|
|
decimal |
|
The quantity, in |
Mandatory * |
|
|
string |
max 10 |
The unit of measure that belongs to the |
Mandatory * |
|
|
string |
max 10 |
The lot of the item. Required for lot tracked items, unless the line refers to a specific trade item (then it is taken from the trade item, and a given lot must match). |
Mandatory * |
|
|
string |
max 20 |
A direct reference to a trade item can be given with |
OPTIONAL |
|
|
integer |
|
See |
OPTIONAL |
|
|
string |
max 22 |
A direct reference to a trade item with its barcode. |
OPTIONAL |
|
|
string |
max 20 |
The pallet to put the trade item on. If it does not exist, it is created (see How it works > Palletizing). |
OPTIONAL |
|
|
string |
max 20 |
Can be used instead of |
OPTIONAL |
|
|
date-time utc |
|
The system populates this value automatically. |
non-editable |
Example Object
Usage
The requests below are sent to .../api/wisefish/base/v1.0/companies({companyId})/mesShipment, shortened to .../mesShipment. How to create a new transaction and add lines to it works in the same way as for API - MES Receipt.
Palletizing (no document)
Put a barcoded trade item on a new pallet
POST
.../mesShipment
{
"externalReference": "REF-NO-1",
"itemNo": "70064",
"tradeItemBarcode": "0123456",
"palletBarcode": "00066666667000000124",
"palletNo": "000012"
}
The pallet does not exist, so it is created (barcode 00066666667000000124, no. 000012, key item 70064), and the trade item with barcode 0123456 is put on it. If that trade item is not of item 70064, the transaction gets an error.
Put a quantity of a lot on an existing pallet
POST
.../mesShipment
{
"externalReference": "REF-NO-2",
"itemNo": "70064",
"lot": "PROD180501",
"quantity": 50,
"unitOfMeasure": "BOX",
"palletBarcode": "00066666667000000124"
}
The pallet exists, so palletNo can be skipped. A trade item of the item and lot with 50 boxes (or the first with more, then it is split) is put on the pallet.
Reservation to a Delivery Agreement
Reserve a trade item, and put it on a pallet
POST
.../mesShipment
{
"externalReference": "REF-NO-3",
"documentNo": "DA-009",
"itemNo": "70064",
"tradeItemBarcode": "0123456",
"palletBarcode": "00066666667000000124"
}
DA-009 is found as a Delivery Agreement. The trade item is put on the pallet, and reserved to the agreement line for the item (documentLineNo can be given to choose the line).
Reserve a quantity of a lot (no barcodes)
POST
.../mesShipment
{
"externalReference": "REF-NO-4",
"documentType": "SalesAgreement",
"documentNo": "DA-009",
"documentLineNo": 20000,
"itemNo": "70064",
"quantity": 100,
"unitOfMeasure": "KG",
"lot": "LOT-123"
}
100 kg of the lot are reserved to line 20000. Without a reference, only trade items that are not reserved are used.
Finish the shipment on a Delivery Agreement
When the MES has sent everything for a Delivery Agreement, it says so with a shipment transaction without lines. Because this endpoint always creates a line, the transaction is created with the transactions endpoint:
POST
.../transactions
{
"terminal": "INNOVA",
"externalReference": "DA-009-END",
"type": "Shipment",
"documentType": "SalesAgreement",
"documentNo": "DA-009"
}
When this transaction is processed:
-
It must wait until all other MES transactions on the agreement are processed. Until then, it gets an error, and can be processed again later.
-
The agreement gets MES Status MES Finished.
-
With Sync Quantity and Reserved = After every transaction or After shipment closure on the Terminal, the agreement's quantities are updated to the reserved quantity.
-
The posting document is not created (see WFPAPI-194).
Shipment of standard items on a Sales Order
POST
.../mesShipment
{
"externalReference": "REF-NO-5",
"documentNo": "1003",
"itemNo": "70074",
"quantity": 100,
"unitOfMeasure": "PCS",
"lot": "LOT-123"
}
1003 is found as a Sales Order. 100 PCS of the lot are registered as shipped on the sales line (and the shipment posted, if the Terminal has Post Shipment Automatically).
How it works
POST → the transaction is created with status Ready (or On Hold) → the job queue error checks it → and palletizes, reserves or ships → status Processed.
If anything is wrong, the status is Error and nothing is changed in BC. The error can be fixed and the transaction processed again.
-
Nothing is changed in BC (no pallets, splits, reservations or shipments) until the transaction has been processed.
-
Trade items are shipped on Delivery Agreements (or only palletized), standard items on Sales Orders.
-
Post Shipment Automatically only works for Sales Orders. On a Delivery Agreement it gives an error (not implemented, see WFPAPI-194).
Endpoint
Each POST creates one line in table MES Transaction Line with Transaction Type = Shipment, and the response is returned immediately.
Header (MES Transaction)
The line is added to an existing transaction header, or a new header is created:
-
If
transactionIdis given, the line is added to that transaction. It must exist. -
Else, if a transaction with the same
terminal+externalReferenceexists, the line is added to it. -
Else a new transaction header is created.
When a line is added to an existing transaction, the transaction must not be Processed yet, and a given terminal, externalReference and documentNo must match the transaction.
Default values on a new header:
|
Field |
Value |
|---|---|
|
Type |
Shipment |
|
Terminal |
|
|
Activity Date |
|
|
Document Type |
Only if
Any other number (for example a Production Order) is refused (error in the response). |
|
Lot |
Not set: a shipment can have lines of many lots |
|
Location |
Terminal Production Location, else User Profile, else |
|
Stock Center |
Terminal Default Stock Center, else User Profile |
|
Status |
Ready, or On Hold if MES Terminal Control says shipments from this terminal/location are processed manually |
Line (MES Transaction Line)
Default values on the line, if not given in the request:
|
Field |
Value |
|---|---|
|
Line No. |
The next line number of the transaction |
|
Document Type |
From the header |
|
Location |
The location of the header |
|
Quantity, Unit, Lot |
With a reference to a trade item: the lot of the trade item and, if both |
|
Item No. |
Mapped to the BC item number, if Data Mapping is active |
|
Unit of Measure |
If |
|
Pallet No. |
From the pallet, if the pallet with |
Errors in the response (nothing is created)
-
itemNois missing -
the terminal does not exist
-
externalReferenceis missing, or has already been used for another transaction from the same terminal (also archived transactions). Not checked if the Terminal has Disable Ext. Reference Check. -
no Location (neither a default nor given)
-
documentNois given withoutdocumentType, but no Delivery Agreement or Sales Order is found with this number -
tradeItemStage+tradeItemLineNorefer to a trade item that does not exist
Everything else is checked when the transaction is processed.
Processing
The MES processor (job queue) processes Ready transactions: first the error check, then the posting. Everything for one transaction is done in one unit: if anything fails, nothing is changed in BC, and the job queue continues with the next transaction.
What is done depends on the document of the transaction:
|
Document |
Items |
For each line |
|---|---|---|
|
None |
Trade items |
Find the trade item → palletize |
|
Delivery Agreement |
Trade items |
Agreement line → find the trade item → palletize (if a pallet is given) → reserve |
|
Sales Order |
Standard items |
Sales line → register what is shipped → post (if set up) |
|
Delivery Agreement, no lines |
|
Finish the shipment on the agreement (see Usage > Finish the shipment on a Delivery Agreement) |
The steps are the same, whether the transaction only palletizes or also reserves. They are described once below.
Finding the trade item
-
Without a reference: an open trade item of the item and lot on the line's location and the transaction's stock center, that is not reserved: one with exactly the quantity, or else one with enough quantity that is not on a pallet. The lot is required.
-
With a reference (
tradeItemBarcode, ortradeItemStage+tradeItemLineNo): the trade item must exist, be of the same item, on the same location, stock center and lot (if given), and have enough quantity. It may be reserved: see Reservation below. -
Part of a trade item: the trade item is split. The requested quantity is palletized/reserved, the rest stays where it was, as a new trade item (not on the pallet, not reserved). A reserved trade item, or a trade item on a pallet, is not split (only as a whole).
Palletizing
Only when palletBarcode or palletNo is given:
-
The pallet is found with
palletBarcode, or else withpalletNo. An existing pallet must be on the transaction's stock center and the line's location. -
If the pallet does not exist, it is created if the Terminal has Pallets Created in MES; then both
palletBarcodeandpalletNoare required. Else: error. -
Only trade items can be palletized.
Reservation (Delivery Agreement)
-
The agreement must exist. The agreement line is
documentLineNo, or a matching line is found. If no line is found: error, unless the Terminal has Create missing Sales Lines. With Sales Line No. is Mandatory,documentLineNois required. -
A trade item that is reserved to another agreement gives an error, unless the Terminal has Allow Changing Reservation. A trade item reserved to the same agreement is fine.
-
Wisefish can refuse the reservation (for example when the shipment date of the agreement is before the production date of the trade item). Then the transaction gets the error, and nothing is changed (no split, an old reservation is kept).
-
A line must have either a reservation or a pallet. With Disable Reservation on the Terminal, nothing is reserved (only palletized, and the agreement line created).
Sales Order
-
Only standard items. The Sales Order must exist.
-
Lot tracked items need the
lot. Items with Package Sales Outb. Tracking need thepalletBarcode(the package). -
There must be enough inventory of the item on the line's location (and lot).
-
The sales line is
documentLineNo, or a matching line is found. If no line is found: error, unless the Terminal has Create missing Sales Lines.
Errors on the transaction (status Error, nothing changed)
-
A transaction cannot have both trade items and standard items. Trade items only without a document or on a Delivery Agreement, standard items only on a Sales Order.
-
The document does not exist, or
documentNoon a line is not the document of the transaction. -
Post Shipment Automatically on a Delivery Agreement: not implemented.
-
A finishing transaction (no lines) while other MES transactions on the agreement are not processed yet.
-
And the checks described above (trade item, pallet, agreement or sales line, inventory).
Result (after processing)
Palletizing
-
A new pallet is created (barcode, pallet no., key item =
itemNo, the transaction's stock center and the line's location). -
The trade item (or the split part) is put on the pallet.
Delivery Agreement
-
A missing agreement line is created, with Create missing Sales Lines.
-
The trade item (or the split part) is reserved to the agreement line. A reservation to another agreement is moved, with Allow Changing Reservation.
-
Sync Quantity and Reserved = After every transaction: the agreement's quantities are updated to the reserved quantity.
-
Finishing (no lines): the agreement gets MES Status MES Finished, see Usage.
Sales Order
-
A missing sales line is created, with Create missing Sales Lines. If more is shipped than ordered, the line's quantity is raised.
-
Item tracking (lot, package) is put on the sales line for the shipped quantity.
-
With Post Shipment Automatically, the shipment is posted in the same unit. If the posting fails, nothing is registered.
The transaction gets status Processed.
The exact behaviour is described by the unit tests: MES Unit Tests - Shipment
Settings
Settings that change what happens in the endpoint or in processing:
|
Setting |
Where |
Step |
Effect |
|---|---|---|---|
|
Production Location, Default Stock Center |
MES Terminal |
Endpoint |
Default values on the transaction header |
|
Disable Ext. Reference Check |
MES Terminal |
Endpoint |
|
|
Populate Unit Automatically |
MES Terminal |
Endpoint |
Missing |
|
Process Manually |
MES Terminal Control |
Endpoint |
New transactions get status On Hold and are not processed by the job queue |
|
Pallets Created in MES |
MES Terminal |
Processing |
On: an unknown pallet is created (pallet barcode and pallet no. required). Off: the pallet must exist. |
|
Disable Reservation |
MES Terminal |
Processing |
Delivery Agreements: nothing is reserved (only palletizing and agreement lines) |
|
Allow Changing Reservation |
MES Terminal |
Processing |
A trade item reserved to another agreement can be reserved to this one |
|
Create missing Sales Lines |
MES Terminal |
Processing |
A missing agreement line or sales line is created instead of an error |
|
Sales Line No. is Mandatory |
MES Terminal |
Processing |
Delivery Agreements: |
|
Sync Quantity and Reserved |
MES Terminal |
Processing |
After every transaction or After shipment closure: the Delivery Agreement's quantities are updated to the reserved quantity |
|
Post Shipment Automatically |
MES Terminal |
Processing |
Sales Orders: the shipment is posted in the same unit. Delivery Agreements: error (not implemented, WFPAPI-194). |
|
Package Sales Outb. Tracking |
Item Tracking Code |
Processing |
Sales Orders: |