RME Release Note: May 2021: Ingredient List 'Ready for Use' Tick Box, Updated Recipe Reports, API Updates, Site-linking Validation – Fourth & HotSchedules Customer Success Portal

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’.

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.

Fig.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).

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

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

Fig.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.

Fig.6 - Recipe Specification Sheet (Mains)

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.

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

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.

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.

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

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

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

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""

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

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""

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.

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

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