batch.queue.changeActiveStep

Sepasoft MES Module Suite

queue.changeActiveStep(...)

Overview

Changes which step is the active step in a running batch's execution logic. Use this in Manual mode to redirect execution to a different valid step in the recipe—for example, when an operator selects a new active step from a batch monitor or a script needs to reposition execution after a step reaches a terminal state. The batch must be actively running, the target step's parent logic (Procedure, Unit Procedure, or Operation) must be in Manual mode, and the currently active step must be in a terminal state (idle, complete, aborted, or stopped).

Note

Version specific:

Available in 3.81.12 RC3 and later.

Syntax

Copy Code
Python
system.mes.batch.queue.changeActiveStep(batchQueueEntryOrBatchID, path)
system.mes.batch.queue.changeActiveStep(batchQueueEntryOrBatchID, path, changedBy='operator')

Parameters

Parameter

Type

Required

Default

Description

batchQueueEntry Or BatchID

BatchQueueEntry or String

Required

—

The BatchQueueEntry object or batch ID of the running queue entry whose active step should be changed.

path

String

Required

—

Full path to the step that should become the active step. Format: /Procedure/Unit_Procedure/Operation:Step. Use {} in place of the procedure name. Examples: /{}:Step, /{}/Unit_Procedure:Step, /{}/Unit_Procedure/Operation:Step.

changedBy

String

Optional

None

Optional identifier to associate with the change (for example, a username or script name). Accepted for API consistency with other batch queue functions.

Return Value

Type

Description

None

This function does not return a value.

Scope / Availability

Context

Available

Batch Designer / client scripts (BatchClientQueueScript)

Yes

Gateway scripts (BatchGatewayQueueScript)

Yes


Both contexts invoke the same gateway batch execution logic (client via RPC, gateway directly).

Behavior

When changeActiveStep runs:

  1. Preconditions — The MES system must be started, the queue entry must exist, and the batch must be actively running.

  2. Path validation — The path must include a step (or a Unit Procedure / Operation that is converted to a step path). Malformed paths are rejected.

  3. Manual mode — The parent logic of the target step must be in Manual mode; otherwise the call fails.

  4. Step resolution — The friendly path is resolved to the internal step. If the path points to a Unit Procedure or Operation without an explicit step segment, the last path segment is converted from /Operation to :Operation step notation.

  5. Active step change — The SFC execution engine sets the specified step as the pending active step for the running chart, provided the execution context allows the change.

Success

Use getValidNextSteps() before calling this function to discover which step paths are valid targets for the current execution state.

Exceptions

Exception

When raised

IllegalArgumentException

The path is malformed, the target is not a valid step type for active-step change (for example, a transition or terminator), or the step is inside an And_Begin/And_End block that is not currently active.

IllegalStateException

The parent logic is not in Manual mode, the parent logic is not currently running, or the currently active step is still running or otherwise not in a state where the active step may be changed.

NoSuchElementException

No step or logic item can be found at the specified path, or the execution chart for the logic is not found.

Excluded / Edge Cases

  • Automatic mode — Active step cannot be changed when the parent logic is in Automatic mode; set Manual mode with setLogicMode() first.

  • Non-terminal active step — The current active step must be idle, complete, aborted, or stopped before a different step can be made active.

  • Invalid target types — Transitions, initial elements, terminators, and And_End/Or_End elements cannot be selected as the new active step.

  • And context blocks — Steps inside an And_Begin/And_End parallel block can only be activated when that branch context is active.

  • Batch not running — The queue entry must be in a running state; otherwise the call fails.

Example Usage

Minimal example

Copy Code
Python
batchID = 'BATCH-001'
stepPath = '/{}/Mix Operation:Charge Materials'
system.mes.batch.queue.changeActiveStep(batchID, stepPath)

Complex example

Query valid next steps, switch the parent logic to Manual mode if needed, then change the active step:

Copy Code
Python
batchID = 'BATCH-001'
logicPath = '/{}/Fermentation'
targetStep = '/{}/Fermentation:Hold Phase'
changedBy = 'batchMonitor.script'

# Discover steps that can become active
validSteps = system.mes.batch.queue.getValidNextSteps(batchID, logicPath)
if targetStep not in validSteps:
    raise Exception('Target step is not a valid next step: %s' % targetStep)

# Ensure parent logic is in Manual mode
system.mes.batch.queue.setLogicMode(
    batchID,
    system.mes.batch.queue.MODE_MANUAL,
    logicPath,
    changedBy=changedBy
)

# Change the active step
system.mes.batch.queue.changeActiveStep(
    batchID,
    targetStep,
    changedBy=changedBy
)

# Confirm the new active step
activeSteps = system.mes.batch.queue.getActiveSteps(batchID, logicPath)
print('Active steps: %s' % activeSteps)

Using a BatchQueueEntry object instead of a batch ID:

Copy Code
Python
entry = system.mes.batch.queue.getQueueEntry('BATCH-001')
stepPath = '/{}/Packaging/Fill Line:Fill Containers'
system.mes.batch.queue.changeActiveStep(
    entry,
    stepPath,
    changedBy='fillLineMonitor'
)

Related Functions

  • getValidNextSteps() — Returns step paths that are valid targets for an active-step change in the current execution state.

  • getActiveSteps() — Returns step paths for steps that are currently active in the execution logic.

  • setLogicMode() — Sets a logic item to Manual or Automatic mode; Manual mode is required before changing the active step.

  • executeStep() — Executes a step when the parent logic is in Manual mode.

  • forceStepComplete() — Forces a running step to complete even though it has not finished.

Sepasoft MES Module Suite