Commodities

The integration of Commodities (Ingredients/Packaging/Raw Materials/SKUs) between V5 Traceability and a customer’s ERP system allows for commodity details, such as costs, units, default expiry times etc. to be sent to V5 Traceability.

1. Control Center Layout
2. API Links
3. Integration Template
4. Commodities 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 Commodities to what we see in Control Center, we can see that we only have a single panel to populate here, the main commodities window.

 

Using the V5 Gateway we can easily populate the data here using a single endpoint.

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

Commodities

The integration template for Commodities can be downloaded here.

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

code – The unique identifying code for each commodity.

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

units.code – The default stocking UoM of the commodity.

type – The type of commodity (ingredient (0), formula (1), or packaging (2)).

recordStock – Whether the usage of this commodity should be tracked by V5 Traceability (not recorded (0) or recorded (1)).

Preferred fields serve to add more information against the commodity in question, and while not required, are useful when it comes to added functionality within V5 Traceability.

description – The description of the commodity.

bulkUnit – The bulk unit of the commodity (e.g. ‘Bag’ or ‘Box’).

bulkQuantity – The amount of the default UoM (units.code) of the commodity goes into the bulk unit above (e.g. ‘20’ for this, and ‘Bag’ entered for the bulkUnit, with a default unit of ‘lb’ means in 1 Bag of this commodity there are 20lbs).

Additional fields can also be included, such as:

cost – The default cost (per unit) of the commodity.

defExpiryDays – Default number of days from receipt that an inventory item of this commodity type will be set to expire

gtin –  The GTIN of the commodity.

Given that we are only using a single endpoint for this object class, we can make use of the ‘commodity’ endpoint for both JSON and CSV imports and exports. We can now look at this below.

Commodity:

‘Commodity’ import Endpoint/URI –

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

Endpoint Description

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

This sample JSON file can be downloaded here.

We can see here an example of using nested classes related to the ‘Commodity’ endpoint. In this case we have included the indented ‘units’ and ‘bulkUnit’ datapoints, allowing us to define both the default UoM of the commodity as well as its bulk unit. Since both of these make use of the ‘WeightUnit’ class, we can use the V5 API manual to guide us to these datapoints by using the following path:

We can build up the rest of our required datapoints using a similar pathfinding method to traverse to additional classes such as ‘Location’ or ‘Container’ as required.

If we were to import the example file above, we will see in Control Center that our commodity has been imported.

In terms of receiving files relating to commodities back from the V5 API, if we check the method summaries under the IntegrationExport class, we have 2 different options here:

Commodity:

Export Endpoint/URI –

http://host:port/V5-API/api/integrate/export/commodity/{code}

Endpoint Description

This endpoint will export a JSON file with all related information for a specific commodity. If we run this request using the commodity we have just imported, we will get a file that looks something like this:

An example JSON file can be downloaded here.

Commodities:

Export Endpoint/URI –

http://host:port/V5-API/api/integrate/export/commodites/{all}

Endpoint Description

This endpoint will export a JSON file that includes a list of all the related information for all commodities in the system depending on the value of the {all} field. If this is ‘true’ then we will pull all commodities, whereas if ‘false’ then we will just get a return for new commodities (i.e. commodities that are not marked as already exported).

If we run this request as true , we will get a file that looks something like this:

An example JSON file can be downloaded here.

Header/column definition filename: “commodity.csvh”

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

Import CSV filename: “commodity-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 commodities 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.

An example csv import file using the header above could look something like this:

This sample import file can be downloaded here.

With the import complete, we can see that these commodities have been added to Control Center.

When exporting commodities using this method then we would use the same class definitions as we did for imports, which we can find here.

Header/column definition filename: “commodity.csvh”

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

Export CSV filename: “Commodity-datetime.csv”

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

This export would also need to be enabled in the Control Center’s Gateway section. We can choose here to export just ‘Ingredients’ (ingredients/packaging), or formulas, or both. Here we will just look at exporting ‘Ingredients’ :

Header File:

From here it would be a simple case of structuring our export header file to suit what information we want to receive back from the system.

We could structure it in a very similar way to how we structured the import header:

This sample header file can be downloaded here.

CSV Export File:

With the above header in place, we would receive a return csv for our recent imports that would look something like this:

This sample export file can be downloaded here.