system.mes.batch.queue.changeEntryPriority(batchQueueEntry, newPriority)

Sepasoft MES Module Suite

changeEntryPriority(...)

Updates the numeric priority of an existing batch queue entry, identified by either a BatchQueueEntry or a batch ID. Lower numbers mean higher priority (for example, 1 is highest); the value is used for reference and by the allocation manager. If the new priority matches the current value, the call returns immediately without persisting changes. Otherwise, the gateway applies the update through the same add/update queue entry path used for idle entries, and returns the refreshed BatchQueueEntry. Priority cannot be changed while the entry's batch controller is active (the batch is running under active control).

changeEntryPriority(batchQueueEntry, newPriority) → BatchQueueEntry

Syntax

Copy Code

Python

system.mes.batch.queue.changeEntryPriority(batchQueueEntry, newPriority)
system.mes.batch.queue.changeEntryPriority(batchID, newPriority)

Parameters

Parameter	Type	Required	Description
batchQueueEntry	BatchQueueEntry	Required for this overload	The queue entry to update, typically from getEntry, getEntries, addEntry, or addOrUpdateEntry. Must still be present in the gateway's batch queue (matched by the entry's control recipe UUID).
batchID	String	Required for this overload	Batch ID of the queue entry to update. Must be a non-blank ID for an entry currently in the queue.
newPriority	Integer	Required	New priority value. 1 is the highest priority. Used for ordering reference and allocation behavior.

Return Value

Type	Description
BatchQueueEntry	The queue entry after the operation. If the priority was unchanged, the function returns the resolved entry without running add/update persistence; for the batchQueueEntry overload, this is the same object reference passed in. If the priority was updated, this is the entry returned from the internal add/update logic (reflecting the new priority and persisted state).

Scope / Availability

Registered on the system.mes.batch.queue script module (Sepasoft Batch / MES).
Gateway: Executes on the gateway that owns the batch queue for the entry's process cell.
Designer / Client: Same API; calls go to the connected gateway via RPC (consistent with other system.mes.batch.queue.* functions).

Excluded / Edge Cases

Active batch - If the queue entry's controller is active, the call raises Exception: "Unable to change priority because batch queue entry is active." Change priority only when the batch is not under active controller execution (idle / waiting entries).
Entry not in queue - If no queue entry exists for the control recipe UUID on batchQueueEntry, BatchQueueEntryNotFoundException is raised (message includes the control recipe UUID).
Blank batch ID - The batchID overload raises IllegalArgumentException when the supplied ID is blank or missing.
Unknown batch ID - The batchID overload raises BatchQueueEntryNotFoundException when no queue entry exists for that batch ID.
No-op - If newPriority equals the entry's current priority, the function returns the resolved entry without running add/update persistence.
MES runtime - The MES system must be started before the entry can be checked and updated. When the priority changes, the internal addOrUpdateQueueEntry path runs (and normal Batch licensing applies), same as other queue mutations.
None entry - Passing None for batchQueueEntry is invalid and will fail before a successful lookup.

Example Usage

Minimal Example

Copy Code

Python

updated = system.mes.batch.queue.changeEntryPriority("BATCH-2026-0001", 5)

Complex Example

Copy Code

Python

# Raise priority (lower number) for a waiting batch after rescheduling
entries = system.mes.batch.queue.getEntries(pageNumber=0, pageSize=50, searchPattern="SPRING-*")
for entry in entries:
	if entry.getBatchName().startswith("SPRING-RUSH"):
		try:
			system.mes.batch.queue.changeEntryPriority(entry, 1)
		except Exception as e:
			system.util.getLogger("BatchPriority").error("Could not reprioritize %s: %s" % (entry.getBatchID(), e))

Related Functions

system.mes.batch.queue.addEntry(...) - Creates a new queue entry; optional priority sets the initial value.
system.mes.batch.queue.addOrUpdateEntry(batchQueueEntry) - Updates an idle entry's editable fields (including priority) via a full BatchQueueEntry; changeEntryPriority is a focused shortcut that routes through similar gateway logic when priority changes.
system.mes.batch.queue.getEntry(batchID) - Loads a BatchQueueEntry by batch ID for use with changeEntryPriority.
system.mes.batch.queue.getEntries(pageNumber, pageSize, searchPattern) - Lists queue entries for batch processing or UI.
system.mes.batch.queue.removeEntry(batchQueueEntry) - Removes an entry from the queue.

Sepasoft MES Module Suite