ASCII File Connector#
SHARK Link supports a standard ASCII format, suitable for Host Systems that are capable of exporting and importing ASCII files in a flat-file, table like format. The format is convenient to use with many host systems, especially older systems not supporting XML. If XML is available this is recommended instead, due to better flexibility, more functions and human readability.
The interchange of data, by means of readable ASCII files, makes it easy to debug and it is a robust solution not sensitive to for example temporary network problems.
The following transaction types are by default supported from the host (ERP) to SHARK:
| Transaction | Description | Comment | SHARK Order Type ID |
|---|---|---|---|
| PS | Pick Sale. | Standard picking order. | 1 |
| ST | Store. | Normal put-away operation for incoming goods. | 2 |
| MD | Item Master Data. | Optional master data for the articles | - |
| RA | Rename Article | Change the article number. |
The actual names of the transactions, can be configured and new user defined order types created in the configuration.
When the transaction has been executed, the pick and put transactions will be confirmed by SHARK , by an acknowledge file.
Typical flow of files from the Host System to SHARK. The host generates an order file, SHARK picks the order and returns an acknowledge file.
Folders and File Names#
One folder is used for sending files from the HOST to SHARK and another folder for acknowledge files from SHARK to the HOST.
Rules for the filename:
Files from the host must have a unique name with a fixed file extension. SHARK does not use the name as such, but it should not be reused to avoid deletion by overwriting existing files.
Files from SHARK to the Host are also unique. The name is the order number, followed by an index number, for example 9456-1.cmf. The index number is incremented for each written acknowledge file for the particular order.
Each file may contain one or more orders, but they are expected to be sorted in "order number" when created.
The procedure for importing files is:
The file is moved to a temporary local folder (a copy followed by a file-delete from the import folder). This is mainly done to improve performance, if the shared folder is a network folder on none-Windows systems or the access is via WAN networks.
SHARK imports the file from the temporary folder.
After SHARK has read the file, it is stored in a local log folder.
After a configurable period, the file in the log folder is deleted (default is 14 days).
If the import fails, the file is stored in an error folder instead, for later analysis or re-import.
In general SHARK Link only imports one file a time. If huge files, typically Master Data Files, are send frequently, it can be a good idea to use another file extension or folder for the Item Master Data files, this will allow the import to be handled in two separated threads and thereby preventing normal order files to be blocked by possible long running Master Data imports.
Various Issues#
The order can be modified by resending the same order again. The general rules for modifying an order are:
An order cannot be updated while it is working (the order has been released for picking or picking is in progress) and should not be updated until the acknowledge file has been returned. If an update is received, while the order is working the request will be rejected as an error.
If the order already exists, but the line number is new, the line will be appended to the order (existing lines will remain).
If the order and the line number already exists, the line will be replaced.
If an existing order, which has been closed (set to OK status in SHARK), is updated, it will be re-opened.
If a line is updated with quantity set to 0, it will be deleted.
This behavior can be modified using the configuration parameters:
ReplaceOrder: If set to true the order will always be deleted when the same ordernumber is imported again.
Master Data (Host → SHARK)#
Master data is basic information about the articles. The most important information is the article number and description, but other information can be transferred as well. The article description can also be updated in the order file, so the Master Data file is not absolutely required, SHARK will create new articles and update the description, when met in an order file. But the Master Data allows more information and will also work if SHARK is used with the Manual Transactions (transactions with no host-orders), this could be the case in an initial store process, where goods are moved from old locations into SHARK without orders.
Use BoxType to tell SHARK the preferred location type for the article (must be created in SHARK first).
The ERP Quantity is used to define what the host system actually expects on stock in SHARK. The information can be used to search inconsistencies between the 2 systems. Note that this kind of information is valid, only when there is no uncommitted transactions.
The Misc fields can be used for customized information and will as default be stored in the Article Master Data misc1 to misc5 fields.
Master data files can be very large and in a simple setup with only one file importer, a large file can block for normal orders. If it is necessary to send large Master Data Files during normal work hours, it is recommend to setup a dedicated Master data import folder, or to use a special file extension to allow separate import of Master Data and ordinary order files.
Field |
Desciption |
Format |
Example |
|---|---|---|---|
1 |
Master Data |
Text: "MD" |
"MD" or MD |
2 |
Article Number |
Text. Max 50 characters. |
"AC-127" |
3 |
Article Description. Can be left empty |
Text: "<text>" |
"Resistor 5 Ohm" |
4 |
BoxType. Can be left empty, in that case the default value will be used. |
Text: "<box type" |
"B5-75". The preferred box or location type. |
5 |
Storage strategy. Can be left empty, in that case the default value will be used. |
Text: "Fixed|FIFO|Floating" |
How the article will be stored "Floating" |
6 |
EAN Can be left empty |
EAN Number |
EAN Barcode 45999999999 |
7 |
ERP Qty Can be left empty |
Decimal |
The quantity in the ERP system . Used to compare the stocks. 15 15.0 |
8 |
Misc1 Can be left empty |
Text |
Optional field 1 |
9 |
Misc2 Can be left empty |
Text |
Optional field 2 |
10 |
Misc3 Can be left empty |
Text |
Optional field 3 |
11 |
Misc4 Can be left empty |
Text |
Optional field 4 |
12 |
Misc5 Can be left empty |
Text |
Optional field 5 |
MD,A001,Article description for A001
MD,A002,Article description for A002
MD,A003,Description for article A00
Pick/Put-Away Orders (Host → SHARK)#
The same file format is used for all order types: PS, PP, SP, SC
Each line is óne order line with comma separated fields and terminated with \<cr>\<ln> or \<ln>. Other separators can alternatively be defined.
Text fields can optionally be surrounded by " ".
Character encoding is as standard ISO-8859-1, but can be configured.
No header lines are used.
Field |
Desciption |
Format |
Example |
|---|---|---|---|
1 |
The line tag defines the order type. |
Text: PS|ST |
"PS" |
2 |
Order flags for example priority. Can be left empty. |
Text: "Express"|"Normal|High|Low" Number: 0-255 |
"Express" |
3 |
Order number |
Text: "<number>", max 50 characters. |
"12345" |
4 |
Delivery Note Number. Can be left empty |
Text: "<number>" |
"F00001" |
5 |
Article Number |
Text: "<number>", max 50 characters. |
"AC-127" |
6 |
Quantity |
Decimal: 0.0 |
12.0 |
7 |
Line number. Can be left empty, but if used it must be unique for the order. |
Integer |
1002 |
8 |
Delivery Date. Can be left empty. |
Date: yyyy-mm-dd |
2003-12-02. The actually format can be modified. |
9 |
Note on the order line. Can be left empty. |
Text: "<text>" |
"10 pcs. per box" |
10 |
Customer Name. Can be left empty. |
Text: "<name>" |
"Hansen A/S" |
11 |
Article Description. Can be left empty |
Text: "<description>" |
"Resistor 5 Ohm" |
12 |
Batch number. Can be left empty. |
Text: “<number>” |
Batch or lot number. Both text and numbers are legal. |
13 |
Article Owner. Can be left empty. |
Text: “<text>” |
The owner of the article. |
14 |
Unit Can be left empty. |
Text: “<text>” |
Quantity unit |
15 |
Misc1 Can be left empty. |
Text: “<text>” |
Optional field 1 |
16 |
Misc2 Can be left empty. |
Text: “<text>” |
Optional field 2 |
17 |
Misc3 Can be left empty. |
Text: “<text>” |
Optional field 3 |
18 |
Misc4 Can be left empty. |
Text: “<text>” |
Optional field 4 |
19 |
Misc5 Can be left empty. |
Text: “<text>” |
Optional field 5 |
Example – Simple file for picking orders:
A simple picking order with order number “12345678”, 3 lines (Line number 1,2 og 3) with the articles ART01, ART02, ART03. Pick 5 of ART01, 7 of ARG02 and 9 of ART03.
|
Support for negative quantities#
It is possible to use negative quantities; this will actually “reverse” the order type, but keep the order number. For example a “PS” order with a negative pick quantity is regarded as “returned goods” and the order type will be changed to “SC”. This feature supports the Microsoft Dynamics products, where returned articles can be handled, by adding the article to an existing order with negative number. The same is true for returning goods from purchase orders. Note that since SHARK does not allow picked pick and put orders, this will actually generate 2 different orders with the same order number, but with different order types.
Rename Article (SHARK → Host)#
This transaction is used to rename an old article number to a new one. It is possible to rename articles, also when they are in use, but please note that:
The Transaction Log will not be changed, the original article number will be kept.
For order import and acknowledge files, the rename will take place immediately. So the order can be imported with the old number, but will report back a new number, when the order is acknowledged back to the host.
This transaction does not support article owners.
| Field | Description | Format | Example |
|---|---|---|---|
| 1 | Confirmation of pick or put orders | RA | "RA" |
| 2 | Old article number | Text | “Art001” |
| 3 | New article number | Text | "NewArt01" |
Order Confirmation (SHARK → Host)#
When a pick or put transaction is finished in SHARK a confirmation is send back to the host. The exact point of time when the file will be generated, is configurable and can be:
When the order is finish (default).
When the order is partly finished. This means that if not everything could be picked, typical because of a back order situation, the order will still be confirmed.
When an order line is finish (each order line is confirmed individually, possible in different files).
If is possible to run with a one-way communication system, where SHARK receives the orders, but no confirmation is expected to be returned to the Host.
The same format is used for both pick, put-away and relative adjustments.
File format for the acknowledge file:
Field |
Description |
Format |
Example |
1 |
Confirmation of pick or put orders |
Text: "CP|CU|SA" CP: Confirm Pick CU: Confirm Put-Away SA: Stock Adjustment |
"CP" |
2 |
Order Number |
Text |
“123456” |
3 |
Line Number |
Integer |
12 |
4 |
Article Number |
Text: "<number>", max 50 characters. |
"AC-127" |
5 |
Actually Quantity |
Decimal: 0.0 |
12.0 Positive sign is stock increase. Negative numbers is stock decrease. |
6 |
Date |
Date: yyyy-MM-dd |
2003-12-02 |
7 |
Status of the order line |
Text: "OK|Partly|Cancel" |
"OK" |
8 |
Delivery Number |
|
|
9 |
Batch Number. Empty if not used. |
Text |
1234 |
The delivered quantity is what is actually delivered and not what is ordered. The status of the line will indicate if there is a mismatch, a status set to “OK” means the line is fulfilled as ordered.
Field 1 can be configured to any text string for each order type.
The acknowledge file will be be delivered to the specified output folder. It will have a .tmp extension, while it is written and afterwards renamed to the final extension. SHARK will never delete or move the file, this is the responsibility of the Host system.
Example of stock adjustment, Artikel "ART001" is decreased with 3:
|
Stock Report (SHARK → Host)#
The connector can be configured to send a stock report file when the job is executed. If the stock report is needed, setup an extra job to allow it to be scheduled individually from the normal confirmations (normally a stock report is only needed once a day).
File format for the Stock Report file:
Field |
Description |
Format |
Example |
|---|---|---|---|
1 |
Article Number |
Text |
Article number |
2 |
Owner |
Text |
Article owner in multiple owner setups. Default is empty. |
3 |
Stock Indicator |
Text |
Used for special stock types. |
4 |
ReservedTo |
Text |
Articles reserved to a specific order/customer. |
5 |
Stock Quantity |
Decimal: 0.0 |
Quantity on stock. |
6 |
Qty in Put-Away Orders |
Decimal: 0.0 |
Quantity registered in goods reception. |
7 |
Qty in Pick Orders |
Decimal: 0.0 |
Quantity registered in consolidation. |
8 |
Qty in transport |
Decimal: 0.0 |
Quantity in internal transport. |
9 |
Misc1 |
Text |
Customizable field |
10 |
Misc2 |
Text |
Customizable field |
11 |
Misc3 |
Text |
Customizable field |
12 |
Misc4 |
Text |
Customizable field |
13 |
Misc5 |
Text |
Customizable field |
14 |
LastAccessDate |
datetime |
Last time the location was accessed. Uses the datetime format specified with the DateFormat parameter in the configuration |
15 |
LastCountedTime |
datetime |
Last time the location was counted. Empty if newer counted. Uses the datetime format specified with the DateFormat parameter in the configuration |
Configuration#
To setup a job to generate a stock report every night, use the following setup
System Configuration → Registry → Scheduler → Jobs → StockReport
Registry Entry |
Data type |
Value |
Description |
|---|---|---|---|
ClassName |
String |
dk.logiware.SHARKlink. SHARKLinkMicrosoftDynamicExport |
|
Parameters.StockReport |
boolean |
true |
I true the stock report will be generated. |
Parameters.ReportPickPutConfirmations |
boolean |
false |
Disable order confirmation |
Parameters.reportStockAdjustments |
boolean |
false |
Disable stockadjustments |
Parameters.ReportInventoryReports |
boolean |
false |
Disable |
Parameters.stockReportFileName |
String |
stock-%Date%.txt |
Name of the stock report file 2 placeholders supported: %Date% %Time% |
Parameters.OutFolder |
String |
<folder> |
Folder where the stock report file is stored |
Hints for Microsoft Dynamics#
An interface must be implemented in the ERP system, there is no standard way of doing this in the Microsoft Dynamics solutions. Some hints:
Use the unique database id for the line to be sure the line number will not change if the order is modified.
For C5 or XAL (DOS like), export the data as “ANSI” formatted data to support none US characters in a SHARK compatible way.
When the host write files to SHARK, it is recommended first to create the file with a temporary extension and then rename the file when it is ready. SHARK will not begin reading a file that is locked and open by another application, but if the file is coming from an FTP Server, the shared import folder is a network folder or similar setups, it cannot be guaranteed that SHARK does not begin reading the file before it is completed and this obviously leads to an error. SHARK uses the same technique when it write files to the host.
Configuration of SHARK#
SHARKs uses 2 scheduled task for the ASCII connector, one for importing files and one for exporting files.
The following parameters must be configured in SHARK to use the ASCII Connector.
Import Class type: dk.logiware.SHARKlink.SHARKLinkMicrosoftDynamicImport
Export Class type: dk.logiware.SHARKlink.SHARKLinkMicrosoftDynamicExport
| Registry Entry | Data type | Value | Description |
|---|---|---|---|
| Parameters.FileFormat.InSeparator | String | A separator character | Default is “,” |
| Parameters.FileFormat.CommaSeparator | String | . | , |
| Parameters.FileFormat.DateFormat | String | yyyy-mm-dd | Date forma. See below how the define the format string. |
| Parameters.FileFormat.StringEnclosureChar | String | " | Character used to enclosure text. |
| Parameters.FileFormat.NumberFormatStr | String | 0.0 | |
| Parameters.FileFormat.OneFilePrLine | Boolean | false | true |
| Setup for each order type to support: | |||
| Parameters.FileFormat.OrderTypes.\<type>.Tag | String | Maps a file \<tag> to a SHARK order type. | |
| Parameters.FileFormat.OrderTypes.\<type>.OrderTypeID | Int | The SHARK OrderType number for the this order type. | |
| Parameters.FileFormat.OrderTypes.\<type>. ReversedOrderTypeID | Int | OrderType number in SHARK when the quantity is negative. |
The date format string
| Letter | Date or Time | Examples |
|---|---|---|
| G | Era designator | AD |
| y | Year | 1996; 96 |
| M | Month in year | July; Jul; 07 |
| w | Week in year | 27 |
| W | Week in month | 2 |
| D | Day in year | 189 |
| d | Day in month | 10 |
| F | Day of week in month | 2 |
| E | Day in week | Tuesday; Tue |
| a | Am/pm marker | PM |
| H | Hour in day (0-23) | 0 |
| k | Hour in day (1-24) | 24 |
| K | Hour in am/pm (0-11) | 0 |
| h | Hour in am/pm (1-12) | 12 |
| m | Minute in hour | 30 |
| s | Second in minute | 55 |
| S | Millisecond | 978 |
| z | Time zone | Pacific Standard Time; PST; GMT-08:00 |
| Z | Time zone | -0800 |