WinCC Professional UserAlarm.State Values and Process Tag Output in Alarm Text

Overview

The runtime API of Siemens WinCC Professional (and WinCC Comfort) exposes the active alarm population through the HMIRuntime.Alarms collection. From a TIA Portal VBScript you can address an alarm by its ID, read or write its State, attach a Comment and a UserName, and publish the change to the message system with Create or Clear. Two practical questions come up repeatedly in field engineering and in the WinCC Professional V13 / V14 / V15 / V16 / V17 / V18 scripting help:

1. What do the numeric values of UserAlarm.State mean? The Siemens example sets the State to 5. What does 1, 2, 4, 6 or 7 represent?
2. How do you embed the current value of a process tag into the alarm message text? The "Insert Tag Field" toolbar button that is familiar from WinCC Flexible and from the Comfort text editor is not visible in the Professional alarm configuration dialog.

This reference documents the bitfield encoding of the State property, walks through the alarm object model, and provides the configuration paths and code patterns required to embed live process values in the message shown on a WinCC Professional runtime screen. The same surface applies to PC Station, Comfort Panel, and Unified PC runtime installations that target the WinCC Professional programming model (TIA Portal V13 and later).

Prerequisites

• TIA Portal V13 SP1 Update 4 or later. The VBScript API surface for HMIRuntime.Alarms is stable from V13 through V18. This document also applies to V14, V15.1, V16, V17, and V18.
• WinCC Professional or WinCC Comfort runtime license (the API is identical between the two).
• A configured HMI connection between the PLC and the HMI panel or PC station. Discrete and analog alarms are only triggered once the connection is online.
• At least one user-defined alarm (discrete or analog) configured on an HMI tag in the project tree.
• Read access to the Siemens Online Support portal for the help system that matches your installed TIA Portal version: Siemens Industry Online Support.

The HMIRuntime.Alarms Object Model

The Alarms collection is reached from the global HMIRuntime object. You can iterate the whole collection, address an alarm by its string ID, or filter by class through the alarm class object.

The string parameter passed to Create and Clear is a free-form application identifier that is recorded in the alarm log. Use a consistent value per script origin (for example, "LevelScript", "PumpMonitor") so that post-mortem analysis of the alarm log can attribute the change to a specific script.

UserAlarm.State Bitfield Reference

The State property is a 32-bit integer that packs three independent boolean flags. The example value 5 from the Siemens V13 help script decodes to:

• Bit 0 (value 1): Came In
• Bit 1 (value 2): Going
• Bit 2 (value 4): Acknowledged

Therefore 5 = 1 + 4 → Came In + Acknowledged.

State Decoding Table

State Transition Diagram

In production systems the most frequently observed runtime values are 0 (cleared), 1 (raised, awaiting operator acknowledgment), 3 (transient at the moment of clear), 4 (post-clear re-ack), and 5 (latched and acknowledged). States 2, 6, and 7 appear only in the brief window between the Going edge and the final clear of an acked alarm.

Decoding State at Runtime

To extract the individual flags from a numeric State value, use the bitwise AND operator against the bit mask:

Dim s
Set objAlarm = HMIRuntime.Alarms("17")
s = objAlarm.State

If (s And 1) <> 0 Then Trace "Came In active"
If (s And 2) <> 0 Then Trace "Going active"
If (s And 4) <> 0 Then Trace "Acknowledged active"

Setting State Programmatically

To set a state, pass the sum of the desired bits. Writing UserAlarm.State = 5 raises the alarm and marks it acknowledged in a single step, which is useful when mirroring a downstream PLC state that already includes the acknowledgment bit:

objAlarm.State = 1     ' Came In only — raise, no ack
objAlarm.State = 5     ' Came In + Ack
objAlarm.State = 0     ' clear (call Clear afterwards to publish)

Triggering and Acknowledging User Alarms via Script

The reference script from the Siemens V13 WinCC Professional help performs the following sequence: looks up alarm ID "17", sets State to 5 (Came In plus Acknowledged), attaches a free-form comment and operator name, and finally calls Create "MyApplication" to publish the alarm to the message system.

Sub onClick(ByVal item)
    Dim UserAlarm
    Dim ID_UA
    Dim State_UserAlarm

    ID_UA = "17"
    State_UserAlarm = 5
    Set UserAlarm = HMIRuntime.Alarms(ID_UA)

    UserAlarm.State = State_UserAlarm
    UserAlarm.Comment = "empty Comment"
    UserAlarm.UserName = "Max Mustermann"
    UserAlarm.Create "MyApplication"
End Sub

Practical Variant: Raise Without Auto-Ack

If you need to raise the alarm without auto-acknowledging it (the typical operator-flow case), use:

Sub RaisePump3Overload(ByVal item)
    Dim alarm
    Set alarm = HMIRuntime.Alarms("17")

    alarm.State = 1                       ' Came In only
    alarm.Comment = "Pump 3 motor overload"
    alarm.UserName = HMIRuntime.Environment.UserName
    alarm.Create "PumpMonitor"
End Sub

Clear Without Re-Create

To clear the alarm without re-creating it, set State to 0 and call Clear:

Sub ClearPump3Overload(ByVal item)
    Dim alarm
    Set alarm = HMIRuntime.Alarms("17")

    alarm.State = 0
    alarm.Clear "PumpMonitor"
End Sub

Bulk Acknowledge All Active Alarms of a Class

For maintenance routines, iterate the collection and acknowledge every alarm whose state is 1 (Came In, not yet acknowledged):

Sub AckAllActiveErrors(ByVal item)
    Dim alarm
    For Each alarm In HMIRuntime.Alarms
        If alarm.Name = "Errors" Then
            If (alarm.State And 1) <> 0 And (alarm.State And 4) = 0 Then
                alarm.State = alarm.State Or 4   ' set the Ack bit
                alarm.UserName = HMIRuntime.Environment.UserName
                alarm.Create "BulkAck"
            End If
        End If
    Next
End Sub

Displaying Process Tag Values in Alarm Messages

There is no "Insert Tag Field" toolbar button in the alarm text editor for WinCC Professional user-defined alarms, in the way that WinCC Flexible and WinCC Comfort provide. The functionality is available, but the configuration path is different. Three reliable methods are documented below, in order of preference for production systems.

Method 1: Analog Alarm (Recommended for Numeric Tags)

1. In the project tree, open HMI Tags and select the tag you want to alarm on.
2. In the inspector window switch to the Properties tab and open the Alarms sub-section.
3. Add an analog alarm with the desired limit (for example, upper limit 80.0).
4. In the Alarm text field, enter the message you want operators to see.
5. The trigger value is automatically appended to the message because analog alarms carry the process value as an embedded parameter, evaluated at the moment the alarm is raised.

Analog alarms with the default message text render the trigger value as a numeric suffix. To customize the surrounding text, edit the message text field directly. The process value is always evaluated at trigger time and stored with the alarm record, so the Alarm Control and the alarm log both show the value that caused the alarm to be raised.

Method 2: Manual Tag Reference in the Alarm Text

For WinCC Professional, the message text supports curly-brace placeholders. Configure a user-defined alarm on the trigger tag, then edit the Message text with the following syntax:

Tank level exceeds setpoint: {HMI_Tag_1}%0.2f

The format specifier follows C printf rules:

The placeholder is evaluated at the moment the alarm is raised and the literal value is stored in the alarm log. The displayed value will not refresh if the underlying tag changes after the alarm is in the active list — the value is captured at the trigger edge.

Method 3: Dynamic Text from a Script

If the message text needs computed values (for example, a unit conversion, a status string, or a value composed from multiple tags), generate the text in VBScript and assign it to the Comment property before calling Create:

Sub RaiseLevelAlarm(ByVal item)
    Dim alarm
    Set alarm = HMIRuntime.Alarms("42")

    Dim level
    level = HMIRuntime.Tags("HMI_Tag_1").Read
    alarm.Comment = "Level = " & FormatNumber(level, 2) & " m"
    alarm.UserName = HMIRuntime.Environment.UserName
    alarm.State = 1
    alarm.Create "LevelScript"
End Sub

The Comment is stored in the alarm record and shown in the message view alongside the message text. This is the most flexible approach for derived values, and it is the only method that supports multi-tag composition. Place this kind of code behind a button click, a value-change event on the trigger tag, or a scheduler for periodic evaluations.

Configuration Path in TIA Portal

1. Open your HMI station in the project tree.
2. Expand HMI Tags and double-click the target tag.
3. In the Properties inspector, switch to the Alarms sub-section (or the Events tab in older TIA Portal versions, where the alarm section lives at the bottom of the inspector).
4. Click Add and choose either Discrete alarm (boolean trigger) or Analog alarm (limit-based trigger).
5. Select the alarm class. Common classes are Errors, Warnings, Information, plus any custom classes defined under Runtime Settings → Alarm Classes.
6. Enter the Message text, optionally with tag placeholders (see Method 2 above).
7. If the alarm requires acknowledgment, leave the Acknowledgment checkbox enabled in the class properties. If the class is configured as "without acknowledgment", UserAlarm.State = 5 will not produce the visible "acknowledged" indicator on the Alarm Control.
8. Compile and download the HMI station to the runtime.
9. Trigger the tag value and verify in the WinCC Alarm Control that the message contains the expected process value.

Working Code: Complete Raise, Acknowledge, and Clear Cycle

The following script demonstrates a full alarm lifecycle. It is intended for installation behind a button on a WinCC Professional screen. The script reads the trigger tag value at the moment of raise, embeds the value in the Comment, raises the alarm, waits for the operator to acknowledge, and provides a separate button to clear the alarm.

' --- Button "Raise": raises alarm with live tag value in the comment
Sub btnRaise_Click(ByVal item)
    Dim alarm
    Set alarm = HMIRuntime.Alarms("42")

    Dim level
    level = HMIRuntime.Tags("HMI_Tag_1").Read

    alarm.State = 1                                    ' Came In, not acked
    alarm.Comment = "Tank 1 level = " & FormatNumber(level, 2) & " m (limit 80.00 m)"
    alarm.UserName = HMIRuntime.Environment.UserName
    alarm.Create "LevelMonitor"
End Sub

' --- Button "Ack": operator acknowledges the active alarm
Sub btnAck_Click(ByVal item)
    Dim alarm
    Set alarm = HMIRuntime.Alarms("42")

    If (alarm.State And 1) <> 0 And (alarm.State And 4) = 0 Then
        alarm.State = alarm.State Or 4                  ' set the Ack bit → 1+4 = 5
        alarm.UserName = HMIRuntime.Environment.UserName
        alarm.Create "LevelMonitor"
    End If
End Sub

' --- Button "Clear": removes the alarm from the active list
Sub btnClear_Click(ByVal item)
    Dim alarm
    Set alarm = HMIRuntime.Alarms("42")

    alarm.State = 0
    alarm.Clear "LevelMonitor"
End Sub

Verification Checklist

Performance and Runtime Considerations

• The HMIRuntime.Alarms collection is rebuilt on every access. Cache the result in a local variable for repeated lookups within the same script, instead of calling HMIRuntime.Alarms(ID) multiple times.
• Writing to State, Comment, and UserName is synchronous. Avoid invoking these inside a 100 ms cyclic script when the alarm list is large (more than roughly 500 entries); the lock contention with the Alarm Control will show up as UI lag.
• Alarm IDs are case-sensitive strings. "17" and "017" are different IDs in the collection. Always pass the ID as a string to avoid VB coercion issues with numeric PLC addresses.
• The Create and Clear methods take a free-form application identifier. Use a consistent string per script origin to ease post-mortem analysis of the alarm log.
• For a large fleet of alarms, prefer tag-side analog alarms over script-side raises. The runtime evaluates analog alarm limits on the HMI tag update, which is more efficient than a polling script that calls HMIRuntime.Tags(...).Read on a fixed schedule.
• Use the TriggerTag property (V15.1+) to read the live value of the trigger tag from the alarm object without a separate HMIRuntime.Tags(...).Read call.

Version Notes

Verify the available properties for your specific TIA Portal version by opening the WinCC Help (F1) on the script editor and searching for HMIRuntime.Alarms. The TIA Portal help portal entry point is available at Siemens Industry Online Support.

Troubleshooting Matrix

WinCC Comfort vs Professional: API Surface Differences

Both WinCC Comfort (panel-side) and WinCC Professional (PC-side) expose the same HMIRuntime.Alarms collection, but the configuration experience for the alarm text editor differs. Comfort panels include an "Insert tag field" button in the message text editor; Professional uses the manual curly-brace placeholder syntax documented in Method 2 above. The runtime behavior of the resulting alarm is identical, and scripts that use HMIRuntime.Alarms are portable between the two runtimes without modification.

Frequently Asked Questions