AllergenLink

The ‘AllergenLink’ import endpoint can be used to quickly assign commodities to allergen groups within V5 Traceability.

This guide will focus on how to use this endpoint, both via CSV import and using JSON via the V5 API.

1. Default Allergen Groups
2. API Links
3. AllergenLink Field Guide
   1. Primary Keys
   2. Additional Fields
4. Example Dataset
5. Methodology
   1. 1. JSON – Import
      2. CSV – Import

The default V5 database features a number of the most common allergen groups, but this endpoint can be used to create additional ones if required. The standard allergen groups that are included can be seen in the screenshot below:

This endpoint is not intended to be used for commodity creation, this should always be done via the ‘Commodity’ endpoint.

To find out more about the definitions for this ‘AllergenLink’, and related database classes, please see the following link:

AllergenLink 

Allergen

For both import methodologies, the primary keys are:

Allergen_Allergen – the name of the Allergen Group (i.e. Wheat, Gluten etc.).

Commodity_Code – The unique code of the commodity to be assigned to the Allergen Group.

Other options here that we can add from the ‘Allergen’ database class are:

Allergen_TextColor – Allows for a RGB number input to assign a color to the Allergen Group. Note that this should be the same for all commodities within the same Allergen Group. Also note here that when importing colors using this method, the RGB numbers do not need to be separated by commas (e.g. 219 125 33 instead of 219, 125, 33).

For this piece we will be looking at a simple example dataset featuring 5 ingredients that might be used during production:

So here we will be assigning the following default allergen groups to these commodities. For the CSV imports we will also assign text colors at the same time:

• Flour – Wheat (red) & Gluten (purple)
• Cheese – Dairy (yellow)
• Eggs – Egg (green)
• Soybeans – Soy (blue)
• Almonds – Tree Nuts (orange)

‘AllergenLink’ import Endpoint/URI –

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

Endpoint Description

Samples:

Using the ‘AllergenLink’ endpoint, we can structure an import file for the above additions like so:

This sample JSON file can be downloaded here.

And once we have posted this to the system, we can see that all our commodities have been assigned to the correct allergen group, in this case the Almonds under ‘Tree Nuts’.

For CSV imports we first need to construct a header file for our imports.

Header/column definition filename: “allergenLink.csvh”

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

Import CSV filename: “allergenLink-datetime.csv”

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

Samples:

Header File:

An example header file can be seen below. Here we will be assigning our commodities to the defined allergen groups and also adding a color to the groups:

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. 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 import based on our requirements above would look like this:

Note again that we do not need the commas that might normally separate RGB values. This sample import file can be downloaded here.

We can then drop this file into our import folder as defined above, and once the import is complete we can already see that the allergen group text colors have been updated:

And if we examine each group we will see our desired allergens have been added: