Units of Measure
Your Guide to V5 Integration!
The integration of Units of Measure between V5 Traceability and a customer’s ERP system allows for the units of measure used by an ERP/third party system to be sent to V5 Traceability. These units can be then applied to warehousing and formulation/production within the V5 Traceability system.
The flexibility of the V5 Traceability system allows for a fully customised units setup, with the ability to set custom unit conversions for large quantities such as cases and drums, as well as being able to set commodity specific conversion rates. Specific conversion rates are especially useful for items with specific density, as we will see in the example below.
Only imports are available for both the ‘WeightUnit’ and ‘UnitCommodity’ classes that we will be looking at here; exports are unavailable via either the JSON or CSV methodologies.
More information on how units of measure work in V5 Traceability, please see our module guide here.
Table of Contents
1. Control Center Layout
In terms of how we can relate units and commodity specific conversion rates to what we see in Control Center, we can see that the top panel here is for entering our units of measure, with the bottom panel being for commodity specific conversion rates for the unit selected in the top panel.
If an entry in the lower panel is not present for a given commodity, then the system will revert to the conversion rate set in the top panel when a commodity is used with that unit. Once a commodity is added in the lower panel and a conversion rate added to it (the ‘UnitCommodity’) this then overrides the conversion rate in the top panel.
Using the V5 Gateway we can easily populate both panels.
2. API Links
To find out more about the definitions for the 2 database classes we will be using to add our units please see the following links:
3. Integration Template
4. Units Field Guide
4.1. Primary Keys
Primary Keys are the unique identifier for each table within the V5 API.
For WeightUnit, this is:
code – The unique code for the unit of measure (i.e. g, kg, lb, oz etc.)
For UnitCommodity, the primary keys are:
unit.code – the unique code for the unit of measure, as above.
and
commodity.code – The unique code for the commodity to apply the specific conversion rate to.
4.2. Required Fields
Other fields that are required by SG to populate a valid entry in Control Center are:
For WeightUnit:
conversionRate – The conversion rate for this unit, in relation to the unit with ID of 1 in the database.
For UnitCommodity:
conversionRate – the specific conversion rate for the specific commodity.
4.3. Preferred Fields
Preferred fields serve to add more information to the unit of measure (WeightUnit), and while not required, are useful when it comes to functionality within V5 Traceability.
description – description of the unit (kilos, pounds etc.)
4.4. Additional Fields
Additional fields can also be included for WeightUnit, such as:
notes – any additional notes for the unit
5. Methodology
Given the relatively simple nature of this class, we can use either JSON or CSV integration to import units to V5. We will look at this from the point of view of doing an initial import to bring any missing units into the system (weightUnit), after which we will then assign commodity specific conversions using the units in the system (UnitCommodity). Note again that no exports are available for either endpoint/class.
6. WeightUnit
6.1. JSON – Import
‘’WeightUnit’ import Endpoint/URI –
http://host:port/V5-API/api/integrate/import/unit
Samples:
For this sample import, we will be using the ‘WeighUnit’ endpoint to add pounds and ounces to the Control Center Units table shown above in the introduction. The JSON file to do this would look like this:
Note that the conversion rates will always be calculated from the default unit (i.e. the first unit in the units table), so here we are calculating this against kilograms (kg).
This sample JSON file can be downloaded here.
Using the above file, we can see that our new units have been created in Control Center.
6.2. JSON – Export
No JSON export is available for the ‘WeightUnit’ class.
6.3. CSV – Import
Header/column definition filename: “weightUnit.csvh”
Completed header files should be placed in: “<installdir>\SG Control Center\gateway\import\column_defs”
Import CSV filename: “weightUnit-datetime.csv”
CSVs for import should be placed in: “<installdir>\SG Control Center\gateway\import”
Samples:
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 units 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 creating the same new units as we did in the JSON example above, although using lower case letters for the units’ code in order to display this more clearly in Control Center.
This sample import file can be downloaded here.
With the import complete, we can see that once again these new units have been created.
6.4. CSV – Export
As with JSON exports, no CSV export is available for the ‘WeightUnit’ class.
7. UnitCommodity
7.1. JSON – Import
‘UnitCommodity’ import Endpoint/URI –
http://host:port/V5-API/api/integrate/import/unit_commodity
Samples:
For this sample import, we will be using the ‘UnitCommodity’ endpoint to add a specific unit conversion for litres of milk. We saw can see in Control Center above that litres would usually convert as a 1:1 ratio from litres to kg, i.e. 1 litre of water weighs 1kg. A litre of milk however would weigh slightly more than this (1.035kg), so we will see how we can set this up for a JSON import below.
So what we are telling the system here is that, when milk is used, the conversion used will be this 1.035, overriding the default conversion rate for the ltr unit.
This sample JSON file can be downloaded here.
Using the above file, we can see that our specific conversion rate for milk has been added to the lower panel of ‘litre’.
7.2. JSON – Export
No JSON export is available for the ‘UnitCommodity’ class.
7.3. CSV – Import
Header/column definition filename: “unitCommodity.csvh”
Completed header files should be placed in: “<installdir>\SG Control Center\gateway\import\column_defs”
Import CSV filename: “unitCommodity-datetime.csv”
CSVs for import should be placed in: “<installdir>\SG Control Center\gateway\import”
Samples:
Header File:
Header files will generally be compiled by SG Systems prior to CSV integrations taking place, but we can see an example of one we can use for commodity specific unit conversion 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 creating the same commodity specific unit conversion that we did in the JSON example above.
This sample import file can be downloaded here.
With the import complete, we can see that once again this new commodity specific unit conversion has been created.
7.4. CSV – Export
As with JSON exports, no CSV export is available for the ‘UnitCommodity’ class.
