system.mes.batch.queue.syncPLIStepState(batchQueueEntry, path)

Sepasoft MES Module Suite

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

Updates a batch step's state to match the step's current command when state transitions are handled by the PLC (PLI mode). Use this when the MES step state has drifted from the equipment or when you need to manually align state after a command without waiting for PLC feedback.

The function is only valid for:

  • Equipment,
  • Synchronize,
  • Transfer In
  • Transfer Out

phase types configured with State_Transition_Handling set to PLI.

First released in:

Warning

MES 3.81.8 SP3 -  Stable Release

Syntax

Copy Code
JSON
system.mes.batch.queue.syncPLIStepState(batchQueueEntryOrBatchID, path)
system.mes.batch.queue.syncPLIStepState(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 step state should be synchronized.

path

String

Required

—

Full path to the step, including parent logic. 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 recorded with the state change (for example, a username or script name).

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 syncPLIStepState runs:

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

  • Path resolution — The friendly step path is converted to the internal UUID-based path for the batch execution controller.

  • State update — A SYNC_PLI_STEP_STATE notification is sent to the step action. The step's current command (or pending command when the current command is NONE) determines the target state:


Current / pending command

State set

START, RESTART, RESUME

Running

STOP

Stopped

PAUSE

Paused

HOLD

Held

ABORT

Aborted

RESET

Idle

NONE (step already Running)

Complete

NONE (step not Running)

Idle

  • Side effects — The step's State and State_Number parameters are updated, a state change event is emitted, and command completion is evaluated.

In PLI mode, the PLC normally drives state transitions; this function lets MES set state explicitly to match the active command when synchronization is needed (for example, from a Perspective batch control action or a gateway script reacting to equipment feedback).

Excluded / Edge Cases

  • Phase types — Only Equipment, Synchronize, Transfer In, and Transfer Out steps are supported. Other phase types do not handle this notification.

  • State_Transition_Handling — Steps with State_Transition_Handling set to Auto reject this call with an error: "Sync step state command is only available when State_Transition_Handling parameter is set to PLI."

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

  • After action ended — This notification type is not allowed after the step action has ended.

  • Not a substitute for force complete — Unlike forceStepComplete, this function aligns state to the current command rather than forcing a running step to complete regardless of command.

Example Usage

Minimal example

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

Complex example

After issuing a hold command at the step, synchronize PLI state from a gateway timer script when PLC feedback is delayed:

Copy Code
Python
batchID = 'BATCH-001'
stepPath = '/{}/Fermentation:Hold Phase'
changedBy = 'gateway.syncScript'

# Issue the hold command first
system.mes.batch.queue.executeStepCommand(
    batchID,
    stepPath,
    system.mes.batch.queue.COMMAND_HOLD,
    changedBy=changedBy
)

# Align MES step state to the hold command if PLC state lags
system.mes.batch.queue.syncPLIStepState(
    batchID,
    stepPath,
    changedBy=changedBy
)

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.syncPLIStepState(
    entry,
    stepPath,
    changedBy='fillLineMonitor'
)

Related Functions

  • executeStepCommand() — Sends a batch command (start, hold, pause, and so on) to a specific step.

  • forceStepComplete() — Forces a running step to complete even though it has not finished; requires the step to be in Running state.

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

  • setParameterValue() — Sets step parameter values directly; use syncPLIStepState instead when aligning PLI-managed state to the current command.

Sepasoft MES Module Suite