Displaying Pop-Ups on WinCC Unified Using a PLC Tag

Overview

Many Siemens HMI applications require operator messages that surface only when the controller asks for them. The classic approach—hard-wiring visibility animations to dozens of discrete bits—does not scale beyond a handful of alarms and forces an HMI recompile every time a new message is added. A cleaner pattern, supported natively in WinCC Unified (TIA Portal V17 and later, including the V18/V19 releases), is to expose a single integer tag from the PLC and let a Unified JavaScript script interpret its value to open, swap, or close a popup window.

This article documents a production-grade implementation of that pattern, including:

• A scalable A01-Message, A02-Message… naming convention so the controller can request any message by number.
• A loop that closes any existing "Message" popup before opening a new one—eliminating the need to send a dedicated close command from the PLC.
• A sentinel value (255) used by the PLC to force-close every open Message popup.
• Two execution hosts for the script—an invisible object on the active screen and a Scheduled task—with a discussion of when to prefer each.
• Commissioning, verification, and a troubleshooting matrix that covers the common failure modes seen in the field.

The scripting surface used here is the WinCC Unified "Global Scripting" JavaScript API, documented in the TIA Portal help under WinCC Unified - Scripting (JavaScript). See the TIA Portal V18 WinCC Unified Help for the authoritative reference.

Prerequisites

Architecture and Data Flow

The complete control loop is intentionally small:

1. The PLC writes an integer to a configured HMI tag (e.g. Numero_Page_Actuelle) each time it wants a new message displayed.
2. The HMI runs a JavaScript on a 1 s schedule. The script reads the tag via Tags("Numero_Page_Actuelle").Read().
3. If the value is in the range 1…254, the script composes the popup screen name A<value>-Message and calls UI.SysFct.OpenScreenInPopup(...).
4. If the value is exactly 255, the script iterates over UI.PopupScreenWindows and closes any open window named Message.
5. If the value is 0, the script does nothing—useful as a "neutral" state the PLC can hold when no message is active.

Step-by-Step Implementation

1. Create the PLC Tag

In the S7-1500 / S7-1200 project, declare a tag (e.g. "DB_HMI".Numero_Page_Actuelle) of type Int. Wire it wherever your application logic needs to surface a message. The convention used in the source is:

• 0 = no message
• 1…254 = display popup A01-Message … A254-Message
• 255 = force-close any open Message popup

2. Expose the Tag to the HMI

In the Unified project, create an HMI tag of the same name (e.g. Numero_Page_Actuelle) and connect it to the PLC tag through the standard HMI connection. Acquisition mode: Cyclic continuous, 1 s. Make sure the connection is online before testing.

3. Create the Popup Screens

Under Project tree ▸ Screens, create one screen per message number. Name them exactly:

A01-Message
A02-Message
A03-Message
...
A99-Message

These screens are normal WinCC Unified screens with whatever layout you need (text, iconography, Acknowledge / Cancel buttons). They have no special configuration beyond their name.

4. Create a Host Screen with an Invisible Script Object

On your main runtime screen (or any screen that stays loaded), place a small rectangle object and set its Visibility animation to 0 (always hidden). Attach the script shown in §5 to the Miscellaneous ▸ Events property of this invisible object, or, more commonly, to a Scheduled task that fires every second.

5. Create the Script

Create a new JavaScript file in Project tree ▸ Scripts ▸ Global modules (or a local script on the invisible object). Paste the following annotated implementation:

// ----------------------------------------------------------
// Dynamic popup controller for WinCC Unified
// Reads an integer tag written by the PLC and opens the
// popup screen whose name matches "A<value>-Message".
// Tag value 255 closes any open "Message" popup window.
// ----------------------------------------------------------

// Local alias to the global UI root. Always assign once and
// reuse the local "ui" reference; some runtime revisions
// have shown race conditions when UI is accessed directly.
let ui = UI;

// Read the integer tag the PLC controls.
let Prod_MsgVis = Tags("Numero_Page_Actuelle").Read();

// Fixed popup window geometry. Adjust to suit your layout.
let left = 290;   // X position in pixels relative to parent
let top  = 65;    // Y position in pixels relative to parent

if (Prod_MsgVis > 0 && Prod_MsgVis < 255) {
    // --- OPEN OR REPLACE A POPUP -----------------------------
    // Close any existing "Message" popup first so that we
    // never end up with two stacked popups of the same name.
    for (let i = ui.PopupScreenWindows.Count - 1; i >= 0; i--) {
        if (ui.PopupScreenWindows(i).Name === "Message") {
            ui.PopupScreenWindows(i).Close();
        }
    }

    // Build the screen name with two-digit zero padding so the
    // PLC value 7 becomes "A07-Message" and not "A7-Message".
    let screenName = "A" + Prod_MsgVis.toString().padStart(2, "0") + "-Message";

    // OpenScreenInPopup signature:
    //   popupName, screenName, bModal, parentName,
    //   left, top, bCloseOnLostFocus, path
    ui.SysFct.OpenScreenInPopup(
        "Message",
        screenName,
        false,        // non-modal: operator can still touch parent
        "Message",    // logical parent (matches popupName is OK)
        left,
        top,
        false,        // do not auto-close on focus loss
        "~/Screen"    // path to the popup screen
    );
}
else if (Prod_MsgVis === 255) {
    // --- FORCE-CLOSE ALL MESSAGE POPUPS ----------------------
    // Iterate from the top of the collection; closing items
    // while iterating forward corrupts indices.
    let count = ui.PopupScreenWindows.Count;
    for (let i = 0; i < count; i++) {
        let j = count - i - 1;     // reverse index
        if (ui.PopupScreenWindows(j).Name === "Message") {
            ui.PopupScreenWindows(j).Close();
        }
    }
}
// else: Prod_MsgVis == 0 → no action, no popup

6. Wire the Script to a Trigger

Two equally valid hosts are used in practice:

7. Add a Manual Re-Open Helper (Optional)

Operators sometimes close a popup by clicking the window's X without acknowledging. To re-open the most recent message, place a button anywhere on the main screen with this minimal script:

// Re-open the popup corresponding to the current tag value.
// Useful after an operator has dismissed a popup manually.
let Prod_MsgVis = Tags("Numero_Page_Actuelle").Read();
let screenName  = "A" + Prod_MsgVis.toString().padStart(2, "0") + "-Message";
let ui = UI;
ui.SysFct.OpenScreenInPopup(
    "Message", screenName, false, "Message",
    290, 65, false, "~/Screen"
);

Script Breakdown and Key Engineering Details

Why let ui = UI;?

The runtime exports the global UI object as a property of the script context. Some Unified builds and some scheduled-task runners have produced intermittent "UI is not defined" errors when the script body uses UI directly—especially inside arrow functions or asynchronous callbacks. Capturing a local reference first is a defensive habit and is widely recommended on the WinCC Unified Scripting Reference.

Why a Reverse Index for Closing

Closing a window while iterating a for loop over the same collection shifts the indices of all later elements. Two patterns avoid the bug:

• Iterate backwards (i = Count - 1; i >= 0; i--).
• Snapshot the count and access items by reverse index (count - i - 1).

Both forms are shown in the script for clarity; in production code, pick one and stay consistent.

The padStart(2, "0") Trick

Unified screen names are case-sensitive and must match the filename exactly. A PLC value of 7 would otherwise produce A7-Message, which does not exist if your screens are A07-Message. String.prototype.padStart guarantees the two-digit form, so values 1…9 become 01…09 and the lookup is uniform up to 99. If you need more than 99 messages, switch to three-digit padding (padStart(3, "0")) and rename your screens A001-Message … A254-Message.

Modal vs. Non-Modal

The third argument of OpenScreenInPopup is a boolean modal flag:

• false (used here): operator can still interact with the parent screen—useful for "informational" messages that should not block.
• true: parent screen is dimmed and disabled until the popup is acknowledged. Use this for safety-relevant messages, but be aware that the user cannot navigate away or press an emergency stop on the parent if the popup hangs.

Parameter Mapping for SysFct.OpenScreenInPopup

Verification and Commissioning

1. Compile the Unified project and start the runtime with the HMI connection online.
2. From the PLC online watch table, force Numero_Page_Actuelle = 1. The popup A01-Message must appear within one tag-acquisition cycle (≤ 1 s).
3. Force Numero_Page_Actuelle = 2. The first popup must close and A02-Message must open in its place, again within one cycle.
4. Force Numero_Page_Actuelle = 255. The open popup must close; the next 0 write must leave the screen clear.
5. Force Numero_Page_Actuelle = 0 for ten seconds and verify that no popup appears and CPU remains nominal.
6. Test the manual re-open button from §7: open A01-Message, click the X to dismiss it manually, click the re-open button, and confirm the popup returns.

Troubleshooting Matrix

Design Notes and Edge Cases

Maximum message count: With padStart(2, "0") the script supports 1…254 distinct screens. To go beyond 254, change the padding to 3 digits, add screens A001-Message … A<N>-Message, and reduce the sentinel value to something that fits the range, e.g. 9999 as "close all" while keeping the comparison Prod_MsgVis < sentinel.

Race between PLC write and script read: Because the script runs on a 1 s schedule, a tag value that changes twice within one second can be missed. If your PLC logic toggles the tag rapidly (write message, wait, write 0), insert a Ton timer of at least 1.2 s between the two writes.

Redundant close on swap: Strictly speaking, the pre-close loop is not required when the PLC writes a different valid message number—Unified will replace a popup that uses the same popupName. The loop is, however, mandatory when the PLC sends 255 (force-close) and is also defensive against orphaned popups from a previous runtime session. Keep it in.

Why the sentinel 255? It is the maximum unsigned 8-bit value and a common "invalid / no-data" marker in legacy Siemens code. The script treats it explicitly, so 0…254 is the safe range for actual messages and 255 is reserved for close. If you need the full 0…255 range for messages, switch the sentinel to -1 (or any out-of-range value) and update the comparison accordingly.

Localized messages: Because the PLC drives the message number and the HMI selects the screen, you can ship the same PLC code with completely different screen libraries per language. The translation work is done once in the HMI project, not in the PLC.

FAQ