system.mes.batch.queue.assignUnit

Sepasoft MES Module Suite

assignUnit(...)

Assigns a MES unit (by equipment path) to a unit procedure within a batch queue entry’s control recipe, or clears the assignment when no unit path is given. The gateway validates the path, resolves the unit against the unit procedure’s unit class, updates the queue entry and control logic, and—when batch execution is active—sends an assign unit notification so running logic stays in sync. Typical uses include binding equipment before COMMAND_START() or reassigning while the batch is in an allowed state (for example Held).

Syntax

Copy Code
Python
system.mes.batch.queue.assignUnit(batchQueueEntry, unitProcedurePath, unitEquipmentPath)

Parameters

Parameter

Type

Required

Description

batchQueueEntry

BatchQueueEntry

Required

The queue entry whose control recipe contains the target unit procedure. Must correspond to an entry currently in the gateway’s batch queue (see Excluded / Edge Cases).

unitProcedurePath

String

Required

Full item path to the unit procedure step to receive the unit. Use the /{}/UnitProcedureName pattern: {} stands for the procedure segment (this procedure). Example: "/{}/P2". Whitespace-only values are rejected.

unitEquipmentPath

String

Optional

Full equipment path of the MES unit to assign (Ignition/MES equipment path format, e.g. "Enterprise\\Site\\Area\\Process Cell 1\\Unit 1"). The unit must be qualified for the unit procedure’s configured unit class. If omitted or blank, the unit assignment for that unit procedure is cleared (unassigned).

Return Value

Type

Description

None

Updates the queue entry and, when applicable, control logic and batch execution; no return value.

Scope / Availability

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

  • Gateway: Runs on the gateway that owns the batch queue.

  • Designer / Client: Same API; execution is delegated to the connected gateway via RPC.

Excluded / Edge Cases

  • Queue membership — The batchQueueEntry must match a control recipe UUID present in the gateway queue. Otherwise BatchQueueEntryNotFoundException is raised (message indicates the control recipe UUID was not found).

  • Null entry — A null batchQueueEntry causes a NullPointerException when resolving the queue entry.

  • Batch state — Assignment is allowed only when the batch state mayAssignUnit(): Running, Unknown, Idle (can transition to run), or Held. Other states raise IllegalStateException with a message that unit assignment is not permitted.

  • Invalid or missing unit procedure path — Blank unitProcedurePath raises IllegalArgumentException. Paths that do not resolve to a unit procedure (expected form like "/{}/UnitProcedureName") raise IllegalArgumentException with guidance on the required format.

  • Unknown unit procedure — If the path is syntactically valid but no matching unit procedure exists in the recipe, NoSuchElementException is raised.

  • Unit vs unit class — A non-blank unitEquipmentPath must match a unit returned as qualified for the procedure’s unit class (getQualifiedUnits). If none match, IllegalArgumentException explains that the unit is not valid for that unit class.

  • No-op — If the resolved unit link is already the same as the current assignment, the method returns without sending a notification or rewriting references.

  • Active controller — When a batchExecutionController exists and the assignment actually changes, an ASSIGN_UNIT notification is sent with the unit procedure path and equipment path data for execution to consume.

Example Usage

Minimal Example

Copy Code
Python
entry = system.mes.batch.queue.getEntry("BATCH-001")
system.mes.batch.queue.assignUnit(entry, "/{}/Fermenter_UP", "Enterprise\\Site\\Area\\Line1\\Fermenter1")

Complex Example

Copy Code
Python
batchId = "BATCH-042"
entry = system.mes.batch.queue.getEntry(batchId)
unitProcPath = "/{}/Charge_UP"
newUnitPath = "Enterprise\\Site\\Area\\CellA\\Reactor3"

try:
	system.mes.batch.queue.assignUnit(entry, unitProcPath, newUnitPath)
except Exception, ex:
	system.util.getLogger("BatchQueue").error("assignUnit failed for %s: %s" % (batchId, ex))

# Clear assignment for a unit procedure (blank equipment path)
system.mes.batch.queue.assignUnit(entry, "/{}/Hold_UP", "")

Related Functions

  • system.mes.batch.queue.getEntry(batchID) — Loads the BatchQueueEntry used as the first argument.

  • system.mes.batch.queue.addEntry(...) / addOrUpdateEntry(entry) — Create or update entries; assignedUnitMap on add/update applies per–unit-procedure assignments using the same rules as assignUnit when the controller is active.

  • system.mes.batch.queue.executeEntryCommand(batchQueueEntry, command) — Start or control the batch after units are assigned.

  • system.mes.batch.unit.assignUnitClass(unitLink, unitClassLink) — Associates a unit class with a unit (different from assigning a unit to a batch unit procedure).


Sepasoft MES Module Suite