executeStep(...)

Sepasoft MES Module Suite

executeStep(batchQueueEntry, path, changedBy)

Requests manual execution of a single recipe step on a running batch by sending a force step execute notification to the step at the given path. This advances or starts the step’s internal action (for example No Action, Equipment, or Document behavior) according to recipe rules. It is not the same as executeStepCommand, which issues equipment command tokens (Start, Hold, Reset, and so on) to a phase’s command model.

This function executes a step when the parent logic is in manual. The batch must be actively running.

executeStep(batchQueueEntry, path) → void

Syntax

Copy Code

Python

system.mes.batch.queue.executeStep(batchQueueEntry, path, changedBy)

Parameters

Parameter	Type	Required	Description
batchQueueEntry	BatchQueueEntry	Required	Queue entry for the batch. Must resolve to an entry currently held by the gateway execution manager.
path	str	Required	Full friendly path to the step (procedure / unit procedure / operation / phase step). Resolved through the execution controller (friendlyPathToUUIDPath). Use {} as a placeholder for the procedure segment when the procedure name is not fixed.
changedBy	str	Required	User or system identity recorded with the action (audit / “changed by”), passed through the batch notification.

Path examples

Example	Meaning
/{}:StepName	Step at procedure root
/{}/Unit_Procedure:StepName	Step under a unit procedure
/{}/Unit_Procedure/Operation:StepName	Step under an operation

Return Type

Type	Description
None	No return value. Failures are raised as exceptions.

Scope / Availability

Context	Notes
Gateway	Runs on the gateway against the live BatchExecutionController for the queue entry.
Client	Exposed as system.mes.batch.queue.executeStep; delegates to the gateway over RPC (same rules as other system.mes.batch.queue.* calls, including Enterprise routing where applicable).
Batch Designer	The system.mes.batch.queue module is available for authoring; execution applies to batches running on the gateway.

Excluded / Edge Cases

The queue entry must be running. If it is not running, IllegalStateException: Unable to execute step because batch queue entry is not running.
If batchQueueEntry is missing, IllegalArgumentException: Unable to execute step because a batch queue entry was not provided.
If the entry’s control recipe is not in the gateway queue, BatchQueueEntryNotFoundException with the control recipe UUID.
If the MES production system has not finished starting, IllegalStateException: Try request again once the MES system has fully started.
If no batch listener is registered for the resolved UUID path (wrong or non-step path), Exception: Specified logic path is not valid.
Phase-type rules (enforced when the notification reaches the step):
- Types that do not allow manual execution raise BatchNotifyException (for example: Phase of (…) type cannot be manually executed.).
- Equipment phases additionally require manual execute permission, manual step mode, an allocated unit, the step not already executing, and no conflicting active step of the same phase type; otherwise BatchNotifyException with a specific reason (see runtime message).
- No Action / Document style handlers reject execution if the step is already executing (BatchNotifyException).
- Recipe configuration may expose an Execute Step parameter on steps; the batch controller UI uses that to enable operator Execute Step actions. Scripts can still call this API when the engine allows the transition; align recipe design and permissions with your use case.

Example Usage

Minimal example

Copy Code

Python

entry = system.mes.batch.queue.getEntry("BATCH-2026-0042")
system.mes.batch.queue.executeStep(entry, "/{}/Mix_UP/Mix_Op:Weigh_Add", "operator1")

Complex example

Typical pattern: confirm the batch is running, resolve the step path (often matching the Batch Controller or recipe monitor), then execute after prerequisites (messages, parameters, or unit assignment) are satisfied.

Copy Code

Python

batchId = "BATCH-2026-0042"
entry = system.mes.batch.queue.getEntry(batchId)
phasePath = "/{}/Ferment_UP/Ferment_Op:Inoculate_Phase"

# Optional: ensure messages/parameters are handled before forcing step execution
# system.mes.batch.queue.assignMessageValue(msg)

system.mes.batch.queue.executeStep(entry, phasePath, system.security.getUsername())

Related Functions

system.mes.batch.queue.executeStepCommand(batchQueueEntry, stepPath, command, changedBy) — Sends a command string (COMMAND_START(), COMMAND_HOLD(), etc.) to a step’s equipment command model; use for phase command transitions, not for generic “execute this step” manual advance.
system.mes.batch.queue.forceStepComplete(batchQueueEntry, path, changedBy) — Forces completion of a step when the recipe allows force complete (paired with Execute in many operator flows).
system.mes.batch.queue.syncPLIStepState(batchQueueEntry, path, changedBy) — Synchronizes PLC-linked equipment step state where supported.
system.mes.batch.queue.getActiveSteps(batchQueueEntry, path=None) — Lists active step paths to help choose a valid path for manual actions.
system.mes.batch.queue.completeDocumentStep(batchQueueEntry, path) — Completes a Document phase by marking it complete (different notification than execute).
system.mes.batch.queue.executeEntryCommand(batchQueueEntry, command, ...) — Batch-level commands (start, hold, reset, etc.) on the queue entry.

Sepasoft MES Module Suite