Skip to main content
Jump to
    Fourth Customer Success Portal
    • Updated

    RME Release Note: May 2021: Ingredient List 'Ready for Use' Tick Box, Updated Recipe Reports, API Updates, Site-linking Validation

    What’s Changing?

    • Ingredient List: Ready for Use, confirmation tick box for ingredient
    • Updated recipe reports
    • API: New POST/GET requests for ingredient ‘Shelf Life’ fields
    • API: Access to endpoints related to Natasha’s Law functionality
    • API: POST/ingredients, validation so that Supply Quantity UoM and Unit Size UoM match
    • Site-linking validation to allow ‘0’ cost price Ingredients

    Release Date: 18th and 19th May 2021.

    Reason for the Change

    Ingredient List (related to Natasha’s Law functionality), Ready for Use confirmation
    To give customers a means of explicitly confirming that an ingredient is ready for use in a recipe’s ‘Ingredient List’.

    Updated Recipe Reports
    General enhancements.

    API: New POST/GET requests for Ingredient ‘Shelf Life’ fields
    To support customers using the import API to manage ingredient data.

    API:  Access to Endpoints Related to Natasha’s Law Functionality
    To reduce confusion by only enabling access to these endpoints when the functionality has been globally enabled for an Organisation.

    API:  POST/ingredients, validation so that Supply Quantity UoM and Unit Size UoM match
    To align import API validation with validation used in the RME user interface.

    Site-linking validation to allow ‘0’ cost price Ingredients
    To reduce friction for Inventory customers for whom ‘0’ cost price ingredients could be valid.

    Customers Affected

    Ingredient List, Ready for Use Confirmation:  All customers using this functionality
    API changes:  Impacts customers using those particular endpoints
    Site-linking Validation:  All Inventory customers

     

    Release Notes

    Ingredient List:  Ready for Use Confirmation – New Tick Box for Ingredient

    A new Ready for use tick box has been added to the ingredient field Ingredient List (located via Ingredients > Nutrition > Ingredient List) – see Fig.1.

    In the example shown in Fig.1 the ingredient ‘Egg Size 3 Free Range’ is used in the Recipe ‘Egg White’. 

    Fig1.png
    Fig.1 – ‘Ready for use’ tick box (unticked) for ngredient’s Ingredient List field

    When this box is not ticked, any recipes using the ingredient will not have their Ingredient List - Automatically generated - text field populated.         

    Fig2.pngFig.2 – Recipe Ingredient List cannot be automatically generated if all ingredients are not ‘ready for use

    When one or more recipe ingredients have the Ready for use box unticked, a message will be displayed in the recipe’s automatically generated Ingredient List:  “List could not be automatically generated because some ingredients have not been enabled for use for this list” – as shown in Fig.2.

    When the box is ticked and a weight value is present for the ingredient's pack size (or one of its conversions), any recipes using this ingredient will have their Ingredient List - Automatically generated - text field populated (provided all other recipe ingredients also meet this data requirement).

    Fig3.png
    Fig.3 – ‘Ready for use’ tick box (ticked) for ingredient’s Ingredient List field

    Fig4.png
    Fig.4 – Recipe Ingredient List is automatically generated if all ingredients are ‘ready for use’ and have a weight value

    • If one or more recipe ingredients are missing weight and/or a Ready for use tick, the relevant error message(s) will be displayed in the recipe’s automatically generated Ingredient List
    • If the Ready for use tick box is ticked (=yes) then unticked (=no), this is the expected recipe field behaviour:
      • If the recipe Ingredient List was automatically generated when the tick box was enabled (ticked), when the tick box is 'disabled' (unticked), a message will be displayed that states “List could not be automatically generated because some ingredients have not been enabled for use for this list”
    • When a new ingredient is created and the Ingredient List functionality is enabled, the tick box will be 'off' by default
    • For ingredients that exist before the functionality is enabled, the tick box will be unticked by default when the functionality is enabled
    • When an ingredient is copied, the tick box for the copy will be the same as the original record and the Ingredient List from the original will also be copied. The user can then change these values for the copy if required
    • When a new ingredient is created and the Ingredient List functionality is not enabled, the tick box will be 'off' by default and will not be populated in the database or API responses
    • The Ready for use tick box can be set manually by the user in the user interface and via the import API endpoint POST /ingredientlist
    • The system will not change the tick box’s value - there are no triggers that will automatically set it back to a default value when other actions are taken

     

    Import API > POST /ingredientlist > “ReadyForUse” property

    The ‘ready for use’ property has been added to this endpoint. Yes = 'enabled', No = 'disabled'.  This property is mandatory for this endpoint.  It must be present in the payload.

     

    Sample payload

    [
      {
        "StarchefKey": "3422",
        "FullIngredientList": "Orange Juice, Vitamin C, Calcium",
        "LabelDescription": "Fortified Orange Juice",
        "ReadyForUse": "YES"
      }
    ]

     

    Validation

    If a payload is submitted and the "ReadyForUse" property is not in the payload, an error will be generated.

    Error message:  “Ready for Use Flag is a mandatory value.  Valid values are 'Yes' or 'no'.”

    If the "ReadyForUse" property is included in the payload but is an empty string, an error will be generated.

    Error message:  “Ready for Use Flag is a mandatory value.  Valid values are 'yes' or 'no'.”

    If the "ReadyForUse" property is included in the payload but is an invalid value, an error will be generated.

    Error message:  “Ready for Use Flag is a mandatory value.  Valid values are 'Yes' or 'No'.”

     

    Export API > GET /ingredientlist > “ReadyForUse” property has been added to the response.

     

    Sample Response

    [
      {
        "IngredientName": "Calcium Plus Vitamin D (No Pulp) Orange Juice",
        "StarchefKey": "3422",
        "ParentGuid": "ce769cd4-c84a-4144-84f4-4ac912646152",
        "AlternateGuid": "aa869cd4-c84a-4144-84f4-4ac912646152",
        "FullIngredientList": "Orange Juice, Vitamin C, Calcium",
        "LabelDescription": "Fortified Orange Juice",
        "ReadyForUse": "YES"
      }

     

    Report

    Food Information (Amendment) (England) Regulations 2019 Ingredient Data

    Fig5.pngFig.5 - 'Ready for Use' status (Yes/No) has been added to the above ingredient report

     

    Updated Recipe Reports

    Two previously bespoke recipe reports are now available for all customers. They are called:

    • Recipe Specification Sheet (Mains)
    • Recipe Specification Sheet Multi-image

    To have these reports enabled, please raise a request via Fourth’s Customer Success Portal.

    Fig6.png
    Fig.6 - Recipe Specification Sheet (Mains) 

    Fig7.png
    Fig.7 - Recipe Specification Sheet Multi-image

     

    API:  New POST/GET requests for Ingredient Shelf Life fields

    Two new endpoints have been added for Ingredient Shelf Life fields.

    Please note: Access to these endpoints requires a username and password.  Additionally, the POST endpoint must be configured.  Please contact Fourth’s Support team via the Customer Success Portal if access is required.


    POST /ingredientshelflife

    This endpoint will allow partial updates. If one of the properties is not included in the payload, it will not be impacted by the payload processing. This will allow users to submit only those fields in the payload that they want to update.

     

    Sample payload

    [
      {
        "ShelfLife": "12",
        "ShelfLifeTwo": "11",
        "ShelfLifeThree": "7",
        "ShelfLifeFour": "15",
        "MinShelfLifeIntoUnit": "22",
        "MinShelfLifeDays": "5",
        "SupplierName": "Dairy",
        "SupplierCode": "B365",
        "StarChefKey": "0030702"
      }
    ]

     

    The fields in the payload correspond to these fields (see Fig.8) in the RME user interface. Please note that if these fields are not currently visible for an organisation, they can be configured on request to Fourth’s Support team: Customer Success Portal.

    Fig88.png
    Fig.8 – Ingredient Shelf Life fields (Ingredients > Supply Details > Shelf Life fields)

    Validation

    Ingredient identifier logic will follow the usual patterns and error messages. Ingredients can be identified either by Supplier Name, Supplier Code, or StarChef Key. If all three values are included in the payload, the StarChef key is used to identify the ingredient for update, and Supplier Name and Supplier Code will be ignored.

    Shelf Life Field value can only be populated with an integer (no decimals).

    If an empty string is submitted for one of the properties in the payload, an error will be generated.

    Error message: “This property must be populated with an integer.”

    If a Shelf Life field is populated, the value cannot be changed to ‘null’. ‘0’ is a valid value.

    Validation logic will check the organisation’s global setting for min/max shelf life field value(s). If the value in the payload is outside the min/max value, an error will be generated.

    Error message:  “The value should be between [min - max] value.”

     

    GET /ingredientshelflife

    Sample response
    [
      {
        "ShelfLife": "12",
        "ShelfLifeTwo": "11",
        "ShelfLifeThree": "7",
        "ShelfLifeFour": "15",
        "MinShelfLifeIntoUnit": "22",
        "MinShelfLifeDays": "5",
        "SupplierName": "Dairy",
        "SupplierCode": "B365",
        "StarChefKey": "0030702"
      }
    ]

     

    Query Parameters

    ProductId = Response will return product associated with this product key (please note: this field is also called StarChef key in the APIs)
    Guid = Response will return product associated with this Ingredient guid
    Group guid= Response will return records associated with the specified group

     

    API: Access to Endpoints Related to Natasha’s Law Functionality

    Endpoints that have been created to support functionality related to a change in UK legislation called Food Information (Amendment) (England) Regulations 2019, also known as Natasha’s Law, will return a response (GET requests) or accept a payload (POST requests) only if the Ingredient List functionality has been enabled for an organisation.

    When the functionality is disabled, a ‘403’ response will be returned when requests are made to these endpoints.

    Endpoints impacted by this are:

      • POST /ingredientlist
      • GET /ingredientlist
      • GET /recipeingredientlist
      • get /Ingredients/{guid}/fullIngredientListHistory
      • get /Ingredients/fullIngredientListHistory
      • get /Recipes/{guid}/fullIngredientListHistory
      • get /Recipes/fullIngredientListHistory

    Fig8.png

    Fig.9 - ‘403’ Response code when accessing the above endpoints when Ingredient List functionality is disabled

     

    API:  POST /ingredients, validation that Supply Quantity UoM and Unit Size UoM match

    New validation has been introduced for the POST/ingredients endpoint. This validation will mimic the existing ingredient validation used in the RME user interface. 

    This validation is typically relevant to organisations that use Fourth’s Inventory solution.

    When users are manually updating ingredients, certain constraints are imposed to ensure that there is unit of measure (UoM) alignment between ‘Supply Quantity UoM’ and ‘Unit Size UoM’. These same constraints will now apply to the import API validation for the endpoint POST/ingredients.

    Important reminder: This endpoint assumes a complete payload and any values not specified within the payload will be set to Null/Empty.

    1. Supply Qty UoM ("SupplyQuantityUnit") and Unit Size UOM ("UnitSizeUom") must be same UoM type:  weight, volume or other

    Example:  If Supply Qty UoM = KG (or other weight UoM) then Unit Size UoM must = a weight UoM
    Example:  If Supply Qty UoM = Fl (oz) US (or other volume UoM), then Unit Size must = a volume UoM
    Example: For UoM of type = 'other', the UoMs must match exactly, e.g. 'each' or 'slice' or 'bottle. 

    Sample partial payload - Supply Qty UoM and Unit Size UoM values in POST /ingredients payload

    [
      {
        "IngredientName": "Pastry Puff",
        "IngredientGuid": "5FD5ED46-C254-4002-9EF4-6513C623CD0D",
        "ParentIngredientProductName": "Puff Pastry",
        "SupplierName": "Bread Factory",
        "SupplierCode": "B365",
        "StarChefKey": "0030702",
        "InternalCode": "1007",
        "SupplyQuantityNumber": "5",
        "SupplyQuantity": "1",
        "SupplyQuantityUnit": "kilogram",
        "CostPrice": "20.16",
        "IngredientSets": {
          "Set": [
            "food",
         ]
        },
        "IngredientType": "Food",
    …..
        "UnitSizeNumber": "1",
        "UnitSizeUom": "kilogram",
        "UnitSizeUomDescriptor": "",

     

    If a payload is submitted with mismatched "SupplyQuantityUnit" and "UnitSizeUom", an error will be generated.

    These properties correspond to the fields in the RME user interface shown below in Fig.10.

     

    Fig9.png
    Fig.10 – Supply Qty UoM and Unit Size UoM (Ingredients > Supply Details)

    1. For organisations using Inventory and RME ‘catch weight’ functionality, the dependency between Supply Qty UoM and Unit Size UoM is changed for ‘catch weight’ ingredients (when global setting Apply UoM restriction when Variable Weighted Equals True =  true and ingredient, variable weighted = true). 

    For ‘catch weight’ ingredients, the UoM dependency is between Unit Size UoM and Invoice UoM. Unit Size UoM and Invoice UoM must match. For the configuration mentioned above, the only UoMs available for Unit Size and Invoice UoM are KG or LB. 

    Example:  If Unit Size = KG then Invoice UoM = KGM

    Example:  If Unit Size = LB then Invoice UoM = LB 

                                                      

    Fig10.png
    Fig.11 – Supply Qty UoM and Unit Size UoM for a ‘catch weight’ ingredient (Ingredients > Supply Details)

     

    1. If global setting Supply Quantity read-only for Live Ingredients is enabled, existing ingredients in 'live' ingredient sets cannot have these values updated via import API:

    1. ""SupplyQuantityNumber""
    2. ""SupplyQuantity""
    3. ""SupplyQuantityUnit"" 

    Fig11.png

    Fig.12 – Supply Quantity Number, Quantity and Unit in RME UI

     

    1. If global setting Unit Size read-only for Live Ingredients is enabled, existing ingredients in 'live' ingredient sets cannot have these values updated via import API:

    1. ""UnitSizeNumber""
    2. ""UnitSizeUom""

    Fig12.png

    Fig.13 – Unit Size Number and Unit Size UoM in RME UI

     

    Site-linking Validation to Allow ‘0’ Cost Price Ingredients

    Validation has been changed to allow ‘0’ (zero) cost price ingredients to be synchronised with Inventory via site-linking.

    This validation is only relevant to organisations that use Fourth’s Inventory solution.

    Fig13.png
    Fig.14 – Previously, site-linking validation stopped the synching of ingredients with ‘0’ cost price

    Fig14.png
    Fig.15 – Site-linking validation now permits the synching of ingredients with ‘0’ cost price

     

    Related articles

    Comments

    Please sign in to leave a comment.