MES Inbound - Error Handling & Validation

The APIs to insert MES transactions into Wisefish are multiple but have a common error handling logic. The purpose of this document is to describe the error handling process:

Required properties
Which data properties are required at the time of inserting the data, i.e. in the API request. If these values are missing, the request will return an error an no entry is created in Wisefish.
Automatic population
Which properties can can be skipped in the API requests, to let the values get retrieved from setup cards in Wisefish. These cards can be for example and they have a certain priority order:
1. Production Lot
2. MES Terminal
3. User Profile
4. Wisefish Setup & Configuration cards

Transaction Identity

Origin of an transaction

A transaction is identified by 2 values:

Terminal - the external machine or system that sent in the transaction. This could for example be a packing station on the production floor, or the Stream handheld app.
External Reference - the sender can add their own reference number (or code), in order to identify the transaction within the scope of the sender.

Adding a line to a specific Transaction

When adding a line to a current Transaction, and if both transactionId and extReference are given, but they do not match with one single transaction, an error is given:

JSON

{
    "error": {
        "code": "Application_DialogException",
        "message": "The given External Reference XXX does not match the existing transaction external reference ID-0123  CorrelationId:  37ae53e3-f81c-41d5-8597-81c83296fc0f."
    }
}

Mandatory properties at API request

External Reference

When creating a new Transaction (first level), the extReference property is mandatory.

Document No.

When creating a new Transaction of type Output, Receipt or Shipment, documentNo must (or may) be given:

If Type = Receipt, the number must exist in one of the following document lists:
- Receipt Agreements
- Purchase Orders
- Fishing Trips
If Type = Shipment, a document number must be given that exists in one of the following document lists:
- Sales Agreement
If Type = Output, a document number may be given (not mandatory) and then it must exists in one of the following document lists:
- Sales Agreement - when producing to an order
- Sales Order - when producing to an order
- Production Agreement - when producing to a production order

The API does not check if a document with this number exists in the system. If it does not exist, the transaction will stop in the processing queue later.

When updating a Transaction, the documentNo is not necessary, because it has already been put on the transaction. But if it is given, it must match the document number on the transaction.

Quantity or Weight

There are 2 ways of giving the quantity of the Trade Item to be received:

quantity and unitOfMeasure
weight

Either of them is mandatory, i.e. if weight is given, quantity and unit can be skipped.

Automatic Population

This chapter describes what is automatically populated on insert, if the values are not given in the API request body:

Transaction

On the header level, the automatic population and priority order is as follows:

	Field	Automatic population - and priority order if can come from >1 origin
1	ID	This is the primary key and record ID of the transaction. It is automatically populated by incrementing last transaction by 1.
2	Terminal	Given for every transaction, or can be set up as default in the case where there is only one system sending in transactions.
3	Stock Center Code	If given in the API as property `stockCenter` else if `terminal` is given and found in table MES Terminal and it is a default stock center else the default value is taken from the User Profile
4	Location Code	If given in the API as property `location` else if `terminal` is given and found in table MES Terminal and it is a default location else the default value is taken from the User Profile
5	Type	The default for this field depends on which endpoint is used: `transactions` : default value is set as Output, but there is a property to change `receivingTransactions` : set as Receipt `outputTransactions` : set as Output `consumptionTransactions` : set as Consumption
6	Document Type	This property can be populated automatically according to where the given `documentNo` was found: The given `documentNo` is found as Receipt Agreement, the then value is set as Receipt Agreement The given `documentNo` is found as Purchase Order, the then value is set as Purchase Order If the given `lot` is for a Lot that is connected to a Fishing Trip No., then value is set as Fishing Trip
7	Stage	This property can be populated automatically with the following priority: If given in the API as property `stage` it has the first priority else if the `lot` has a “Processing Stage” else if the Terminal has a default Stage (can be different for receipt and production) else the default value is taken from the User Profile
8	Activity Date	There are properties to populate this, name can differs with different endpoints: `activityDate` `productionDate` `receiptDate` but value is always put in field “Activity Date”. If left blank, this is set automatically as today’s date.
9	Date Created Time Created	Current date and time is put here. Fields are non-editable.
10	Created by User	Populated automatically.
11	Status	Status of a newly created entry is Ready - when an API is used to create a header entry directly On Hold - when an API is used to add a line to a transaction. When all lines have been added, and the transaction is ready to be posted, the entry must be “released of hold” by setting the transaction ready with endpoint: TO-DO: THIS-Do we want this behaviour?

Transaction Line

On the line level, the automatic population is as follows:

	Field	Automatic population - and priority order if can come from >1 origin
1	Line No.	Primary key, automatically populated as a sequence number.
2	Pallet No.	If `palletBarcode` is given and the pallet already exists in Wisefish, the Pallet No. is put here for better information.

Additional Information

This chapter describes in more details some features in the MES connect solution.

Locations

This is an overview of how the Locations are used in the MES Transactions and their processing:

Transactions Type	Transaction. Location Field “Location”	Transaction Line From Location Fields “From Location” and “To Location”	Transaction Line To Location	Additional Requirement
Receipt	The default comes from the Terminal or User Profile. This is then used as a default for new lines	Items will be received on this location. All lines must have the same Location, no mixing allowed.	Not used
Output	The default comes from the Terminal or User Profile. This is then used as a default for new lines	Output will be posted on this location, for all the lines. Credit Consumption uses the same field. All lines must have the same Location, no mixing allowed. In the same way as the transaction has the same lot and it would be strange	Not used	Það væri hægt að breyta þannig að lotan bókist á mismunandi Location, en ekki viss það passi í Wisefish.
Consumption	The default comes from the Terminal or User Profile. The location in this field is only for information. Could be used to show the location of the production. The consumption in the lines can be taken from various locations, as given with “From Location”. But this is anyway used as a default for new lines - but in many cases the consumed item is on another location, then that location needs to be given in the API request.	Standard items are consumed from this location. But Trade Items can have any location, when checking balance, no location is used.	Not used	Wisefish would allow posting consumption from whatever location, but to keep it similar as for other transactions, the item must be available on the location given in the “From Location” field á ég að gera það?
Transfer	Not used But to get through the error handler, the system sets automatically the “Production Location”	Item needs to be available here	and will be transferred into the location
Adjustment	Not used But to get through the error handler, the system sets automatically the “Production Location”	For negative adjustments, the location is given in “From Location”	For positive adjustments, the location is given in “To Location”

GÆTI ÞETTA VIRKAÐ SVONA

Trans.Location - if this is used, then all the transaction lines will have the same location in field “Location”