Guides
Start typing to search…

Product Labelling

The May Contain labelling feature adds an additional layer of information to product endpoints, specifically regarding potential allergens or ingredients that products may contain. This label is used alongside the existing Contains label to indicate ingredients or allergens that could potentially be present, though not guaranteed. Any allergens or dietary requirements marked as "May contain ..." or "May be suitable for..." will be added to the relevant fields in the products. The feature is integrated into the product data sourced from a platform used for managing recipes and products.

Purpose

The primary purpose of the May Contain labelling feature is to:

  • Enhance product safety: By providing additional allergen or ingredient information for products, it helps display more comprehensive labels for consumers.
  • Support compliance: It assists partners in meeting regulatory requirements related to allergen disclosure.
  • Improve data integration: The feature allows partner systems, such as point-of-sale systems, to retrieve both Contains and May Contain data, enabling informed decision-making and accurate labelling at the consumer level.

Scope

This feature is applicable to any product management system that provides product and recipe data through an API endpoint. The system can retrieve Contains and May Contain data from Fourth, and in the future, a variety of integrated platforms, enhancing labelling information across multiple environments.

Description

Functionality Overview

The May Contain label is appended to product information retrieved from an external platform. This allows the partner system to display both definite and potential allergens or ingredients within the same data structures.
When a product or recipe is processed, the May Contain label is included as part of the product's metadata alongside the allergens, accessible through a products endpoint. This data can then be used by partner systems (such as POS or inventory management systems) to show more detailed ingredient and allergen information on consumer-facing labels.

Workflow

  • Data Retrieval: The system retrieves product and recipe data from the external platform via the products endpoint. This data includes Contains and May Contain labels.
  • Endpoint Processing: Once the product data is pulled, the labels are processed along with other product details (such as ingredient information, nutritional information , allergens, dietary).
  • Product Listing: The processed data, including Contains and May Contain labels, is made available through the product list endpoint and the product endpoint. Partner systems can display the information as needed.

Integration Example

When a product labelled as "May Contain Nuts" is processed through the system, both the Contains and May Contain labels ensure that the potential presence of allergens is communicated to the consumer.
In the Products/ProductList endpoints, there is a allergen field which out the allergens, for example:

"allergens": [
    "Contains Eggs / Egg Derivatives",
    "Contains Cereals that Contain Gluten",
    "Wheat",
    "Barley",
    "Contains Soya"
]

Label Implementation

Partners such as POS or retail systems can retrieve data—including the May Contain label—through the product endpoint and integrate it into their internal systems without additional configuration if they use a Kitchen Management System in Trac. The labels are visible within product listings, recipes, and ingredient data provided via the API. Note that may contain is not presented as a separate field but is included alongside the contains allergens.

Configuration Details

For each partner, a unique installation ID and config file (containing necessary credentials like usernames and passwords) are required to facilitate the connection between the partner’s system and the external platform.
To set these up the integration partner will need to tell us which platform they would want to use (e.g. Fourth). They will also need to send us their configuration details (e.g. location ID of the school, menu client ID, menu client password etc.).
The Trac service team will then switch on the partner’s installation, which will allow Trac to start retrieving and sending data. The configuration will differ based on the partner organisation's setup, including specific location identifiers, which must be provided before the data can be pulled successfully.

Implementation

Steps for Integration

  1. Configuration Setup: Ensure the installation ID and configuration are set up with the external platform. This includes:
  • Adding the partner’s installation ID.
  • Configuring required credentials (e.g., username, password) in the config file.
  • Location ID
  1. Accessing Endpoints: Once the configuration is complete, partners can access the Products and ProductList endpoints to retrieve the product list, including all ingredients, pricing, and labelling data.
  2. Using the Labels:
  • Pull product data from the Products and ProductList endpoints. The labels will be in the allergen / dietary fields in both endpoints
  • Use the May Contain and Contains labels as necessary for specific integration (e.g., labelling system, product display).
  1. Testing and Verification:
  • Partners should verify that the product data, including the May Contain label, is being retrieved correctly.
  • Ensure the labels are displaying correctly within the partner’s system (e.g., POS or consumer-facing labels).

Data Structure Example

This is what a product would look like from the products endpoint :

{
   "nutrition":[
      {
         "name":"Energy_kCal",
         "referenceIntakePercent":"1.553",
         "per100g":"64.222",
         "perServing":"31.06533"
      },
      {
         "name":"Energy_KJ",
         "referenceIntakePercent":"1.535",
         "per100g":"266.553",
         "perServing":"128.93617"
      }
   ],
   "menuDescription":"Coleslaw",
   "ingredientListString":"Broccoli, Cabbages & Cauliflower - Cabbage Savoy BBEach (Savoy Cabbage), Root Vegetables - Carrots Catering C2 PK 12.5kg (Carrot), Bulk Condiments - Light Mayonnaise (Ingredients:\r\n\r\nWater, Rapeseed Oil, Sugar, Spirit Vinegar, Modified Maize Starch, EGG Yolk Powder (1.5%), Salt, Stabiliser(Xanthan Gum), Acidity Regulator(Acetic Acid), Lactic Acid, Preservative(Potassium Sorbate), Colour(Mixed Carotenoids).\r\n\r\n\r\n\r\nContains : EGG), Onions & Leeks - Onions PK25kg (Cooking Onions), Other Salad - Spring Onions BB Bunch (Spring Onions), Herbs, Spices & Seasonings - Chef William Table Salt (Ingredients:\r\n\r\nSalt, Anti-caking Agent E535.\r\n\r\n), Herbs, Spices & Seasonings - Ground Black Pepper (Ingredients:\r\n\r\nGround Black Pepper).",
   "ingredients":[
      {
         "name":"Broccoli, Cabbages & Cauliflower - Cabbage Savoy BBEach",
         "unit":"each",
         "quantity":"2",
         "ingredientCost":"3.700",
         "ingredientPortionCost":"0.062"
      },
      {
         "name":"Root Vegetables - Carrots Catering C2 PK 12.5kg",
         "unit":"kilogram",
         "quantity":"1",
         "ingredientCost":"0.770",
         "ingredientPortionCost":"0.013"
      }
   ],
   "description":"Coleslaw",
   "dietary":[
      "Suitable for Vegetarians"
   ],
   "co2Emissions":"",
   "plu":"0006302",
   "shortName":"",
   "allergens":[
      "Contains Eggs / Egg Derivatives"
   ],
   "name":"Coleslaw 6302"
}

Endpoint Information

  • Product Endpoint: /api/{version}/orgs/{org_id}/products
  • Configuration File: Contains partner-specific credentials and installation ID.
  • Product Data Fields:
  • Product name
  • Ingredient list
  • Product list
  • Contains label
  • May Contain label
  • Tolerances
  • Pricing information
  • Note: An ingredient list details the specific components, like "sugar" or "water," used in an individual product. A product list is a collection of products—similar to a menu— Coleslaw for instance contains Mayonnaise, which would be listed in the product list (see example above).

Risks and Mitigations

To prevent miscommunication about product updates between external platforms and partner systems, regular synchronisation ensures consistency. Product updates automatically flow through the product endpoint. Trac has the ability to receive webhooks from Fourth when any product in a menu cycle updates, to which it will process and update the products every 10 minutes. If any products aren't synced by the webhooks, a pull function runs every hour to catch them, ensuring all updates are properly shared between systems.

Updated 1 day ago