batch.queue.addEntry(...)

Sepasoft MES Module Suite

queue.addEntry(...)

Overview

Adds a new batch to the batch queue for later execution. You pass a Batch Master Recipe or Batch Formula link plus a unique batch ID; the gateway resolves the target process cell, builds the control recipe (including optional unit assignments and batch parameters), and returns a BatchQueueEntry. In Enterprise deployments, the request is routed to the gateway that owns the equipment for the resolved process cell.

For enterprise, see Enterprise Batch Queue Management.

Syntax

system.mes.batch.queue.addEntry(
	masterRecipeOrFormulaLink=recipeOrFormulaLink,
	batchID="UNIQUE_BATCH_ID"
)

system.mes.batch.queue.addEntry(
	masterRecipeOrFormulaLink=recipeLink,
	batchName="Display Name",
	batchID="UNIQUE_BATCH_ID",
	priority=10,
	scale=1.0,
	quantity=100.0,
	unitAssignments={"Unit Procedure 1": "Enterprise\\Site\\Area\\Process Cell\\Unit 1"},
	batchParameters={"Param1": 10, "Param2": True},
	processCellPath="Enterprise\\Site\\Area\\Process Cell"
)

Parameters

Required

Parameter	Type	Required	Description
masterRecipeOrFormulaLink	MESObjectLink	Required	Link to a Batch Master Recipe or Batch Formula to execute. Must not be None. If you use a formula link, the formula must be valid and its recipe user version must match the master recipe. Version specific: As of MES 3.81.11 RC1 MESObjectLink can reference a BatchMasterRecipe or a BatchFormula.
batchID	String	Required	Unique identifier for this batch. Cannot be blank. Must not match any batch currently in the queue or any batch already executed (historical use of the ID is rejected).

Optional

Parameter	Type	Required	Default	Description
batchName	String	Optional	Master recipe name	Human-readable batch name. Multiple queue entries may share the same name. If omitted or blank, the master recipe name is used. Version specific: As of MES 3.81.10 SP7 and later, the parameter batchName is optional.
priority	Integer	Optional	50	Used for reference and by the allocation manager. Lower values mean higher priority (product documentation describes 1 as highest priority). If omitted, the runtime applies the default priority constant (50).
scale	Double	Optional	1.0	Optional scale factor for recipe calculations.
quantity	Double	Optional	1.0	Batch size; used in recipe calculations and by the allocation manager (e.g., unit capacity checks).
unitAssignments	PyDictionary	Optional	None	Maps sub-logic step names (unit procedure steps in the master recipe) to unit equipment: each value is either a String equipment path or an MESObjectLink to a MESUnit. Keys must match step names that exist with sublogic on the recipe; values must not be None. Ex: {'Unit Procedure 1':'Enterprise\Site\Area\Process Cell\Unit A'}
batchParameters	PyDictionary	Optional	None	Parameter name → value pairs applied to the procedure logic after the control recipe is created. Values must be Serializable types suitable for batch parameters.
processCellPath	String	Optional	(resolved)	Equipment path to the target MES Process Cell. Use when defining batches from an Enterprise context so the path aligns with where the recipe syncs. If omitted, the process cell is inferred from unitAssignments, the master recipe’s associated equipment, or (on a server with exactly one process cell) that cell.
masterRecipeLink	MESObjectLink	Optional	—	Deprecated. Use masterRecipeOrFormulaLink instead. Still accepted as a fallback when masterRecipeOrFormulaLink is not supplied.

Returns

Scope / Availability

• Registered on the system.mes.batch.queue script module (Sepasoft Batch / MES).

• Gateway: Runs on the gateway; the entry is appended to the local runtime queue when the process cell’s equipment is hosted on that server.

• Designer / Client: Same API; calls go to the connected gateway via RPC. Enterprise routing: the gateway forwards addQueueEntry to the server closest to the resolved process cell’s equipment path when that owner is not the local gateway.

Excluded / Edge Cases

• Link type — masterRecipeOrFormulaLink (or deprecated masterRecipeLink) must be a Batch Master Recipe or Batch Formula link; otherwise an IllegalArgumentException is raised.

• Blank batch ID — Raises Exception: "The batch id cannot be blank."

• Duplicate batch ID — Raises if the ID is already in the queue or was used by a completed/archived batch ("already in the queue" / "has already been used").

• Invalid or out-of-sync formula — Formula must be valid and match the master recipe user version; otherwise creation fails with a descriptive Exception.

• Master recipe not validated — If the resolved master recipe has not been successfully validated, addQueueEntry fails with an error naming the recipe.

• Process cell resolution — If the process cell cannot be determined (e.g., multiple cells and no disambiguating path/assignments), Exception is raised with guidance to supply processCellPath, unitAssignments, or use a single-cell server configuration.

• processCellPath — Must resolve to a MES Process Cell equipment object; otherwise Exception ("is not a Process Cell").

• Recipe vs. process cell — The master recipe’s unit class assignments must be consistent with the chosen process cell; cross–process cell mismatches raise Exception (wording differs for local vs. sync scenarios).

• Unit assignments — Values must be String paths or MESObjectLink to MESUnit; None values per key are rejected. Assigned units must belong to the same process cell as the resolved target when a cell is already fixed.

• MES runtime and license — The MES system must be started and the Batch module must be licensed; otherwise gateway checks fail before the entry is created.

• Local queue list — The in-memory queue on a gateway only receives the entry when equipment for that process cell is on that server; remote routing still completes addQueueEntry on the owning gateway.

Example Usage

Minimal Example

# recipeLink is an MESObjectLink to a Batch Master Recipe
entry = system.mes.batch.queue.addEntry(
	masterRecipeOrFormulaLink=recipeLink,
	batchID="BATCH-2026-0001"
)

Complex Example

recipeLink = system.mes.batch.recipe.getRecipeLink(name="MyMasterRecipe")

entry = system.mes.batch.queue.addEntry(
	masterRecipeOrFormulaLink=recipeLink,
	batchName="Spring Production Run",
	batchID="BATCH-2026-0002",
	priority=5,
	scale=1.0,
	quantity=500.0,
	processCellPath="Enterprise\\Site1\\AreaA\\Mixer Cell",
	unitAssignments={
		"Charge": "Enterprise\\Site1\\AreaA\\Mixer Cell\\Mixer 1"
	},
	batchParameters={
		"TargetTemp": 72.5,
		"UseAdditive": True
	}
)

system.mes.batch.queue.executeEntryCommand(
	entry,
	system.mes.batch.queue.COMMAND_START()
)

Related Functions

• system.mes.batch.queue.addOrUpdateEntry(entry) — Adds or updates an existing BatchQueueEntry (editable fields) instead of creating from a fresh request.

• system.mes.batch.queue.getEntry(batchID) — Retrieves a queue entry by batch ID.

• system.mes.batch.queue.getEntries(pageNumber, pageSize, searchPattern) — Lists queue entries with paging and wildcard search.

• system.mes.batch.queue.executeEntryCommand(batchQueueEntry, command) / executeEntryCommandAsync — Sends batch commands (e.g. COMMAND_START()) to a queue entry.

• system.mes.batch.queue.assignUnit(batchQueueEntry, unitProcedurePath, unitEquipmentPath) — Assigns a unit to a unit procedure on an existing entry.

• system.mes.batch.queue.removeEntry(batchQueueEntry) — Removes an entry from the queue.

• system.mes.batch.queue.changeEntryPriority(batchQueueEntry, newPriority) — Updates priority after the entry exists.

Sepasoft MES Module Suite