User Message Phase

Sepasoft MES Module Suite

User Message Phase

The User Message phase shows a message to the operator while a batch is running. Place it on a Procedure, Unit Procedure, or Operation chart when the operator needs an instruction, a warning, or a hold until they confirm they have read the message.

The built-in phase name is User Message. In the Batch Recipe Editor it is under Phases > Built-In Phases. The phase description is “Batch phase used to display a message to the user.”

A message appears in the Batch Message List and in the Messages section of the Batch Controller after the step starts. The same list also shows Value Prompt messages and equipment messages. This page covers the User Message phase only.

When to use it

Goal	Setting
Show a message and let the next transition decide when to move on	`Requires_Acknowledgement` = `False`
Hold the step until an operator confirms the message	`Requires_Acknowledgement` = `True`
Ask the operator to type a value into a parameter	Use a Value Prompt phase

The phase can run on a procedure, a unit procedure, or an operation. It is included in the electronic batch record. It does not bind equipment resources, it is not a permissive-start phase, and it does not offer manual execute or force complete.

Messages created on a procedure have no unit. Messages created on a unit procedure or operation carry the unit path of the logic that is running.

The phase runs on the shared action thread pool, together with No Action, E-Signature, Document, Script, Set Parameter, Start, and Terminator. Other phase types use a dedicated thread.

How the step runs

The step stamps Date_Time when it starts, then follows Requires_Acknowledgement.

Acknowledgement is not required

Requires_Acknowledgement defaults to False.

The step starts and writes Date_Time.
Complete is set to True immediately.
The following transition controls when the chart moves on. A typical expression is the step’s Complete parameter, for example P8.Complete.
The message stays in the message list. It is not removed when the step finishes.

Acknowledged_By, Acknowledged_Date_Time, and Acknowledged_By_Ref are not written to the electronic batch record for this run.

Acknowledgement is required

The step starts, writes Date_Time, and stays running.
The message stays in the list until it is acknowledged.
An operator acknowledges it from the Batch Message List or the Batch Controller, or a script calls system.mes.batch.queue.acknowledgeMessage.
The step writes Acknowledged_Date_Time, Acknowledged_By, and Acknowledged_By_Ref, sets Complete to True, and completes.
The message leaves the list after it is acknowledged.

The batch must be in a running state. Acknowledgement is rejected when:

the batch is not running
the step has not started (Date_Time is empty)
Complete is already True
the person who acknowledged the message is missing

Ending the chart or shutting down the batch also ends a step that is waiting for acknowledgement.

Restart and resume

Resetting the step clears Complete, Date_Time, Acknowledged_By, Acknowledged_By_Ref, and Acknowledged_Date_Time.

If the step is resumed and Begin_Date_Time is already set, the phase does not write a new copy of Message, Severity, Requires_Acknowledgement, Date_Time, Complete, Acknowledged_By, or Acknowledged_Date_Time.

What the operator sees

The message is available after Date_Time is set.

`Requires_Acknowledgement`	Shown in the message list
`False`	Stays visible after the step completes
`True`	Visible until the operator acknowledges it

The Batch Message List can limit which messages appear by severity. A message is shown when its Severity is between severityFilterMin and severityFilter, including both ends. The default range shows every severity. Set severityFilterMin to one more than a level to hide that level and everything below it. Use a separate list for each audience, such as operators, supervisors, and maintenance.

Severity is an integer. The built-in default is 1. Lower numbers sort first when messages are listed for a unit filter or for a whole batch.

Parameters

These parameters belong to the User Message phase. The step also has the standard phase parameters (State, Command, Begin_Date_Time, End_Date_Time, Duration, Step_Name, and the rest).

Set on the recipe

These values come from the recipe. A formula may override them. They are recorded as All to Object and History.

Parameter	Type	Default	Description
`Message`	String	(none)	Text shown to the operator. Required unless a calculation supplies it. Calculations are supported.
`Severity`	Integer	`1`	Severity used by the message list filter and sort. Must be `0` or greater.
`Requires_Acknowledgement`	Boolean	`False`	`True` holds the step until the message is acknowledged. `False` lets the next transition control the flow.

If Message has a calculation on the phase, that calculation is the one the step uses. A different calculation entered on the recipe step does not replace it. Recipe validation accepts a calculation in place of a literal message. It does not evaluate the calculation.

Written while the batch runs

These values are filled in by execution. They are not entered on the recipe. They are recorded as All to Object and History.

Parameter	Type	Default	Description
`Date_Time`	Date	(empty)	Time the message was displayed. The message is not listed until this is set.
`Acknowledged_Date_Time`	Date	(empty)	Time the operator acknowledged the message. Written only when acknowledgement is required.
`Acknowledged_By`	String	(empty)	Person who acknowledged the message. Written only when acknowledgement is required.
`Acknowledged_By_Ref`	String	(empty)	Hidden reference to that person. Not shown in the recipe editor.
`Complete`	Boolean	`False`	`True` when the step is done. Set immediately when acknowledgement is not required. Set when the operator acknowledges the message when acknowledgement is required.

Validation

Recipe validation reports these problems:

Parameter	Rule	Message
`Message`	Must have text, or a calculation	`Message parameter value for User Message Phase (<step>) is invalid. It must be assigned a value.`
`Severity`	Must be an integer of `0` or greater	`Severity parameter value for User Message Phase (<step>) is invalid. It must be assigned a positive integer value.`
`Requires_Acknowledgement`	Must be `True` or `False`	`Requires_Acknowledgement parameter value for User Message Phase (<step>) is invalid. It must be assigned a boolean value.`

0 is a valid severity. The validation text says “positive,” and 0 still passes.

Electronic batch record | EBR

Every User Message parameter above is included in the batch record with recording type All to Object and History, unless you change it on a custom phase.

When acknowledgement is not required, Acknowledged_By, Acknowledged_Date_Time, and Acknowledged_By_Ref are left out of the record for that run.

When acknowledgement is required, Acknowledged_By_Ref is still left out of the initial write. Acknowledged_By and Acknowledged_Date_Time are written when the operator acknowledges the message.

Custom User Message phases

The built-in phase can be used as the parent of a custom phase. In the Batch Phase Manager, a custom User Message phase can change Recording Type on its parameters.

Recording Type	What the batch record shows
All to History	Every value change
All to Object and History	Every value change
Last to History	Only the final value, and only after the step completes
All to Object and Last to History	Only the final value, and only after the step completes
All to Object	No value changes in the batch record
Changes Not Saved	No value changes in the batch record

The product name of the last option is Changes Not Saved.

Example: recipe step

On the chart, drag User Message from Phases > Built-In Phases.
Open the step settings.
Set Message to the text the operator should read. Example: Confirm the vessel is vented before continuing.
Leave Severity at 1, or set another integer of 0 or greater.
Set Requires_Acknowledgement to True to wait for the operator, or leave it False to continue under the next transition.
Add a transition under the step. Set its expression to the step’s complete flag, for example P8.Complete.
Validate the recipe.

To loop back to an earlier step, place the User Message on one branch of an Or Begin and draw the transition from this step back to that earlier step. The Value Prompt and User Message tutorial on docs.sepasoft.com walks through that chart.

Script functions

These gateway functions read and acknowledge messages from a running batch. They apply to User Message steps and to the other message types in the same list.

getMessages

Returns the messages for running batches.

system.mes.batch.queue.getMessages(unitFilter) system.mes.batch.queue.getMessages(batchQueueEntry)

Parameter	Type	Required	Description
`unitFilter`	String	One of the two call patterns	Equipment path of the units to include. Format: `Enterprise\Site\Area\Process Cell\Unit`. `*` matches any number of characters. `?` matches one character. Separate paths with a comma.
`batchQueueEntry`	BatchQueueEntry	One of the two call patterns	Queue entry whose messages should be returned.

Type	Description
List of BatchMessage	Messages for the matching units, or for every unit on that batch. An idle queue entry returns an empty list.

The unit-filter call returns messages from every running batch whose unit path matches. Results are ordered by severity, lowest first. A procedure-level message has no unit path, so a unit filter does not include it. Pass the queue entry to see every message on that batch.

# Messages for one unit, or for similarly named units msgList = system.mes.batch.queue.getMessages('Enterprise\\Site\\Area\\Process Cell\\Unit ?') for m in msgList:     print m  # Two units msgList = system.mes.batch.queue.getMessages(     'Enterprise\\Site\\Area\\Process Cell\\Unit 1, Enterprise\\Site\\Area\\Process Cell\\Unit 2' )  # Every message on each active batch qList = system.mes.batch.queue.getEntries(0, 1000, '') for q in qList:     msgList = system.mes.batch.queue.getMessages(q)     for m in msgList:         print m.getStepName(), m.getMessage(), m.getSeverity(), m.getRequiresAcknowledgement()

acknowledgeMessage

Acknowledges one message. Use this when Requires_Acknowledgement is True. Calling it sets Acknowledged_By, Acknowledged_Date_Time, and Acknowledged_By_Ref, sets Complete to True, and completes the step.

system.mes.batch.queue.acknowledgeMessage(batchMessage)

Parameter	Type	Required	Description
`batchMessage`	BatchMessage	Required	Message to acknowledge. Call `setAckBy` with the person name before this function. The message must already identify its step.

Type	Description
None	The function returns nothing. It raises an error when the message cannot be acknowledged.

# Minimal m.setAckBy('Tom') system.mes.batch.queue.acknowledgeMessage(m)  # Acknowledge one named step on a running batch qList = system.mes.batch.queue.getEntries(0, 1000, '') for q in qList:     msgList = system.mes.batch.queue.getMessages(q)     for m in msgList:         if m.getStepName() == 'O6' and not m.hasAckBy():             m.setAckBy('Tom')             system.mes.batch.queue.acknowledgeMessage(m)             break

Acknowledgement fails with one of these errors:

Condition	Error
The message has no step path	`Batch message does not contain a path to a logic step.`
The batch is not running	`Unable to acknowledge message for batch ID (<id>) because the phase is in (<state>) state.`
No running batch has that id and step	`Error acknowledging batch message. No running batch queue entry with ID (<id>) and step (<step>) was found.`
The step does not exist	`A message for step (<step>) is not found.`
The step has not started	`Message for step (<step>) cannot be acknowledged because it is not active.`
The step is already complete	`Message for step (<step>) has already been acknowledged.`
`setAckBy` was not called	`Unable to acknowledge batch message for step (<step>) because the acknowledge by is missing.`

Value Prompt — Asks the operator to enter a value. The prompt stays in the message list until the value is entered. Use system.mes.batch.queue.assignMessageValue.
Equipment phase message — A Message value written by the PLC, a script, or a Set Parameter step. Those parameters are named Message_Requires_Ack, Message_Ack_By, Message_Ack_Date_Time, Message_Date_Time, and Message_Ack_Confirm. They are not the User Message parameters.
Batch Message List — Table of operator messages, with unit and severity filters.
Batch Controller — Shows the same messages and can acknowledge them.

Sepasoft MES Module Suite

User Message Phase