Resolving WinCC Professional V18 Alarm Email Trigger Failures

1. Problem Description

Engineers deploying Siemens WinCC Professional V18 on a TIA Portal project commonly integrate the Siemens HMI Toolbox to dispatch operator messages by SMTP. The toolbox provides a complete set of tags, VB scripts, screen templates and a project library that wraps the WinCC SMTP client. In the field, a consistent symptom appears: the manual "Send Mail" button or scheduled test send delivers mail successfully, but the runtime fails to dispatch an email automatically when an alarm event occurs. The trigger tag never fires, the VB function is never called, or the alarm control never propagates the message text to the mail body.

This article classifies the root causes, walks through the trigger wiring, and provides the GMsgFunction (C script) fallback for projects that need a true per-alarm callback. References to the official Siemens entry Entry ID 106226404 – Sending e-mails with WinCC Professional (TIA Portal) and the WinCC Unified email use-case documentation at Send E-Mail (WinCC Unified, V21) anchor every procedure to manufacturer documentation.

2. Architecture of the WinCC Professional V18 Email Subsystem

The HMI email subsystem in WinCC Professional V18 has four cooperating layers. A failure in any one of them produces the observed "manual works, alarm trigger does not" symptom.

When the manual button uses the same SMTP client and the same library, but a scheduled callback cannot deliver mail, the problem is isolated to layer 3 (dispatcher) or layer 4 (alarm source). Layer 1 and layer 2 are proven functional by the manual test.

3. Root Cause Matrix

The following matrix maps the most common field failures to their symptom and the corrective action. Use it as a triage tool before opening the project.

4. The Trigger_Email Tag Mechanism

The Siemens HMI Toolbox implements a publish/subscribe pattern with a single boolean tag, conventionally named Trigger_Email. The alarm event (or any other source) toggles the tag, and a scheduled task listens for the change and runs the mail-build function.

4.1 Declaring the Tag

1. In the TIA Portal project tree, open HMI Tags → Default tag table.
2. Add an internal tag named exactly Trigger_Email with data type Bool and initial value 0.
3. Confirm the tag is internal and not acquired from the PLC; it must not be a process tag.
4. If your project uses multiple HMIs, the tag must exist on every device that will dispatch mail.

4.2 Wiring the Alarm Event

1. Open HMI Alarms → Discrete Alarms.
2. Select the alarm that should dispatch a mail.
3. Switch to the Events tab.
4. For the Incoming event, configure the function list as:
   1. Set tag → Trigger_Email = 1
   2. (Optional) Reset tag → Trigger_Email = 0 after a 1 s scheduled task, so the next event can retrigger

5. Configuring the Scheduled Task for Automatic Dispatch

1. Open Schedules → Scheduled Tasks in the HMI device editor.
2. Add a new task named SendEmail_OnTrigger.
3. Set the trigger to On change of tag.
4. Select the tag Trigger_Email.
5. Choose condition: Value = 1 (not just "any change").
6. Under Function list, insert the VB script SendEmail from the toolbox library.

For the reset, add a second task:

1. Trigger: On change of tag → Trigger_Email = 1.
2. Delay: 1 second.
3. Function: Set Trigger_Email = 0.

6. Using GMsgFunction for Native C-Script Alarm Events

When the toolbox pattern is too rigid (one tag must be wired per alarm), use the C-script callback GMsgFunction. WinCC Professional invokes this function for every alarm state change, including incoming, outgoing, acknowledgement and operator actions. Because the callback is C, it can call into the runtime C-API for tags and the SMTP client directly.

6.1 Declaring the Function

1. Open Project Library → HMI Email Toolbox → C Scripts.
2. Add a new C function named exactly GMsgFunction. The name is reserved and recognized by the WinCC alarm control.
3. The function signature must be:

BOOL GMsgFunction(DWORD dwMsgService, DWORD dwMsgID, LPCTSTR pszMsgText,
                  LPCTSTR pszMsgTime, DWORD dwMsgState, LPVOID lpUserData)

6.2 Pushing Alarm Text to an Internal Tag

GMsgFunction cannot directly call VBScript, so the recommended pattern is to populate a buffer tag that the VB mail-build script later reads.

#include "apdefap.h"
BOOL GMsgFunction(DWORD dwMsgService, DWORD dwMsgID, LPCTSTR pszMsgText,
                  LPCTSTR pszMsgTime, DWORD dwMsgState, LPVOID lpUserData)
{
    // dwMsgState bit 0 = incoming, bit 1 = outgoing, bit 2 = acknowledged
    if (dwMsgState & 0x01)                       // incoming only
    {
        SetTagChar("Mail_Subject", "HMI Alarm");
        SetTagChar("Mail_Body",    pszMsgText);
        SetTagChar("Mail_Time",    pszMsgTime);
        SetTagBit ("Trigger_Email", 1);          // arm dispatcher
    }
    return TRUE;
}

6.3 Wiring the Function

1. Open HMI Alarms → Settings → Functions.
2. Under Alarm function, select GMsgFunction.
3. Compile and download the project. The runtime will call this function for every alarm state transition on this device.

7. Wiring the Incoming Alarm Event to the Trigger

For discrete alarms with a small, fixed set of message IDs, the simplest wiring is per-alarm event scripts. The toolbox script SendEmail_Discrete reads the message text and builds a complete RFC 822 envelope. Use this when the alarm count is under approximately twenty and the message text is fixed.

1. Open the alarm → Events → Incoming.
2. Add the function list: Set tag → Mail_Subject = alarm name; Set tag → Mail_Body = alarm text; Set tag → Trigger_Email = 1.
3. For analog alarms, use the value and limit tags in the body: "PV=" + GetTagFloat("ProcessValue").

8. SMTP and Runtime Configuration

Open the HMI device → Properties → Email settings and configure:

Open Runtime Settings → Services → Email and confirm the service is enabled and the device runtime is started with administrative rights. Without administrative rights, the SMTP client cannot open the credentials vault on first use, and the manual send will succeed only once after the credentials are cached in the registry.

9. V18-Specific Behavior and Firmware Considerations

WinCC Professional V18 introduced an updated alarm event pipeline that runs asynchronously to the graphics thread. In practice this means a small race condition: a scheduled task triggered by Trigger_Email may fire before the VBScript event that wrote Mail_Body has committed the value to the tag cache. Symptoms include empty subject lines or mails with the previous event's body.

Two mitigations are supported in V18:

1. Configure the scheduled task with a 200–500 ms delay before running the mail-build script. This is sufficient for the tag cache to settle in nearly all cases.
2. Upgrade to TIA Portal V18 Update 5 or later, which contains the alarm-event ordering fix described in the V18 update readme.

Projects upgraded from V17 must re-import the toolbox master copy; V18 changed the internal tag naming convention and the old names (e.g. TriggerMail) are silently ignored.

10. Verification and Commissioning Checklist

1. Open HMI Tags → Default tag table → Start value and confirm Trigger_Email = 0 at runtime start.
2. Force the alarm in the PLC (or use the alarm simulator). The alarm should appear in the alarm control within 1 s.
3. Watch Trigger_Email in the HMI tag diagnostics; it should pulse 0 → 1 → 0 within approximately 1.2 s.
4. Confirm the scheduled task SendEmail_OnTrigger appears in the runtime log with status "Executed".
5. Open the SMTP relay log and verify a connection from the HMI station IP on the configured port.
6. Confirm the recipient mailbox receives the message with the correct subject and body.
7. Force the same alarm a second time within 5 s. The reset task must have cleared Trigger_Email; otherwise only the first event is delivered.

11. Field-Proven Pitfalls and Diagnostic Steps

11.1 The "Tag Exists, Task Never Fires" Symptom

The most common report is: the alarm comes in, the function list runs, the tag value changes, but the scheduled task does not. The cause is almost always a mismatch between the configured tag and the configured trigger. The scheduled task's trigger dialog stores the tag name as a string and the runtime resolves it at load time. If the project is renamed, the device is renamed, or the tag is renamed in the HMI tag table, the trigger silently fails to bind. Re-open the task, re-select the tag, and download the project again.

11.2 The "SMTP Relay Rejects STARTTLS" Symptom

WinCC V18 implements STARTTLS only on port 587. If the corporate relay listens on 465 with implicit TLS, the connection appears to hang in the trace, and the alarm task reports a generic "Send failed". Two workarounds: deploy a local SMTP relay (e.g. smtp4dev, Postfix in relay mode) that accepts 587 and forwards to 465, or use a STARTTLS-capable provider.

11.3 The "Manual Works Once, Alarm Never Works" Symptom

The SMTP client caches the credentials on first send. If the runtime is restarted and the HMI device properties still have the credentials stored, the alarm path may not re-authenticate before the watchdog. Open the device properties, re-enter the password, mark the option Store in project, recompile, and re-download. This pattern matches RC4 in the matrix.

11.4 The "GMsgFunction Is Never Called" Symptom

If the function name is correct and the project compiles, the function is still only invoked if the alarm control is loaded. On screens that do not host the alarm control, the runtime may not call GMsgFunction. Add a permanent area window with the alarm control on the start screen, or invoke the function through the alarm control's Function property explicitly.

11.5 The "Unified vs Professional Confusion" Symptom

The WinCC Unified line (Panels and Runtime Unified) uses a different mail API and a different alarm subscription model, as documented in Send E-Mail (WinCC Unified, V21). If the project runs on a Unified Comfort Panel, the Professional toolbox does not apply, and the alarm subscription must be configured under Unified Alarms → Subscriptions → Actions.

12. Summary and Field Notes

The "manual email works, alarm email does not" symptom in WinCC Professional V18 is a dispatcher-layer failure, not an SMTP failure. The diagnostic path is:

1. Confirm the trigger tag is internal and bound.
2. Confirm the scheduled task trigger and condition are configured for the explicit 0→1 edge.
3. Confirm the alarm event fires the function list that sets the tag.
4. Confirm the mail-build script reads the buffer tag after the trigger event has been committed (add a 200–500 ms delay in V18).
5. If step 4 is not feasible, migrate to the GMsgFunction C-callback with an internal tag bridge.

For deployments beyond a handful of alarms, prefer the C-callback over per-alarm event scripts. It centralizes the mail envelope construction, reduces the number of function lists, and is the only mechanism that scales to alarm classes.