MES Transaction API Endpoints - Data 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.