system.mes.batch.recipe.getRecipeBOM(masterRecipeLink)

Sepasoft MES Module Suite

getRecipeBOM(...)

Scripting Function added in MES 3.81.8 RC 1 and later

system.mes.batch.recipe.getRecipeBOM() returns the Bill of Materials for one validated master recipe. The dictionary holds the recipe header, the procedure, and the steps that contain BOM parameters or nested logic.

Values are the values configured on the master recipe. This is not the executed batch BOM. Use getBatchBOM() for a control recipe.

dateTimeFormat was added in MES 3.81.11 SP12.

Syntax

Copy Code

Python

system.mes.batch.recipe.getRecipeBOM(masterRecipeLink)
system.mes.batch.recipe.getRecipeBOM(masterRecipeLink, dateTimeFormat)

Arguments can be passed by position or by name.

Copy Code

Python

system.mes.batch.recipe.getRecipeBOM(recipeLink, dateTimeFormat='yyyy-MM-dd HH:mm:ss')

Required Parameters

Parameter	Type	Description
masterRecipeLink	MESObjectLink	Link to a saved master recipe. Get it with getRecipeLink(). The recipe must already be validated.

Optional Parameters

Parameter	Type	Default	Description
dateTimeFormat	String	yyyy-MM-dd HH:mm:ss.SSS	Pattern for every date-time string in the BOM, including parameter values and minimum and maximum dates. Added in MES 3.81.11 SP12. Pass '', None, or omit the argument to use the default. An invalid pattern raises IllegalArgumentException.

Date-time patterns use the gateway locale and time zone. Examples:

Pattern	Result shape
yyyy-MM-dd HH:mm:ss.SSS	2026-09-28 10:15:06.000
yyyy-MM-dd HH:mm:ss	2026-09-28 10:15:06
EEE, MMM d, yyyy h:mm a z	Mon, Sep 28, 2026 10:15 AM PDT
yyyy-MM-dd'T'HH:mm:ss.SSSXXX	2026-09-28T10:15:06.000-07:00

Return Value

Type	Description
Python dictionary	The master-recipe BOM. Convert it with system.util.jsonEncode() when you need JSON. The same structure can be passed to setBatchBOM().

Recipe dictionary

Key	Type	Description
Recipe_State	String	Recipe state.
Recipe_Name	String	Master recipe name.
Recipe_Version	Integer	User version.
Recipe_Scale	Float	Recipe scale.
Recipe_Quantity	Float	Recipe quantity.
Name	String	Procedure logic name.
LogicType	String	Procedure.
Parameters	List	BOM parameters on the procedure. Omitted when the list is empty.
Steps	List	Steps that have BOM parameters or nested logic. Omitted when the list is empty.

What is included

A parameter is included when it is one of these:

A Material In, Material Out, or Supplemental Equipment parameter.
A user parameter configured on the recipe.
Unit_Quantity or Work_Order on a Unit Procedure.

A phase step is included only when it has at least one of those parameters. A Unit Procedure or Operation step is included because it has nested logic. Start, Terminator, Transition, And Begin, And End, Or Begin, and Or End are omitted.

Step dictionary

Key	Type	Description
Step	String	Step name.
Phase	String	Phase name.
Type	String	Phase type, such as Timer or Unit Procedure.
Parameters	List	BOM parameters on the step. Omitted when the list is empty.
Sublogic	Dictionary	Nested Unit Procedure or Operation. Present on those step types. The nested dictionary uses Name, LogicType, Parameters, and Steps.

Parameter dictionary

Key	Type	Description
Name	String	Parameter name.
DataType	String	Built-in primitive types use the MES type name, such as STRING, DOUBLE, INTEGER, BOOLEAN, or DATE. Other types use the Ignition type name, such as String, Float8, or Int4.
Value	String, number, or Boolean	Configured value. Date-time values are strings in dateTimeFormat. Numbers and Booleans keep their native type. Other values are strings.
MinValue	String, number, or Boolean	Present only when the minimum differs from the parameter default. Dates use dateTimeFormat.
MaxValue	String, number, or Boolean	Present only when the maximum differs from the parameter default. Dates use dateTimeFormat.
UOM	String	Units. Omitted when empty.
Documentation	String	Parameter documentation. Omitted when empty.

A Material In, Material Out, or Supplemental Equipment parameter uses Name and Entries. The recipe has one entry. That entry has SubParameters, and each sub-parameter uses the parameter dictionary above. The sub-parameter Name includes the parent name, such as Mat_In.Lot_No.

Material sub-parameters included in the entry:

Name suffix	Meaning
Material_Name	Material definition
Material_Class	Material class
Lot_No	Lot
Lot_Status	Lot status
Target_Quantity	Target quantity
Actual_Quantity	Actual quantity
Lot_Equipment	Lot equipment
Lot_Equipment_Class	Lot equipment class
Lot_Manifest	Lot manifest
Lot_Manifest_Class	Lot manifest class
Material_UOM	Material units
Alternate_Group	Alternate group
Alternate_Priority	Alternate priority
Trace_Count	Trace count

Supplemental Equipment sub-parameters included in the entry:

Name suffix	Meaning
Equipment_Name	Supplemental equipment
Equipment_Class	Equipment class
Quantity	Quantity
Equipment_UOM	Equipment units
Trace_Count	Trace count

Scope

Available in Gateway and Client scripts.

Edge Cases

The recipe must be validated. Otherwise the call raises Exception: Unable to create recipe BOM because the recipe (<name>) has not been validated. Use validateRecipe() and save the recipe first.
A link that cannot be loaded raises Exception: Recipe not found or another error was encountered trying to load recipe (<link>). See gateway logs for more details.
An invalid dateTimeFormat raises IllegalArgumentException: Invalid date-time format: <pattern>.
Phase steps with no BOM parameters are left out. Nested Unit Procedure and Operation steps are still included.
Each resource has one Entries item. Multiple lots from a running batch are returned by getBatchBOM(), not by this function.

Example Usage

Copy Code

Python

# Minimal
recipeLink = system.mes.batch.recipe.getRecipeLink('Chocolate Batch')
bom = system.mes.batch.recipe.getRecipeBOM(recipeLink)
print system.util.jsonEncode(bom, 2)

Copy Code

Python

# Format date-time values, then walk materials under each step
recipeLink = system.mes.batch.recipe.getRecipeLink('Chocolate Batch')
bom = system.mes.batch.recipe.getRecipeBOM(recipeLink, 'yyyy-MM-dd HH:mm:ss')

print bom['Recipe_Name'], bom['Recipe_Version'], bom['Recipe_Quantity']
for step in bom.get('Steps', []):
	print step['Step'], step['Type']
	for param in step.get('Parameters', []):
		if 'Entries' in param:
			print '   material', param['Name']
			for entry in param['Entries']:
				for sub in entry.get('SubParameters', []):
					print '     ', sub['Name'], sub['Value']
		else:
			print '   ', param['Name'], param['Value']

Copy Code

Python

# Copy the recipe BOM onto a new batch
recipeLink = system.mes.batch.recipe.getRecipeLink('Chocolate Batch')
bom = system.mes.batch.recipe.getRecipeBOM(recipeLink)
system.mes.batch.queue.setBatchBOM('BATCH-001', bom)

Example Return

Copy Code

Python

{
    "LogicType": "Procedure",
    "Name": "Equipment Phase Manual",
    "Recipe_Name": "Equipment Phase Manual",
    "Recipe_Quantity": 1.0,
    "Recipe_Scale": 0.0,
    "Recipe_Version": 3,
    "Steps": [
		{
            "Step": "Mix",
            "Phase": "Unit Procedure",
            "Sublogic": {
                "Steps": [
	 	    {
                        "Phase": "Mix_Meat",
                        "Step": "Mix_Meat",
                        "Parameters": [
                            {
                                "DataType": "INTEGER",
                                "Name": "Mix_Time",
                                "Value": 600,
			      "UOM": "Minutes"
                            },
                        ],
                    },
                    {
                        "Phase": "Add Ingredient A",
                        "Step": "Add Protein",
                        "Parameters": [
                            {
                                "DataType": "MATERIAL_LOT_NUM",
                                "Name": "Protein.Lot_No",
                                "Value": ArrayOfLotNumbers[]
                            },
			  {
                                "DataType": "MATERIAL_NAME",
                                "Name": "Protein.Material_Name",
                                "Value": "Chicken"
                            },
			  {
                                "DataType": "MATERIAL_LOT_STATUS",
                                "Name": "Protein.Lot_Status",
                                "Value": "Uncooked"
                            },
                            {
                                "DataType": "MATERIAL_TARGET_QUANTITY",
                                "Name": "Protein.Target_Quantity",
                                "Value": 1000,
			      "UOM": "Lbs"
                            },
			  {
                                "DataType": "MATERIAL_ALTERNATE_GROUP",
                                "Name": "Protein.Alternate_Group",
                                "Value": "Alt 1"
                            },
			  {
                                "DataType": "MATERIAL_ALTERNATE_PRIORITY",
                                "Name": "Protein.Alternate_Priority",
                                "Value": 1
                            },
			  //Other Material_In sub-parameters may be included
			  {
                                "DataType": "MATERIAL_LOT_NUM",
                                "Name": "Alt_Protein.Lot_No",
                                "Value": "Meat7890"
                            },
			  {
                                "DataType": "MATERIAL_NAME",
                                "Name": "Alt_Protein.Material_Name",
                                "Value": "Chicken (Grade 2)"
                            },
			  {
                                "DataType": "MATERIAL_LOT_STATUS",
                                "Name": "Alt_Protein.Lot_Status",
                                "Value": "Uncooked"
                            },
                            {
                                "DataType": "MATERIAL_TARGET_QUANTITY",
                                "Name": "Alt_Protein.Target_Quantity",
                                "Value": 1000,
			      "UOM": "Lbs"
                            },
			  {
                                "DataType": "MATERIAL_ALTERNATE_GROUP",
                                "Name": "Alt_Protein.Alternate_Group",
                                "Value": "Alt 1"
                            },
			  {
                                "DataType": "MATERIAL_ALTERNATE_PRIORITY",
                                "Name": "Alt_Protein.Alternate_Priority",
                                "Value": 2
                            },
			  //Other Material_In sub-parameters may be included
                        ],
                    },
                    {
		       "Phase": "Add Ingredient B",
                        "Step": "Add Flavor",
                        "Parameters": [
			  {
                                "DataType": "MATERIAL_LOT_NUM",
                                "Name": "Flavor.Lot_No",
                                "Value": "Seasoning1234"
                            },
			  {
                                "DataType": "MATERIAL_NAME",
                                "Name": "Flavor.Material_Name",
                                "Value": "Mix Spices"
                            },
			  {
                                "DataType": "MATERIAL_LOT_STATUS",
                                "Name": "Flavor.Lot_Status",
                                "Value": "Good"
                            },
                            {
                                "DataType": "MATERIAL_TARGET_QUANTITY",
                                "Name": "Flavor.Target_Quantity",
                                "Value": 10
			      "UOM": "Lbs"
                            },
			  //Other Material_Out sub-parameters may be included
                        ],
                    },
                ]
            },
        },
        {
            "Step": "Cook",
            "Phase": "Unit Procedure",
            "Sublogic": {
                "Steps": [
                    {
                        "Phase": "Full Cook",
                        "Step": "Cook",
                        "Parameters": [
                            {
                                "DataType": "DOUBLE",
                                "Name": "Cook_Temperature",
                                "Value": 220.0,
			      "UOM": 
                            },
                            {
                                "DataType": "INTEGER",
                                "Name": "Cook_Time",
                                "Value": 120,
			      "UOM": "Minutes"
                            },
                            {
                                "DataType": "MATERIAL_LOT_NUM",
                                "Name": "Raw_In.Lot_No",
                                "Value": "Raw1234"
                            },
			  {
                                "DataType": "MATERIAL_NAME",
                                "Name": "Raw_In.Material_Name",
                                "Value": "Uncooked Chicken"
                            },
			  {
                                "DataType": "MATERIAL_LOT_STATUS",
                                "Name": "Raw_In.Lot_Status",
                                "Value": "Uncooked"
                            },
                            {
                                "DataType": "MATERIAL_TARGET_QUANTITY",
                                "Name": "Raw_In.Target_Quantity",
                                "Value": 1000,
			      "UOM": "Lbs"
                            },
			  //Other Material_In sub-parameters may be included
			  {
                                "DataType": "MATERIAL_LOT_NUM",
                                "Name": "Cooked_Out.Lot_No",
                                "Value": "Cooked1234"
                            },
			  {
                                "DataType": "MATERIAL_NAME",
                                "Name": "Cooked_Out.Material_Name",
                                "Value": "Cooked Chicken"
                            },
			  {
                                "DataType": "MATERIAL_LOT_STATUS",
                                "Name": "Cooked_Out.Lot_Status",
                                "Value": "Cooked"
                            },
                            {
                                "DataType": "MATERIAL_TARGET_QUANTITY",
                                "Name": "Cooked_Out.Target_Quantity",
                                "Value": 975,
			      "UOM": "Lbs"
                            },
			  //Other Material_Out sub-parameters may be included
                        ],
                    },
                ]
            },
        },
    ]
}

Related Functions

getRecipeLink() — Returns the MESObjectLink for a master recipe name.
validateRecipe() — Returns the messages that keep a master recipe from being valid.
getRecipeEBR() — Electronic Batch Record for a validated master recipe. Accepts the same optional dateTimeFormat.
getBatchBOM() — Bill of materials for a control recipe, including lots recorded during execution. Accepts the same optional dateTimeFormat.
setBatchBOM() — Applies a BOM dictionary to a batch queue entry.

Sepasoft MES Module Suite