Interfaces

Object and Field

Object

SAGE Warehousing provides various standard interface files to communicate with external applications. This document presents the various predefined interface templates provided in the standard Warehousing package and their implementation.

These templates can be entirely set up, both concerning the tansmitted information and the exchange conventions. This enables our customers to be fully self-sufficient as regards the control of the exchanges with the outside world.

Domain

Term L3 (Level 3) will designate Central IT (purchase management, sales management, production, etc.).

Term L2 will be used for SAGE Warehousing.

Update principle of stock L3

On receipt        

Stock L3 is updated via the interfaces:

• Receipt and/or storing report

On issue        

Stock L3 is updated on issue via the interfaces:

• Picking and/or shipping report

Other events

Stock L3 can be levelled (automatically or manually) with stock L2 via the interfaces :

• Stock image
• Adjustment report
• Assembling report

Data exchange principle

An interface is an information exchange protocol between two separate applications.

There are import and export interfaces. Import interfaces integrate L3 data into SAGE Warehousing while export interfaces upload information from SAGE Warehousing to L3.

Import interfaces can follow 3 different operating modes:

• creation: Data are added to SAGE Warehousing
• modification: Already existing data are modified
• deletion: Already existing data are deleted

Principle

Exchanges between L3 and L2 take place in the form of flat files according to the following principle:

Import: Warehousing processes those files that have been previously placed by L3 in the folders (or directories) defined for each interface flow.

• Stage 1: Integration of the file into a processing table: technical consistency check.
• Stage 2: Integration into the Warehousing tables: functional check. During these two stages, files are stored in directories that can be set up.

Export: Warehousing makes the files available for L3 in the folders (or directories) defined for each interface flow. L3 has to recover these files.

• Stage 1: On performing the full validation of an input, for the storing report, at the end of DO picking, for the picking report, on validation of a shipment, for the shipping report, or on validation of the adjustment movements, the reports are generated automatically in a defined directory (that can be set up).
• Stage 2: extraction of the table and generation of a file made available to L3. During stage 2, the issued files are saved in a directory that needs to be set up.

Directory

The directories that accommodate the interfaced data can be entirely set up. They are still set up as follows:

As far as the imported files are concerned:

• Import directory(ies)
  Directory(ies) where the files should be placed to be processed by Warehousing.
  A directory to be set up ("IMP") is defined by default for all the interfaces.
  Dedicated directories can be associated with each interface.
• Import processing directory
  Directory where the import files being processed are temporarily placed.
  A single directory to be set up ("IMPTRT") is defined for all the interfaces.
• Import error directory
  Directory of the import files that generated structure errors.
  A single directory to be set up ("IMPERR") is defined for all the interfaces.
• Import destination directory
  Backup directory of the import files that were processed with no structure errors.
  A single directory to be set up ("IMPBAK") is defined for all the interfaces.

As far as the exported files are concerned:

• Export directory(ies)
  Directory(ies) where the files are placed.
  A directory to be set up ("EXP") is defined by default for all the interfaces.
  Dedicated directories can be associated with each interface.
• Export processing directory
  Directory where the export files being made up are temporarily placed.
  A single directory to be set up ("EXPTRT") is defined for all the interfaces.
• Export backup directory
  Backup directory of the generated export files. A single directory to be set up ("EXPBAK") is defined for all the interfaces.
  

Setup

Activation parameters of the interfaces in export mode

Irrespective of the interface flow, the export can be limited to some combinations (site, depositor)

• Interface setup: interface and file activation; site limit, depositor
• Activation parameter linked to the interface template

The standard interfaces relating to the EIs and DOs are conditioned by a "L3 transmission" parameter of the movement code.
Specific activation conditions can be associated with some flows. They are then specified for the flow concerned.

Parameters/General parameters/Parameter values

The "INT" chapter is used to configure the interfaces for the folder as a whole or for a specific site. All the parametrs are subdivied into 3 groups:
1. EXP Export interface

2. MIS Miscellaneous

Difference between ITASLEEP and ITAWAIT

In the INTERFACE processing, a loop runs on the various interfaces. This loop processes in priority the interface batches that already exist with the status '1-To be processed', either to integrate them to the DB for an interface on receipt, or to create flat files in the EXPREP directory for an interface on issue. For an interface on receipt, in the absence of any batch to be processed, a search is conducted to check if new flat files have been placed in the IMPREP directory. If this is the case, new interface batches are created from these flat files.

This search for new flat files in the IMPREP directory implies the launch of a resource-consuming system order. If this takes place too often, the resources of the machine are overused for very few files recovered each time. If this takes place less often, the resources of the machine are less exhausted for more files recovered each time, but the response time is longer.
The 1st time this search is supposed to take place for an interface loop, it is checked if ITASLEEP seconds have elapsed since the last time this question was raised and the answer was Yes. If ITASLEEP seconds have elapsed, this search will be conducted in this interface loop. Otherwise, the search will be conducted in a next loop when ITASLEEP seconds have elapsed.
If a complete blank loop is run (without interface batch processing nor detection of new flat files on receipt), ITAWAIT seconds need to have elpased before a new loop is restarted.

3. REP Directory and extension

Usage/Interfaces/Parameters

For each interface template to be used, the setup to be applied should be defined accurately. For that purpose, it is recommended to duplicate the existing setup in order to keep the reference setup.

• The interfaces from Warehousing to Level 3 are prefixed with X (for export).
• The interfaces from Level 3 to Warehousing are not prefixed.

All the interfaces defined for a site or a site/depositor combination are listed (to be entered in the "Environment" tab). By default ((value "*" for sites and depositor), the interfaces will be generated indentically for all the sites and depositors of the sites of a folder.

The information displayed on the screen specifies:

• If the interface is active
• The rank of the imports/exports for each flow
• The time slot during which the interface is active
• The name of the template to be used for the interface
• Whether the files generated on export should be the object of a specific counter
• The name of the file to be generated for each interface.
• The access path to be used to integrate and deliver the files.

It is therefore possible for depositors and/or separate sites to set up different interface names and thus different names for files placed in separate directories. For instance, XSHP01 for depositor 01, with template XSHP01, and interface XSHP02 for depositor 02, with template XSHP02.

USAGE/INTERFACES/TEMPLATES

For all the interfaces via file exchange, the General tab is used to describe how Sage Warehousing reads the structure of the interface file in the interface template.

• its structure (delineated, fixed length or xml),
• the set of characters,
• the format of the dates,
• the type of decimal separator,
• the line and record separators,
• the character to be interpreted if there is no modification...

The second tab lists the fields in the SAGE Warehousing tables that need to be imported/exported.

The following elements are specified for each table: an action code "$" that will be equal to Create/Modify/Delete (values 1, 2 or 3), a separation code "/" that specifies the start of the fields of another table, for instance "E" (E for French Header)) or "L" (L for Line associated with a header), "P" for associated Parcels.

The structure of the template can be modified: adding or deleting a field within the same table of the template is quite possible. The positions of the framework should simply be recalculated via right click on the mouse ("Position adjustment", to be performed systematically in case of template modification).

It is strongly recommended to systematically transmit the identifiers of the action code; record type, site, depositor.

Definition of the Structure:
The structure of the information within a record is defined for each interface template:

• Field with a variable (or delineated) length
• It is the structure type used by default.
• The formats mentioned in the descriptions of the information structures correspond to the maximum formats of each field. The non significant characters (white or zeros) must be deleted.
• They correspond to the data format in the Warehousing database.
• The end of each field (except the last field in the record) is identified by a field separator (usually ";").
• In addition, each field can be surrounded with field delimiters (usually " " "); these field delimiters are not generated on export for the numerical fields and the date type fields.
• Fixed length fields
• The position and length of each field are fixed.
• There are no field separators or delimiters.
• The presentation and alignment rules of the information (especially the numerical fields) can be set up.
• The alphanumerical data are aligned on the left and complemented with blanks.
• The alphanumerical data are aligned on the right and complemented with zeros if necessary. The decimal separator is not transmitted.
• XML Field: the interface is managed in xml format.
• The codes and tags relating to table indicators are defined in column "Level"
• The codes and tags relating to the fields are defined in column "Tag"
• Record separator
• To enter a non-printable character, it is necessary to enter a '\' (back slash) followed by 3 numbers representing the ascii code of the character in decimal base.
  The following is often used:
• the line feed character (\010), that corresponds to the end of the line in Unix text files
• the combination of the two characters carriage return and line feed (\013\010)n that corresponds to the end of the line in Windows text files.
• It defines the separator between two records (data groups).
• To enter a non-printable character, it is necessary to enter a '\' (back slash) followed by 3 numbers representing the ascii code of the character in decimal base.
  The following is often used:
• the line feed character (\010), that corresponds to the end of the line in Unix text files
• the combination of the two characters carriage return and line feed (\013\010)n that corresponds to the end of the line in Windows text files.

Identifiers
Used to define the code allowing the identification of the record type transmitted at interface level. These codes are specified in standard according to the SAGE Warehousing requirements. They cannot be modified in standard.

 
Transcoding

• Set of characters
• ASCII (ISO 8859-1) is mostly used.
• UNICODE (UTF8) is also possible.
• UCS-2 ?
• Possible date formats: DDMMYY, DDMMYYYY, YYMMDD, YYYYMMDD.
  The chosen format is subsequently supposed to be DDMMYYYY.
• Format of the local menus
  A local menu is a data type refering to a predefined list of authorized values.
  Usually in interfaces, each value is identified via a numerical data that corresponds to the sequence of the value in the list.
  In this way, for a binary indicator (no/yes):
  The value "1" means "No".
  The value "2" means "Yes".
• Decimal separator
  When it is exchanged (it is not necessarily the case for a structure with a fixed field length).
  The point is used by default.
• Blank field symbol
  This symbol can be of importance in the event of modification imports. It makes it possible to mark the data included in the interface whose values should not be modified.
  The symbol "$" is usually used.
• Symbol CR + LF
  This symbol should be used to mark the line breaks in multi-line fields (for instance, comment fields) in a different manner from the record ends.
  The symbol "|~" is generally used.

Usage/Interfaces/Default values

Function "Default values"

This function is used for the interfaces on import and creation modes. It assigns default values to certain fields, and namely to compulsory values.
If L3 does not manage some compulsory information in Warehousing (entry mode, output mode...), it will transmit a "$" in the corresponding field, and the system will replace it with the default value that has been set up.
If a value is transmitted, it is taken into account, otherwise, the system checks if there is any default value to take into account, otherwise the entry processing is taken into account.
The detail of the correspondences between the interface and the window(s) where the default values need to be defined is given below:

Interfaces	Windows
ITM (Products and product containers)	OITM (Products) OITC (Product containers)
EIN (EI)	OEIN (EI Header) FTABEIL (EI lines)
INP (DI)	OINH (DI header) FTABINL (DI lines)
DLO (DO)	ODOH (DO header) FTABDOL (DO lines)
INISLO (location assignment)	OSLO (Locations)
INISKO (Stock initialization)	OAJM (Adjustments) DSRNDACM (Serial no. on adjustment)

Function "Default reception mode"

The function is used for the EIN (expected entries) interface. In the case where the reception mode is not sent by L3, a default reception mode is affected according to the EA mvt code.
This functionality can be activated with flag "Default reception modes" defined at depositor level (General tab).

For more information, refer to the corresponding function help.

Function "Default preparation mode"

This function is used for the interface DO (Delivery Orders). In the case where the preparation mode is not sent by L3, a default preparation mode is affected according to DO criteria (mvt code, Order customer, Company name, Carrier, Transport mode and number of existing DO lines).
It should be noted that the function also determines the DO management mode (palletization, Loading, Shipment, Remaining quantity, Release lead-time and Generic round)
This functionality can be activated with flag "Default preparation mode" defined at depositor level (General tab).

For more information, refer to the corresponding function help.

 In the case where the system cannot determine a defaut preparation mode, then the system tries to determine a mode through the "Default values" standard function. If not possible, then the interface fails.

Interface processing

The following topics will be broached:

• Launch interfaces
• Purge directories
• View the progress of all the interfaces
• the Interface batch task

Usage/Interfaces/Launching

The interface processings are launched manually or via recurring tasks (launched with a period to be set up), for a single interface or for all the interfaces. In the latter case, the interfaces are processed by flow type according to a sequence to be set up, and, on import for a given flow type, in the ascending order of the file numbers.

IMPORT
The import processing is subdivided into 2 stages:

• Stage 1: File import
  Consistency control of the structure with the template description.
  In the event of achieved consistency, the received file is stored in the "import destination" directory, the data are copied to dedicated tables by flow type and processed during stage 2.
  In the event of failed consistency, the file received is stored in the "import error" directory. The interface batch(es) is(are) labelled as "import errors" and cannot be recycled.
• Stage 2: Data integration
  Functional consistency control of data for each interface batch.
  In the event of achieved consistency, the updates are carried out, the batch is labelled as "processed".
  In the event of failed consistency, the batch is labelled as "integration error"; the list of detected errors is saved, the batch can be recycled or closed. An error detected on part of a batch (header or line) means that all the linked records are rejected.

EXPORT
The export processing is also subdivided into 2 stages:

• Stage 1: Loading of the interface tables
  These tables are loaded with the various triggering events (end of DO picking, validation of a storing list, etc.)
  The interface batches are then labelled as "to be processed".
• Stage 2: Generation of the interface file
  All the batches "to be processed" for a given flow generate a file.
  This file is made available in the "export" directory linked with the flow and copied to the "export backup" directory.
  The batches are labelled as "processed".

Usage/Interfaces/Purge of directories

This function is used to manually purge the interface files stored in the various directories, specified as parameter values (chapter INT) by mentioning a conservation period expressed in days.

Usage/Interfaces/Inquiry

A standard function is used for the inquiry and management of the interface batches. It provides a summarized view of the status of each interface depending on whether they are on input, output or both (input and output).
The following statuses are possible:

• To Process
  The batch will be integrated or exported with the next interface processing.
• Processed
  The batch has been integrated or exported.
• Import error
  The structure of one or all the batches of an import file is incorrect; the data of the file has not been integrated.
  Once the error has been identified and the corrective actions taken, the status can be changed to "Processed error".
• Integration error
  A "functional" error has been detected in the imported batch.
  After analysis of the error, the batch can be labelled as "To be processed" to be included in the next interface processing (the batch will be recycled) or as "Processed error".
• Export error
  An error occurred when creating the interface file (stage 2). It is not an error when generating the batch (stage 1).
• Blocked
  Decision made to manually block (any) faulty interface in order to extract it from the population of the faulty interfaces and process it at a later date.

An interface with the initial status "To be processed" can have the following statuses:

Clicking on the magnifier at the end of each interface line is used to zoom in on the details of these lines.

• The Interface tab displays a line by Interface and Status code. This makes it possible to quickly view any errors (especially concerning the imports).
• The Batches tab lists the corresponding batches for the previously mentioned interface.
• The Lines tab lists the fields of a previously selected batch.
• The Numbering button displays a summary of the exchange flows.

Operating principle:
1. Select the interface in the list displayed in the Interfaces tab.
Site, depositor, interface code, setup name are displayed. The interface status is also displayed.
2. Then view the detail of the batches of this interface in the Batches tab.
The reference is the batch identifier. It usually is the reference of the Expected Input, Direct Input, Delivery Order, Product code.
The number refers to the identification of each record. The file refers to the generated or integrated file. If it is not assigned, it means that the record has the status "To be processed".
The date and time of creation relate to the data integration date into the interface table. The date and time of modification relate to the integration of the data into the operating tables.
3. Finally view the details of the lines of the previously selected batch in the Lines tab

This screen also alllows these interfaces to be managed. In this way the "faulty" batches can be manually switched to the status "Processed error" or "To be processed" via right click on the batch in question.

Usage/Batch server/Task management, Interface batch task

The INTERFACE batch task is used to automatically manage the interface files (read of the interface directories, import and export of the interface files).

This batch task can be stopped/started externally to the Warehousing product thanks to the implementation of a cookie file system with the following rules:

1) Upon starting the INTERFACE batch task, addition of a cookie file in the directory of file ("/FIL/INTERFACE.run")
2) Following the placing of the following cookie file: "FIL/INTERFACE.stop" in the folder directory, the automatic stop of the task of the corresponding folder is only carried out after processing an entire cycle of the active interface setup in receipt/emission mode).
3) Following the placing of the following cookie file: "FIL/INTERFACE.kill" in the folder directory, the automatic stop of the task of the corresponding folder is carried out as soon as an interface batch has been completely processed.

Likewise, stopping the batch server by placing the following cookie file: "/SERVGX/FIL/kill" would previously stop the INTERFACE batch task.

Information complémentaire

Interface files

The names of the interface files are defined as follows:

• Root (maximum of 10 alphabetic characters)
  As a synonym of the interface flow, it is defined in the "parameter" table.
  Given the fact that this root identifies the interface flow in the interface tracking function and anomaly management function, it is important to use a consistent and meaningful codification.
  For instance:
  • 1 character "X" for the interfaces (L2 => L3)
  • 2 characters to identify the third-party system
  • 2 or 3 characters for the nature of the flow ("PRO" for the Products, etc.)
• Sequence number
  Concerning the interfaces (L2 => L3), the sequence number format is defined by means of a general parameter. Morevoer, it is possible to use only one counter for all the interfaces, or to define counters dedicated to each interface or each set of interfaces.
• Extension
  The extension "imp" is traditionally used for the import files and the extension "exp" for the export files.

Saving within an interface file

An interface files contains multiple records.
The record end separator is a parameter of the interface template.
Concerning 2-level interfaces such as the product interface (product and container levels) or the delivery order interface (request header and request line):

• Each level is marked with a clear "record type" information at the beginning of the record which is specified in the data structure descriptions.
• The dependence relation is expressed by the relative order of the records, with the "line" level records having to follow the "header" level record to which theyr are linked.
  The interface batch term is used to call a set of records relating to the same header record.

Structure of the exchange files

This data needs to be set up (see the Setup chapter).
Since the position and selection of the fields can be modified, this document is an example of structure of the files. On the other hand, the functional management rules associated with the fields are constant for the imports. The structure described in this document is the one of the delineated frames (as opposed to the fixed length frames). The record separator is the carriage return (not specified in each frame description).
 
Import action code

• ‘1' = Creation
• ‘2’ =modification
• ‘3’ = deletion
• ‘4’ = read
   

Checks are performed with respect to this code and other functional checks are run according to the context.
 
Management rules
 
 To delete a parent entity (a DO, a product, an EI or a DI), the header should be transmitted with the action code = ‘3’ = deletion (in this case the child entities will be deleted automatically).
 
 To delete a child entity (a DO line, a product container, an EI line, a DI line), the header should be transmitted with the action code = ‘4’ = read and the code of the line to be deleted = ‘3’ = deletion. To delete all the child entities, the parent entity should be deleted first.
 
To modify them, the same principle is applied. It remains nevertheless possible to modify certain fields without impacting others by transmitting the entity to be modified with an action code equal to ‘2’ = modification, and then specifying the code defined in the template in those fields that should not be modified.

To delete data on import, it is impossible to delete a parent entity (product for instance) if it is used by an associated entity (stock object, stock movement, etc.).

For creation or modification purposes, it is possible to assign default values to a non-transmitted field of an interface.
If part of a batch is rejected, the entire batch is not integrated. For example: if a DO line is rejected, the order as a whole will be rejected.

To modify data on import (headers and/or lines), if the information is transmitted, the content of the filed updates that of Warehousing.

To avoid updating data modified in Warehousing, it is possible to transmit a character in the field (to be set up) so as to specify that the field should not be modified.

To properly manage the modifications without changing templates, the same structure as on creation mode should be transmitted while specifying those data modified by L3. The other data are transmitted with the value "non modifiable fields".