BatchAllocationRequest Object

Sepasoft MES Module Suite

BatchAllocationRequest Object

Overview

A Batch Allocation Request represents a runtime request for exclusive use of a batch Unit (MESUnit). The gateway's allocation manager tracks active and waiting requests in memory while batches execute Allocate phases, Deallocate phases, and Unit Procedure steps. When a unit becomes available, the manager assigns it to the highest-priority waiting request and records allocation timestamps and equipment paths on the request.

BatchAllocationRequest is not a persisted MES object. It cannot be created, loaded, or saved with system.mes.saveMESObject(). Integrators obtain snapshots through system.mes.batch.unit.getAllocationList() and may reprioritize waiting requests with system.mes.batch.unit.changeAllocationPriority(). Batch execution creates and manages requests internally.

Obtaining a BatchAllocationRequest

Copy Code

Python

# Snapshot of active and waiting allocation requests on the gateway
allocations = system.mes.batch.unit.getAllocationList(
    0,              # pageNumber — use 0 when paging is not required
    100,            # pageSize
    '',             # searchPattern — filters by unit equipment path or unit class name
    True,           # includeAllocation — include requests that have been allocated
    True            # includeWaiting — include requests still waiting for a unit
)

for req in allocations:
    print(req.getBatchID(), req.getPriority(), req.isAllocated())

There is no script API to construct a new BatchAllocationRequest. Requests are submitted by batch SFC actions (BatchAllocateAction, BatchDeallocateAction, BatchUnitProcedureAction) through the gateway allocation manager.

Object Identity

Field	Value
Type name	BatchAllocationRequest
Kind	Runtime gateway object (not stored in the MES database)
Required module	Batch
Managed by	BatchAllocationManager on the gateway

Request Types

Allocation requests fall into two modes, distinguished by what they ask for:

Mode	Identified by	Behavior
Specific unit	getRequestedEquipmentPath() is set	Waits for the unit at that equipment path to become free. Used by Allocate and Deallocate phases and by unit procedures that target a named unit.
Unit class	getUnitClassRef() is set (no equipment path)	Waits for any qualified unit assigned to the unit class (optionally including descendant classes). Used by Unit Procedure steps when no specific unit is assigned.

When a specific unit is deallocated, the manager may also satisfy waiting unit class requests for units assigned to that class.

Priority Constants

Lower numbers indicate higher priority. Waiting requests are ordered by priority, then by request time.

Constant	Value	Typical use
PRIORITY_HIGHEST	1	Highest priority
PRIORITY_HIGH	25	High priority
PRIORITY_DEFAULT	50	Default when not specified
PRIORITY_LOW	75	Low priority
PRIORITY_LOWEST	100	Lowest priority

The Allocate phase reads priority from the step parameter Allocate Priority; values below 1 are treated as PRIORITY_DEFAULT (50).

Immutable Properties

These values are fixed when the request is created and do not change for the life of the object.

Property	Access	Type	Description
Batch ID	getBatchID()	String	Batch identifier of the control recipe requesting the unit.
Requested By Ref	getRequestedByRef()	MESObjectLink	Link to the batch logic object that submitted the request (typically the sub-logic running the allocate/deallocate phase or unit procedure). Used to match duplicate submissions and to locate the request in the allocation list.
Request Date Time	getRequestDateTime()	Date	Timestamp when the request was created.
Step UUID	getStepUUID()	String	Step identifier for unit-procedure requests; empty for allocate/deallocate phases.
Step Name Path	getStepNamePath()	BatchItemPath	ISA-88 path to the procedure step that created the request (e.g. procedure / unit procedure / operation / phase). Returns None when not applicable. Use str(req.getStepNamePath()) for the friendly path string.
Process Cell Link	getProcessCellLink()	MESObjectLink	Process cell scope for unit-class allocation. May be unset for allocate/deallocate requests.
Estimated Duration	getEstimatedDuration()	Long	Estimated hold duration in milliseconds (internal scheduling hint).
Include Descendants	isIncludeDescendants()	Boolean	When True, unit-class matching includes units assigned to descendant unit classes.

Mutable Properties

These values change as the allocation manager processes, assigns, or cancels requests.

Property	Access	Type	Description
Requested Equipment Path	getRequestedEquipmentPath() / setRequestedEquipmentPath(path)	String	Equipment path of the specific unit being requested. Blank when the request targets a unit class instead.
Unit Class Ref	getUnitClassRef() / setUnitClassRef(link)	MESObjectLink	Unit class link for class-based requests.
Quantity	getQuantity() / setQuantity(value)	Double	Batch quantity used for unit capacity checks. Allocation succeeds only when quantity is unset or falls within the unit's min/max capacity.
Priority	getPriority() / setPriority(value)	Integer	Queue priority (lower = sooner). Change waiting requests with changeAllocationPriority() rather than mutating objects returned from an earlier snapshot.
Estimated Date Time	getEstimatedDateTime() / setEstimatedDateTime(date)	Date	Optional estimated allocation time.
Defer Allocation	isDeferredAllocation() / setDeferAllocation(value)	Boolean	When True, the request is held out of the allocation queue until deferral is cleared. Unit procedures create deferred requests and commit them when execution begins.
Allocated Date Time	getAllocatedDateTime()	Date	Timestamp when a unit was assigned; None while waiting.
Allocated Equipment UUID	getAllocatedEquipmentUUID()	String	UUID of the unit that was allocated.
Allocated Equipment Path	getAllocatedEquipmentPath()	String	Equipment path of the allocated unit.
Pending Cancellation	isPendingCancellation()	Boolean	True while a deallocate/cancel operation is being processed.

BatchAllocationRequest Methods

Status and query

Method	Return type	Description
isAllocated()	Boolean	True when getAllocatedDateTime() is set — the request holds an allocated unit.
hasEquipmentPath()	Boolean	True when a specific unit equipment path was requested.
hasUnitClassRef()	Boolean	True when a unit class reference is set.
hasStepUUID()	Boolean	True when a step UUID is present (unit-procedure requests).
hasStepNamePath()	Boolean	True when a step name path is present.
hasProcessCellLink()	Boolean	True when a process cell link is set.
hasQuantity()	Boolean	True when quantity is set and greater than zero.

Fluent setters

These methods update the request and return self for chaining (used internally by batch actions):

Method	Return type	Description
setQuantity(quantity)	BatchAllocationRequest	Set batch quantity for capacity validation.
setPriority(priority)	BatchAllocationRequest	Set queue priority.
setDeferAllocation(defer)	BatchAllocationRequest	Enable or disable deferral.

Internal / batch-runtime methods

The following methods are used by batch execution and the allocation manager. Scripts normally do not call them directly.

Method	Description
waitForAllocation(callback)	Blocks until the request is allocated or the callback reports cancellation. Used by allocate and unit-procedure actions.
cancelAllocation()	Clears allocation fields and marks the request deferred. Called by the manager during deallocation.
notifyUpdate()	Wakes threads waiting on waitForAllocation().

Scope / Availability

Context	How to access
Gateway scripts	system.mes.batch.unit.getAllocationList() and changeAllocationPriority(); read properties on returned objects
Client / Designer scripts	Same module via RPC (BatchClientUnitScript)
Perspective / batch execution	Allocation requests are created and consumed automatically by batch phases and unit procedures

Exceptions and Constraints

Situation	Behavior
Change priority on unknown request	Exception: "Unable to change allocation request priority because the specified request was not found or is no longer active."
Change priority on allocated request	Exception: "Unable to change allocation request priority because it has already been allocated."
Cancel allocation when no matching request exists	BatchAllocationNotFoundException with equipment path in the message
Unit capacity outside min/max	Request remains waiting; manager logs an informational message
Duplicate submission from same logic	requestAllocation() returns the existing in-memory request matched by Requested By Ref and step UUID or equipment path
Deferred request	Not eligible for allocation until setDeferAllocation(False)
Pending cancellation	Excluded from equipment-path queue processing until cancellation completes

Identity matching: The allocation manager locates an existing request when Requested By Ref matches and either (a) both requests lack a step UUID and share the same requested equipment path, or (b) step UUIDs match. Pass the object returned from getAllocationList() to changeAllocationPriority() so the manager can resolve the live request.

Example Usage

Minimal example — list waiting allocations

Copy Code

Python

waiting = system.mes.batch.unit.getAllocationList(0, 50, '', False, True)

for req in waiting:
    unit = req.getRequestedEquipmentPath() or req.getUnitClassRef().getName()
    print('Batch %s waiting for %s (priority %d)' % (
        req.getBatchID(),
        unit,
        req.getPriority()
    ))

Complex example — reprioritize a waiting unit-class request

Copy Code

Python

# Find waiting requests for a batch and raise priority
batch_id = 'BATCH-2026-001'
HIGH = 25

allocations = system.mes.batch.unit.getAllocationList(0, 100, '', False, True)

for req in allocations:
    if req.getBatchID() == batch_id and not req.isAllocated():
        if req.hasUnitClassRef():
            print('Reprioritizing %s on class %s from %d to %d' % (
                req.getBatchID(),
                req.getUnitClassRef().getName(),
                req.getPriority(),
                HIGH
            ))
            system.mes.batch.unit.changeAllocationPriority(req, HIGH)

Inspect active allocations

Copy Code

Python

active = system.mes.batch.unit.getAllocationList(0, 100, '', True, False)

for req in active:
    if req.isAllocated():
        print('%s allocated %s at %s' % (
            req.getBatchID(),
            req.getAllocatedEquipmentPath(),
            req.getAllocatedDateTime()
        ))

Related Functions

Module: system.mes.batch.unit

Function	Description
getAllocationList(pageNumber, pageSize, searchPattern, includeAllocation, includeWaiting)	Returns a paged, filtered snapshot of BatchAllocationRequest objects sorted by priority then request time.
changeAllocationPriority(allocationRequest, newPriority)	Updates priority on a waiting request. Has no effect on requests that are already allocated.

Other unit module functions (getLink, getList, assignUnitClass, …) operate on MESUnit objects, not allocation requests.

Related Objects

Object	Relationship
MESUnit	Physical batch unit that may be allocated or deallocated
BatchUnitClass	Class used when a request does not target a specific unit
MESProcessCell	Optional scope limiting which units may satisfy a unit-class request
BatchControlLogic	Sub-logic referenced by Requested By Ref — the allocate/deallocate phase or unit procedure that owns the request
BatchItemPath	Step path identifying where in the procedure hierarchy the request originated

Batch phases that create allocation requests:

Allocate — requests a shared unit by equipment path; honors Allocate Priority and batch quantity for capacity checks
Deallocate — cancels an existing allocation for a unit path
Unit Procedure — requests a specific unit or any qualified unit from an assigned unit class when the sub-logic starts

Sepasoft MES Module Suite