System Summary
The gateway provides data integration between the V5 product range and other solutions. The gateway can both produce and receive data.
The gateway is highly flexible, providing rapid deployment with many different ERP and external systems, allowing you to efficiently integrate your entire factory.
This document serves as a detailed overview of how to use the various methods to import and export data. It also details each entity that can be imported and the possible fields for these entities.
The gateway can be accessed via a web-interface REST API utilizing JSON or XML or via direct file sharing with CSV or XML documents.
The V5 API provides access to a variety of methods for importing and exporting.
Importing is performed by the IntegrationImport module. Exporting is performed by the IntegrationExport module.
You can access these modules from the package explorer where you can see the available integration methods.
Each method description contains a tag which denotes whether it's a GET or POST request plus the URI for that given method.
It is advised that you test the connection initially by using a REST client.
Once the V5-API has been installed as a web-service (see installation notes), you can access these endpoints via a browser or REST client at:
http://{hostname:port}/{V5-API}/api
The IntegrationImport module has a path of /integrate/import/
The IntegrationExport module has a path of /integrate/export/
You can retrieve the version number by querying /integrate/version/
Each method has its own path listed in this document as URI, which can be appended to the above paths in order to execute the method.
The path for getUsers() is /users. An example of getting a list of users would be:
http://localhost:8080/V5-API/api/integrate/export/users
If the gateway is configured correctly, you should receive a list of users registered in the system. If something went wrong, you'll be provided with a response code and a reason why.
The list you will receive is in JSON format. You will also need to POST in JSON format. All of the fields and objects are defined in the database package, which you can find in this document through the package explorer.
Our website provides more information on the system. For the latest documentation and guides visit us at www.sgsystemsglobal.com.
Import
Files can be imported via two methods.
You can choose your file to use by right-clicking on the Control Center taskbar icon and choosing Gateway then Import File or you can place files into the
gateway/import directory.This is the approach to take if you are regularly performing imports. The gateway will process the files in the order in which they arrive in the directory.
Structure
Import files should abide by the structure defined in the column_defs folder. The header files are in `.csvh` format and can be opened with any text editor.
You can import a variety of entities into the database such as Commodities or Sales Order Lines. Each entity has a series of fields that define the object. Some fields are required while others are optional.
See the database package for a list of possible values.
Naming Convention
File names must contain the corresponding header file name in the column_defs folder. The name of the entity type should be prefixed on the file name and appended with a dash (-).
For example, Clients header file is called "client," so a valid file name would be
client-123.csv.If a file has already been imported before and still exists in the gateway directory's folders, it will be overwritten when subsequently imported.
Linking Entities
Entities can be linked when importing files in order to provide greater efficiency and allow a smaller number of files to be used in each process.
It is possible to define multiple entities in a single file as long as a link exists. For example, when importing a sales order line, you may also specify the sales order information at the same time and the gateway will dynamically generate it for you.
You can disable the ability for the gateway to dynamically create inner entities from the settings panel within the control center under "Insert Child Entities." It will still look up pre-existing links but it won't create them.
When specifying an object within a link, an underscore `_` can be used within the column definition. For example, a Formula code could be referenced as
Formula_Commodity_Code.Import Validation Levels
All data imported into the V5 system will be validated to protect the system. Validation can be set to different levels of strictness.
- WARN: If an error exists in a file and a line cannot be imported, the system will notify you but continue processing the rest of the file.
- ABORT: If an error exists in a file and a line cannot be imported, the system will abort the process and inform you of the error.
Export
Enabling export will allow for data to be placed into CSV-formatted files within the export directory.
Export can be achieved on demand or when data is changed, imported, or created. Each table in the system has an export icon that can be pressed to generate a file containing the data visible on the active table.
To enable regular exports, set the export interval to a number greater than zero and choose which entities you want exported.
Structure
Every entity has its own default export format. This displays all public data about the object and any key data from linked entities.
Utilizing the `.csvh` files in the export/order folder, you can specify which data to include and its order.
The naming conventions are the same as the import files and are listed in the database package. As with importing, it's possible to export multiple linked entities within a single file.
You can specify whether to include the header data in the export file by using the export headers checkbox.
Our website provides more information on the system. For the latest documentation and guides visit us at www.sgsystemsglobal.com.
| Package | Description |
|---|---|
| com.sgapi.config |
This package controls the configuration of the SG-API
The configuration is set once the service is running but can be altered to adjust the behavior of some algorithms
Once configuration is changed, a reboot is required
|
| com.sgapi.resources |
This package provides resources specific to the API that are used for particular data transmissions available through the endpoints
|
| com.sgapi.services |
This package provides endpoints for integrating data with the SG V5 System
Imports are handled within the IntegrationImport class
Exports are handled within the IntegrationExport class
|
| com.sgs.common.database |
This package is responsible for holding all of the objects that can be persisted in the SG V5 System.
|