Purchase Orders

The integration of Purchase Orders 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. These orders can then be received via the V5 WMS software, after which information such as quantity received, location, and container/pallet allocations can be sent back to the ERP.

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

1. Control Center Layout
2. API Links
3. Integration Template
4. Purchase 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 Purchase Orders and Purchase Order Lines to what we see in Control Center, we can see that the top panel here is for the Purchase Orders, where suppliers, order & delivery dates, external order references etc., can all be imported.

 

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

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 PO are picked and stored when the PO is processed. This data will form part of the exported data that we can receive back from the Gateway.

To find out more about the definitions for these database classes please see the following links:

Purchase Orders

Purchase Order Lines

The integration template for Purchase Orders can be downloaded here.

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

purchaseOrder.orderNumber – the PO number.

For Purchase Order Lines, the primary key is either:

purchaseOrder.orderNumber + commodity.code – the PO 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.

Other fields that are required by SG to populate a valid PO line in Control Center are:

quantity – the quantity of that commodity being ordered.

Preferred fields serve to add more data to the purchase order, and while not required, are useful when it comes to functionality within V5 Traceability.

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.

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

purchaseOrder.supplier.code – the unique code used to identify the supplier.

purchaseOrder.placedDate – the date the order was placed.

purchaseOrder.deliveryDate – the set delivery date for the order.

unit – the UOM of the commodity being ordered.

Additional fields can also be included, such as:

purchaseOrder.notes – any notes for the PO.

cost – the cost (per unit) of the commodity being ordered.

Given the nature of the PurchaseOrder and PurchaseOrderLine , we can choose to import data in 2 ways:

1. We can use the ‘PurchaseOrder’ endpoint to import purchase orders, and then, as we will see below, traverse to the ‘PurchaseOrderLine’ 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 purchase order.
2. We can use the ‘’PurchaseOrderLine’ 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 purchase 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.).

Which of these endpoints we will use will largely depend on whether we use a JSON or CSV import. We can now look at these below.

Purchase Order:

‘PurchaseOrder’ import Endpoint/URI –

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

Endpoint Description

For this sample import, we will be using the ‘PurchaseOrder’ 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 ‘PurchaseOrder’ endpoint for this format, given the ability of JSON files to hold nested data, allowing us to include indented ‘PurchaseOrderLine’, 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.

Purchase Order Lines:

‘PurchaseOrderLine’ import Endpoint/URI –

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

Endpoint Description

We can also use the ‘PurchaseOrderLine’ endpoint to add or edit lines of an existing order. We can also add Purchase Orders using this endpoint, but we can only edit a Purchase Order by using the ‘PurchaseOrder’ URI.

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

This sample JSON file can be downloaded here.

We can then see in Control Center that our PO has been imported with the additional line we just added.

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

Purchase Orders:

Export Endpoint/URI –

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

Endpoint Description

This endpoint will export full purchase order JSON files using the purchase order database class, and will include every purchase order that has not already been marked as exported by the system. This will not include any receiving data but rather provide a return for each datapoint in the ‘PurchaseOrder’ class.

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

An example JSON file can be downloaded here.

Purchase Order:

Export Endpoint/URI –

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

Endpoint Description

This endpoint will export full purchase order JSON files using the purchase 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 not include any receiving data but rather provide a return for each datapoint in the ‘PurchaseOrder’ class.

Purchase Order Logs:

Export Endpoint/URI – http://host:port/V5-API/api/integrate/export/po_logs

Endpoint Description

This endpoint can be used to retrieve a list of purchase order logs pertaining to events arising during purchase order receipt, and unlike the types above, can be used to retrieve information such as what was received, how much, and where it was stored etc. This makes use of the ‘SystemLog’ data class to provide additional transactional data such as system descriptors. The endpoint provides this data for completed orders only, provided that they have not previously been marked as exported.

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

An example JSON file can be downloaded here.

Purchase Order Transactions:

Export Endpoint/URI –

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

Endpoint Description

This endpoint works in the same way as ‘Purchase Order Logs’ above, except that this endpoint will also provide data from orders that aren’t complete yet (i.e. orders in progress).

We can also utilize a transactional and log endpoints to retrieve more relevant information about commodities received on Purchase Orders.

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

Purchase Transactions

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

Header/column definition filename: “purchaseOrderLine.csvh”

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

Import CSV filename:“purchaseOrderLine-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 purchase 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 importing 2 different orders, one with 2 line items and the other with just 1. This sample import file can be downloaded here.

With the import complete, we can see that these orders, along with their 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 purchase order information via this method, this would form part of a ‘SystemLog’ export. We can see the class definitions for this endpoint here.

Header/column definition filename: “SystemLog.csvh”

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

Export CSV filename: “SystemLog-datetime.csv”

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

This endpoint can be used to extract a wide variety of data by traversing the available datapoints linked out from here.

Header File:

We can use datapoints such as ‘user’, ‘timestamp’ and ‘quantity’ on this top ‘System Log’ level, but then we can also use the ‘Purchase Order and ‘Purchase Order Line’ pages to further build out the information that we require, such as PO number, the commodity purchased, where this was stored etc.

On a very basic level, our part of the system log header that deals with our purchase orders could look something like this:

This sample header file can be downloaded here.

CSV Export File:

If we go ahead and receive the ‘Flour’ order line for order ‘PO-8472’ above, would give us the following export, telling us that this flour was booked in in 2x 250lbs quantities, and stocked in by ‘SG User’ in the ‘GEN’ stock location.

This sample export file can be downloaded here.