Sales Orders

The integration of Sales Orders (SOs) between V5 Traceability and a customer’s ERP system allows for order details, order line items and scheduling information to be sent to V5 Traceability. V5 can also act as the data master in this case, and send orders created within the system to the ERP.

These orders can then be received via the V5 WMS software, after which information such as quantities that were picked and shipped, location, and container/pallet allocations can be sent back to the ERP.

More information on how the sales order module in V5 Traceability works, please see our module guide here.

1. Control Center Layout
2. API Links
3. Integration Template
4. Sales Order Field Guide
   1. Primary Keys
   2. Required Fields
   3. Preferred Fields
   4. Additional Fields
5. Methodology
   1. JSON – Import
   2. JSON – Export
   3. CSV – Import
   4. CSV – Export

In terms of how we can relate ‘Sales Orders’ and ‘Sales Order Lines’ to what we see in Control Center, we can see that the top panel here is for the Sales Orders, where customers, order & delivery dates, external reference numbers etc., can all be imported.

 

The lower panel is then where we can add our Sales Order Lines, holding data relevant to the commodities, quantities and cost of the order line items.

Using the V5 Gateway we can easily populate both panels, either separately or together.

The lower right panel holds data pertaining to where the items on the SO are picked from when the SO is processed. This data will form part of the exported data that we can receive back from the V5 Gateway.

To find out more about the definitions for the database classes that can be used for Sales Orders please see the following links:

Sales Orders

Sales Order Lines

Sales Log 

The integration template for Sales Orders can be downloaded here.

Primary Keys are the unique identifier for each table within the V5 API. For SalesOrders, this is:

salesOrder.orderNumber – the SO number.

For SalesOrderLines, the primary key is either:

salesOrder.orderNumber + commodity.code – the SO number along with the commodity to be ordered

or

lineID – For advanced purposes where the same commodity may appear on multiple lines, you can specify a line ID as a unique identifier instead the order number and commodity code. This is required if more than 1 line of the same commodity is on the order.

Other fields that are required by SG to populate a valid ‘SalesOrderLine’ in Control Center are:

quantity – the quantity of that commodity/product being sold.

Preferred fields serve to add more data to the sales order, and while not required, are useful when it comes to functionality within V5 Traceability. If using the ‘SalesOrderLine’ endpoint we would ideally add:

lineID – if not used as a primary key above, this field should be included.

commodity.code – if not used as a primary key above, this field should be included.

salesOrder.orderNumber – if not used as a primary key above, this field should be included.

salesOrder.customer.code – the unique code used to identify the customer.

salesOrder.placedDate – the date the order was placed.

salesOrder.deliveryDate – the expected delivery date for the order.

Note that for the last 4 of these points we are traversing to the ‘SalesOrder’ class from ‘SalesOrderLine’. If we were instead using the ‘SalesOrder’ class we could simply remove ‘salesOrder’ from the above 4 entries.

Additional fields can also be included, such as, for ‘SalesOrderLine’:

salesOrder.referenceNumber – any additional notes/references relating to the SO.

Given the nature of the ‘SalesOrder’ and ‘SalesOrderLine’, we can choose to import and manage data in a few different ways:

1. 1. We can use the ‘SalesOrder’ endpoint to import sales orders, and then, as we will see below, traverse to the ‘SalesOrderLine’ class to then include the component line items all in one file. This is the most logical way of importing whole orders as it requires only 1 set of header information and then the subsequent line items. Note that this is also the only endpoint that we can use to modify the header information for the sales order.
   2. We can use the ‘SalesOrderLine’ endpoint to modify or add lines once the order has been created. This can still be used to import whole orders, but is less efficient as each order line item would need to contain a nested reference to the sales order header (such as the order number). As indicated above, this endpoint cannot be used for making changes to the order header information (order number/delivery dates etc.).

Sales Order:

‘SalesOrder’ import Endpoint/URI –

http://host:port/V5-API/api/integrate/import/sales

Endpoint Description

For this sample import, we will be using the ‘SalesOrder’ endpoint, and structuring a basic import file, this could look something like this:

This sample JSON file can be downloaded here.

We can see why we would use the ‘SalesOrder’ endpoint for this format, given the ability of JSON files to hold nested data, allowing us to include indented ‘SalesOrderLine’ lists, and subsequently ‘Commodity’ datapoints in the import, which can be determined by using the SG API manual. For example, the ‘commodity code’ datapoint can be found by using the following path in the API manual:

We can build up the rest of our required datapoints using a similar pathfinding method.

Sales Order Lines:

‘SalesOrderLine’ import Endpoint/URI –

http://host:port/V5-API/api/integrate/import/sales_line

Endpoint Description

We can also use the ‘SalesOrderLine’ endpoint to add or edit lines of an existing order. We can also add Sales Orders using this endpoint, but it is important to remember that we can only edit a Sales Order header by using the ‘SalesOrder’ URI. Also note that the SO information would have to be nested here for each SO line.

We can see an example of a ‘SalesOrderLine’ JSON file below, where we will add another order line to order ‘SO-8471’ that we created above:

This sample JSON file can be downloaded here.

We can then see in Control Center that our order has been imported along with the additional line we just added. Note that information such as the placed/delivery date and reference number was imported from the original ‘SalesOrder’ file.

In terms of receiving files relating to sales order back from the V5 API, if we check the method summaries under the ‘IntegrationExport‘ service, then we have a few different options here:

Sales Orders:

Export Endpoint/URI –

http://host:port/V5-API/api/integrate/export/sales_orders

Endpoint Description

This endpoint will export full sales order JSON files using the sales order database class, and will include every sales order that has not already been marked as exported by the system. This will provide a return for each datapoint in the ‘SalesOrder’ class as well as including any picking information for shipped items.

An example JSON file of this type can be downloaded here.

Sales Order:

Export Endpoint/URI –

http://host:port/V5-API/api/integrate/export/sales_order/{ordernumber}

Endpoint Description

This endpoint will export full sales order JSON files using the sales order database class, but only for the order specified, and only if this order has not already been marked as exported by the system. As above, this will provide a return for each datapoint in the ‘SalesOrder’ class as well as including any picking information for shipped items.

We can see the start of an example export of this type below:

Sales Order Logs:

Export Endpoint/URI –

http://host:port/V5-API/api/integrate/export/sales_logs

Endpoint Description

This endpoint can be used to retrieve a list of sales order logs pertaining to events arising during sales order shipping. This makes use of the ‘SystemLog’ data class to provide transactional data such as system descriptors. The endpoint only provides this data for completed orders that have not been marked as exported.

An example JSON file of this type can be downloaded here.

Sales Order Log:

Export Endpoint/URI –

http://host:port/V5-API/api/integrate/export/sales_log/{id}

Endpoint Description

This endpoint functions the same way as the above ‘Sales Order Logs’ but can be used to return the information for a specific log number, as defined by the V5 system. As before this makes use of the ‘SystemLog’ data class to provide transactional data such as system descriptors. The endpoint only provides this data for logs from completed orders that have not been marked as already exported.

We can see the start of an example export of this type below:

We can also utilize a transactional and log endpoints to retrieve more relevant information about commodities and products sold on Sales Orders.

We have one Transactional/Generic endpoint we can use here:

Sales Transactions

Note that for CSV imports, we would normally be using just the ‘SalesOrderLine’ endpoint, allowing us to generate Sales Orders and their line items through the use of a single csv import.

Header/column definition filename: “salesOrderLine.csvh”

Completed header files should be placed in: “<installdir>\SG Control Center\gateway\import\column_defs”

Import CSV filename: “salesOrderLine-datetime.csv”

CSVs for import should be placed in: “<installdir>\SG Control Center\gateway\import”

Header File:

Header files will generally be compiled by SG Systems prior to CSV integrations taking place, but we can see a basic example of one we can use for sales orders below:

For further information on how we structure these files, please see the main integration page. This sample header file can be downloaded here.

CSV Import File:

We can then use the defined order of data points in the header to structure our import file. SG Systems can supply a template file for this, listing the data point for each column to make things clearer when populating the list. Note that this first row can be ignored by Control Center and so can be kept in the file when submitting for import.

Here we can see that we are aiming to create a similar order to what we created using the JSON methodology. This sample import file can be downloaded here.

With the import complete, we can see that this orders, along with the required line items, have been added to Control Center. Note that if the ‘Date Placed’ data is not included in the import, the date placed will reference today’s date.

When looking to export sales order information via this method, this would form part of a ‘SalesLog’ export. We can see the class definitions for this endpoint here.

Header/column definition filename: “SalesLog.csvh”

Completed header files should be placed in: “<installdir>\SG Control Center\gateway\export\order”

Export CSV filename: “SalesLog-datetime.csv”

CSVs for exports will be generated in: “<installdir>\SG Control Center\gateway\export”

This export would also need to be enabled in Control Center’s Gateway section. This would just be a case of checking the ‘Sales Order’ box and making sure to apply the setting and restart Control Center.

Header File:

We can use datapoints such as ‘user’, ‘timestamp’ and ‘quantity’ on this top ‘Sales Log’, level, but then we can also use the Sales Order and Sales Order Line pages to further build out the information that we require, such as the order number, the items sold, and where they were picked from. Note that here the ‘SalesOrder’ class should be accessed via the ‘Line’ class, as is shown in the example below

On a very basic level, our part of the ‘Sales Log’ header that deals with our Sales Orders could look something like this:

This sample header file can be downloaded here.

CSV Export File:

With our header in place and export enabled, we will subsequently get a return file for this order (along with any other previously unexported orders) that looks like this:

This sample export file can be downloaded here.