September 4th 2024 Release Note: RME | Import API for Ingredients and Recipes, New Properties Supported, New Validation

Summary

Select the release feature from the table below to be taken directly to that section of the release note.

Feature 1	Feature 2	Feature 3	Feature 4
New Properties Added to POST /recipestandard 'Raw Weight' properties have been added for two endpoints: - POST /recipestandard - POST /recipestandardexternal	New Endpoint for User Defined Units New import API to create 'User Defined Units' (units of measure)	POST/ingredients 'Variable Weighted' Property Supported POST /ingredients, 'Variable Weighted' can now be populated as 'true'. For an ingredient created via the import API, the 'Variable Weighted' will still default to 'false' but can now also be populated as 'true' if needed	Prevent Past Date for 'First Date Available to Order' for Alternate Ingredients UI and API validation added

Release date for all features: September 4th 2024

 

Import API:  Raw Weight Properties Added for POST /recipestandard and POST /recipestandardexternal

• Enabled by default? - Yes
• Set up by customer admin? - No
• Enable via support ticket? - No
• Affects configuration or data? - Yes

What's Changing?

Three 'Raw Weight' properties have been added to the POST payload for two standard recipe-related endpoints:

POST /recipestandard
POST /recipestandardexternal

Reason for the Change

To facilitate the import of recipes from third-party systems.

Customers Affected

All customers using the endpoints mentioned above.  

 

Release Note Info/Steps

Three new properties have been added to the POST payload for two endpoints:

POST /recipestandard
POST /recipestandardexternal

 

Properties

• Raw Weight calculation method
  • Data type:  String
  • Valid values:  Auto-calculate or Manual
  • Mandatory value
• Raw Weight quantity
  
  • Data type:  Decimal
  • Valid values:  Must be numeric, up to two decimal points
• Raw Weight UoM
  • Data type:  String
  • Valid values:  Must be existing RME UoM

 Reminder: On the RME Recipe Yield page, the Raw Weight calculation options are represented by a tick-box. If ticked, the 'auto-calculate' option has been selected. If unticked, the calculation method will be manual.

 

Sample payload with new properties in bold

[
  {
    "starChefKey": "0030702",
    "recipeName": "Roast Lamb Salad",
    "flagType": "3",
    "flagExpiryDate": "2019-10-20",
    "servings": 1,
    "recipeSets": {
      "set": [
        "drink",
        "food",
        "desserts"
      ]
    },
    "rawWeightCalculationMethod": "Manual",
    "rawWeightQuantity": "350",
    "rawWeightUOM": "gram",
    "suggestedPLU": "0016313",
    "recipeTax": "VAT",
    "suggestedSellPrice": "12.50"
  }
]

Fig.1 - Sample payload for POST /recipestandard with new Raw Weight properties in bold

 

Fig.2 - Raw Weight and Cooked Weight on recipe yield tab

 

Payload Validation Rules

1. Raw Weight calculation method (auto-calculate or manual) is a mandatory value in the payload. If this value is not in the payload, an error will be generated.
2. If Raw Weight calculation method is 'auto-calculate' and if Raw Weight Quantity and Raw Weight UoM are included in the payload, these values will be ignored. An error message will not be generated.
3. If Raw Weight calculation method is 'manual' and if Raw Weight Quantity is provided in the payload then Raw Weight UoM is mandatory and vice-versa.
4. If Raw Weight calculation method is 'manual', Raw Weight Quantity and Raw Weight UoM are still optional values in the payload. In this scenario, the recipe's Raw Weight will be 'null' and its calculation method will be set to 'manual'. This is allowed on the RME UI so the import API validation is aligned with this behaviour.

When created via the import API, a standard recipe's 'Cooked Weight Quantity' and 'Cooked Weight UoM' will default to 'calculate from raw weight'. 

Reminder: The Cooked Weight UoMs that are defined for a recipe will determine which UoMs are available when adding this recipe to another recipe. If Cooked Weight is not populated, then only the UoM 'serving' will be available when using a recipe as an ingredient within another recipe.

 

Import API:  New endpoint for 'User Defined Units'

• Enabled by default? - No
• Set up by customer admin? - No
• Enable via support ticket? - Yes
• Affects configuration or data? - No
• Roles affected: - if applicable

What's Changing?

New import API request is available to create 'User Defined Units' (Units of Measure)

Reason for the Change

To facilitate data migration from third-party systems.

Customers Affected

Optional. Access to this endpoint is available by request to Fourth's Support team.

 

Release Note Info/Steps

A new endpoint - POST /units -  is available for the creation of 'User Defined Units' ('Units' in this context are units of measure).

 Sample Payload

[
  {
    "uoMGuid": "2b0ac349-86bf-479f-965f-0a9d23a25b36",
    "unitName": "Green ladle, 3.5 fl ounces",
    "unitAbbreviation": "GRN LDL",
    "unitType": "Volume",
    "equatesToQuantity": 3.5,
    "equatesToUOM": "Fluid Ounces (UK)"
  }
]

Properties

• UoM GUID
  • Data type:  String
  • Valid values:  Must match an existing UoM GUID
  • Required for updates to existing User Defined units
• Unit Name 
  • Data type:  String
  • Valid values:  Must be unique
• Unit Abbreviation
  • Data type:  String
  • Valid values:  Must be unique
• Unit Type
  • Data type:  String
  • Valid values:  Weight, Volume or Other
• Equates to Quantity
  • Data type:  Decimal
  • Valid values:  Numeric, up to two decimal places
  • Mandatory value if Unit Type is Weight or Volume
• Equates to UoM
  • Data type:  String
  • Valid values:  Existing Weight or Volume UoM
  • Mandatory value if Unit Type is Weight or Volume

Payload Validation Rules

1. Unit Name is mandatory. Validation prevents creation of duplicate names.  Validation of unique name is checked against existing standard UoMs and User Defined units.
2. Unit Abbreviation is mandatory.
3. Unit Type is mandatory.
4. Equates to Quantity and Equates to UoM are mandatory if the Unit Type is Weight or Volume.

Rules for Updates to 'User Defined Units'

Unit name can be changed
Unit abbreviation can be changed
Unit type cannot be changed
Equates to Quantity and Equates to UoM cannot be changed

  These restrictions apply to updates via the import API and the UI.

 

Sample 'user defined unit' of type 'volume'

Unit Name: Green ladle, 3.5 fl ounces
Unit Abbreviation: GRN LDL
Unit Type: Volume
Equates to: 3.5 Fluid Ounces (UK)

 

Fig.3 - User Defined Units in the RME 'Admin' tab

 Standard metric and imperial weight and volume units of measure cannot be modified using this endpoint.

 

New Terms

'User Defined Units' are units of measure which are bespoke to an individual RME customer. Standard metric and imperial weight and volume units of measure are available to all customers.

Additional Resources

Recipe & Menu Engineering (StarChef) Import API | Fourth

 

Import API:  'Variable Weighted' Property Supported in POST/ingredients

• Enabled by default? - Yes
• Set up by customer admin? - No
• Enable via support ticket? - No
• Affects configuration or data? - Yes

What's Changing?

POST /ingredients, 'Variable Weighted' can now be populated as 'true'. When an ingredient is created via the import API, the 'Variable Weighted' value will still default to 'false' but with this change, it could also be populated as 'true' if needed.

Reason for the Change

To extend the import API so that 'catch weight' products, also called 'variable weighted' can be created via this method.

Customers Affected

All customers using the API request POST /ingredients.

When the global setting Variable weighted read-only for live ings is enabled, the 'variable weighted' value is hidden on the alternate ingredient. It is only visible on the parent ingredient UI.

 

Release Note Info/Steps

This change was delayed in its original release date so details can be found in the 7th August release note:

August 7th, 2024, Release Note: RME | Recipe Yield Auto-calculation, Nutrition Tab Hidden, POST /ingredients New 'Variable Weighted' Property

 

Additional Resources

Recipe & Menu Engineering (StarChef) Import API | Fourth

 

Import API and UI:  Alternate Ingredients, Only Current or Future Dates in 'Date First Available for Order' Field 

• Enabled by default? - Yes
• Set up by customer admin? - No
• Enable via support ticket? - No
• Affects configuration or data? - No

What's Changing?

In both the import API (POST /ingredientsalternates) and the UI, an alternate ingredient's 'Date First Available for Order' will only allow the current date or a future date. Past dates are no longer allowed for new ingredients. This change will not impact existing values.

Reason for the Change

To make it easier to identify an ingredient's 'orderable' status and then to update it automatically in Inventory.

Customers Affected

All customers using alternate ingredients.

 

Release Note Info/Steps

On the UI, this change will be available by default on the 'date picker' calendar which displays when Date First Available for Order is selected.

Fig.4 - A new alternate ingredient's 'Date First Available for Order' must be today's date or a future date

Import API:  POST/ingredientsalternates

For alternate ingredient updates via the API request POST /ingredientsalternates, the import validation will check:

• If 'firstDelivery' date in the payload is different from the existing date in the database
• If the date is different, the date in the payload must be the current or a future date
• If the date in the payload is in the past, an error will be generated
• If the date in the payload is the same as the existing date in the database, the date in the payload will be ignored and an error will not be generated

 Reminder:  If an ingredient's Date First Available for Order is in the future, the ingredient's status in Inventory and the Ordering app will be 'not orderable'.

 

Additional Resources

June 26th 2024, Release Notes: RME | Bulk Edit Categories Extended for Ingredients, Only Current or Future Dates in 'Available for Order' Date-Picker, Import API GET and POST/suppliers 'Supplier Type' Added