Sepasoft MES Module Suite
getBatchEBR(...)
system.mes.batch.queue.getBatchEBR() returns the Electronic Batch Record for one control recipe. The record includes the procedure, the steps that ran, and the parameter values recorded during execution, with a timestamp on each recorded value.
The batch can still be in the queue, or it can be complete and no longer in the queue. Minimum and maximum parameter values are included only when they differ from the parameter default.
|
dateTimeFormat was added in MES 3.81.11 SP12. The function itself is available in MES 3.81.5 SP5 and MES 3.81.6 RC2 and later. |
Syntax
Python |
system.mes.batch.queue.getBatchEBR(batchID) system.mes.batch.queue.getBatchEBR(batchID, includeIdleSteps, includeSystemParameters, timeoutSeconds, dateTimeFormat) system.mes.batch.queue.getBatchEBR(batchQueueEntry, includeIdleSteps, includeSystemParameters, timeoutSeconds, dateTimeFormat) |
Arguments can be passed by position or by name. The first argument is a batch ID string or a BatchQueueEntry.
Required Parameters
Parameter | Type | Description |
|---|---|---|
batchID | String | Batch ID entered in the batch header. Pass this or batchQueueEntry. |
batchQueueEntry | BatchQueueEntry | Queue entry whose EBR should be returned. The batch ID is taken from the entry. Pass this or batchID. |
Optional Parameters
Parameter | Type | Default | Description |
|---|---|---|---|
includeIdleSteps | Boolean | False | When True, steps that have not started are included, with status Pending, along with their configured parameter values. When False, only steps that have execution history are included. |
includeSystemParameters | Boolean | True | When True, built-in system parameters are included. When False, those parameters are omitted. User parameters are still included. |
timeoutSeconds | Integer | 5 | Seconds to wait for a loaded batch to leave Idle before the EBR is built. Used only while the batch is still loaded in the queue. Pending history writes are flushed before and after the wait so startup values such as Batch_ID, Recipe_Name, and Begin_Date_Time are present. If the batch is already running, or it has left the queue, there is no wait. If the wait ends and the batch is still Idle, the EBR is still returned from the data available at that time. |
dateTimeFormat | String | yyyy-MM-dd HH:mm:ss.SSS | Pattern for every date-time string in the EBR, including parameter values, minimum and maximum dates, and TimeStamp. Added in MES 3.81.11 SP12. Pass '', None, or omit the argument to use the default. An invalid pattern raises IllegalArgumentException. |
Date-time patterns use the gateway locale and time zone. Examples:
Pattern | Result shape |
|---|---|
yyyy-MM-dd HH:mm:ss.SSS | 2026-09-28 10:15:06.000 |
yyyy-MM-dd HH:mm:ss | 2026-09-28 10:15:06 |
EEE, MMM d, yyyy h:mm a z | Mon, Sep 28, 2026 10:15 AM PDT |
yyyy-MM-dd'T'HH:mm:ss.SSSXXX | 2026-09-28T10:15:06.000-07:00 |
Return Value
Type | Description |
|---|---|
Python dictionary | The control-recipe EBR. Convert it with system.util.jsonEncode() when you need JSON. |
Procedure dictionary
Key | Type | Description |
|---|---|---|
Batch_ID | String | Batch ID. |
Batch_Name | String | Batch name. |
Recipe_Name | String | Master recipe name. |
Formula_Name | String | Formula name. Present only when the batch uses a formula. |
Name | String | Procedure logic name. |
LogicType | String | Procedure. |
Parameters | List | Recorded procedure parameter values. Omitted when the list is empty. |
Steps | List | Steps under the procedure, in execution order. Omitted when the list is empty. |
Step dictionary
A step that runs more than once appears once for each run.
Key | Type | Description |
|---|---|---|
Step | String | Step name. |
Phase | String | Phase name. <Unknown> when the phase cannot be resolved. |
Order | Integer | Step order. |
Type | String | Phase type, such as Timer or Unit Procedure. |
Status | String | Active, Executed, Skipped, or Pending. Pending is returned only when includeIdleSteps is True. |
Parameters | List | Recorded values for that run of the step. |
Sublogic | Dictionary | Nested Unit Procedure or Operation. Present on those step types. The nested dictionary uses Name, LogicType, Parameters, and Steps. |
Start, Terminator, Transition, And Begin, And End, Or Begin, and Or End are not included.
Parameter dictionary
Each recorded change is its own entry.
Key | Type | Description |
|---|---|---|
Name | String | Parameter name. <Unknown> when a history row cannot be matched to a parameter. |
Value | String, number, or Boolean | Recorded value. In MES 3.81.12 SP2, MES 4.83.1 SP2, and later, numbers and Booleans keep their native type. Date-time values are strings in |
TimeStamp | String | When the value was recorded, in dateTimeFormat. |
ChangedBy | String | Who or what recorded the value. Omitted when blank. |
DataType | String | Present on configured values that were not taken from history, such as pending steps. |
MinValue | String, number, or Boolean | Present only when the minimum differs from the parameter default. Dates use dateTimeFormat. |
MaxValue | String, number, or Boolean | Present only when the maximum differs from the parameter default. Dates use dateTimeFormat. |
UOM | String | Units. Omitted when empty. |
Documentation | String | Parameter documentation. Omitted when empty. |
A material or other resource parameter uses Name and Entries. Each entry has SubParameters, and each sub-parameter uses the parameter dictionary above.
Scope
Available in Gateway and Client scripts.
Edge Cases
An unknown batch ID raises Exception: Batch ID (<id>) not found.
A null BatchQueueEntry raises IllegalArgumentException: Unable to get batch EBR because a batch queue entry was not provided.
An invalid dateTimeFormat raises IllegalArgumentException: Invalid date-time format: <pattern>.
MES must be started. Otherwise the call raises IllegalStateException: Try request again once the MES system has fully started.
timeoutSeconds does not apply to a batch that has already left the queue. That EBR is read from the stored control recipe.
Calling this in a tight loop is expensive. The EBR is built from parameter history for the whole batch.
Example Usage
Python |
# Minimal ebr = system.mes.batch.queue.getBatchEBR('BATCH-001') print system.util.jsonEncode(ebr, 2) |
Python |
# Include steps that have not started, and format every date-time as a local date and time ebr = system.mes.batch.queue.getBatchEBR( 'BATCH-001', includeIdleSteps=True, includeSystemParameters=True, timeoutSeconds=5, dateTimeFormat='yyyy-MM-dd HH:mm:ss' ) print ebr['Recipe_Name'] for step in ebr.get('Steps', []): print step['Step'], step['Status'] for param in step.get('Parameters', []): print ' ', param['Name'], param['Value'], param['TimeStamp'] |
Python |
# Same call from a queue entry, using the default date-time format bqe = system.mes.batch.queue.getEntry('BATCH-001') ebr = system.mes.batch.queue.getBatchEBR(bqe, False, False) |
Related Functions
getRecipeEBR() — EBR for a validated master recipe. Accepts the same optional dateTimeFormat.
getBatchBOM() — Bill of materials for a control recipe. Accepts the same optional dateTimeFormat.
getRecipeBOM() — Bill of materials for a master recipe. Accepts the same optional dateTimeFormat.
getEntry() — Returns the BatchQueueEntry for a batch ID.
Return EBR in JSON
|
Scripting function queue.getBatchEBR() is available in versions:
|
This script returns EBR based on batchID. Min and max parameter settings are only included if they differ from default values.
Python |
ebr = system.mes.batch.queue.getBatchEBR('0001') json_ebr = system.util.jsonEncode(ebr,4) print(json_ebr) ##Can then write the EBR to a file using Ignition file scripting functions such as: ##system.file.writeFile() |
Output
JSON |
|
Sepasoft MES Module Suite