Scripting WinCC Unified IO Field Input Value via JavaScript

Overview

WinCC Unified (TIA Portal V17 and later, including the current V20 release line) exposes a fundamentally different scripting model for screen objects than WinCC V7 or WinCC Professional (Comfort). The legacy InputValue property and the InputValueChanged event do not exist on the Unified IO field object. Engineers migrating automation code, validation routines, or computed-write logic from V7/Comfort panels to Unified Runtime (RT Unified) panels or PC-based Unified Stations frequently discover that the familiar property/event pair is gone, and an attempt such as item.InputValue.set(...) silently throws an undefined reference at runtime.

The Unified replacement pattern uses two distinct touch points on the IO field screen object:

1. The ProcessValue property — used for reading the tag into the field on every cycle (visualization, output direction).
2. The InputFinished event — fires once after the operator confirms input (Enter, focus loss, or configured termination). Inside this event handler the script must call item.ProcessValue.set(...) to write the entered value back to the PLC tag.

This article documents the canonical Siemens-recommended JavaScript pattern, the Tags() collection access used for both directions, and the complete TIA Portal V20 configuration procedure for an RT Unified panel or Unified PC station. All code samples are written against the TIA Portal V20 scripting API as documented in the official Siemens TIA Portal Help and the WinCC Unified engineering manual.

Prerequisites

Before scripting an IO field input, verify that the engineering environment and runtime target meet the following requirements:

• TIA Portal: V17, V18, V19, or V20 with the WinCC Unified ES package installed. The screenshots and scripting interface in this article correspond to V20.
• Runtime target: Either an RT Unified panel (e.g., MTP700 Unified Comfort, SIMATIC HMI Unified Comfort Panels) or a Unified PC station running WinCC Unified Runtime V17+.
• Configured HMI tag: A valid HMI tag, e.g. Tag101, of a numeric data type (Int, DInt, Real, LReal) connected to a PLC tag or DB element. Tags of type String, WString, and Bool are supported by the same API but with type-specific input format handling.
• Script runtime enabled: Project tree → Runtime settings → Script runtime → "Global script runtime" enabled. JavaScript runtime support ships with WinCC Unified by default; no additional option is required.
• User authorization: The operator who should be permitted to write to the tag via the IO field must have an authorization level that allows write access. Configure in User Administration → Users & Roles. By default, the "HMI Operator" role grants read/write; deny explicit if read-only access is required.

Why the Original item.InputValue.set() Approach Fails

The script the source engineer tried — item.ProcessValue.set( Tags("Tag101") ) — is directionally correct but was placed on the wrong event and conflated the read direction. In WinCC Unified, the IO field screen object exposes the following relevant members in its scripting interface:

Placing item.ProcessValue.set(...) on a cyclic trigger (such as the property itself) creates a write-back loop that continuously re-pushes the PLC value into the property. While the IO field then displays correctly, the operator can never enter a new value because the cycle overwrites the buffer before the runtime confirms input. The proper anchor is a one-shot event: InputFinished.

Step-by-Step: Configure the IO Field and Script

The following procedure creates an IO field bound to a tag via JavaScript, covering both directions with a validation example. The procedure is identical for Comfort Unified panels, IPCs running Unified Runtime, and Unified PC stations.

Step 1 — Add the IO Field to the Screen

1. In the TIA Portal project tree, expand HMI → Screens and open the target screen (e.g., Screen_1).
2. From the Toolbox palette, drag an IO field onto the canvas.
3. Select the IO field and open the Properties pane. Under General → Process value, leave the field empty (no direct tag dynamization). Scripting requires that the process value is not statically linked; otherwise the script dynamization on the property is ignored.
4. Set Mode to Input/output (read/write). For read-only display use Output; for write-only configuration use Input.
5. Configure Format according to the data type: e.g. 999 for an Int, 9999.99 for a Real with two decimals, or s9999 for signed values.
6. Confirm with OK. The IO field now displays "###" or a placeholder because it has no dynamization yet.

Step 2 — Add a Read Dynamization Script on ProcessValue

1. With the IO field selected, navigate to Properties → Events and scripts → ProcessValue → Script (or right-click the ProcessValue row → "Add script" in older UI revisions).
2. The script editor opens. Enter the following minimal read script:

// Read dynamization: pull the current PLC value into the IO field each cycle.
// This is the canonical output-direction pattern in WinCC Unified.
let src = Tags("Tag101");
src.Read();
return src.Value;

3. Close the script editor. Compile the project (Project → Compile → Software (rebuild all)). The IO field should now display the live value of Tag101 at the configured refresh rate.

Step 3 — Add the InputFinished Event Handler (Write Direction)

1. Select the IO field, then go to Properties → Events and locate Input finished.
2. Click the row to add a script. The editor opens with the event signature pre-populated; the runtime passes the entered value as the argument value.
3. Enter the canonical write script:

// InputFinished handler: write the operator's entry back to the PLC tag.
// The "value" parameter is provided automatically by the WinCC Unified runtime.
let dest = Tags("Tag101");
dest.Write(value);
return;

4. Compile and download to the RT Unified target.

This pair of scripts — read on ProcessValue, write on InputFinished — is the direct replacement for the missing InputValue / InputValueChanged pair from WinCC V7.

Step 4 — Optional: Add Input Validation

The most common reason to script an IO field in the first place is to validate or transform the entry before it reaches the PLC. Below is a field-proven example that bounds a numeric setpoint to 0…100, clamps out-of-range values, and rejects non-numeric input:

// Validated write: clamp a setpoint into the 0..100 range.
// "value" carries the operator's entry from the runtime.
let dest = Tags("Tag101");
let raw  = Number(value);

if (Number.isNaN(raw)) {
    // Non-numeric input — reject silently and surface a system event.
    HMIRuntime.Trace("IO field: rejected non-numeric input: " + value);
    return;
}

let clamped = raw;
if (clamped < 0)   clamped = 0;
if (clamped > 100) clamped = 100;

dest.Write(clamped);
HMIRuntime.Trace("IO field: wrote " + clamped + " to Tag101");

For string tags, swap Number(value) for a length check or regex validation, e.g. /^[A-Za-z0-9_]{1,16}$/.test(value).

Step 5 — Optional: Trigger a Derived Tag in Parallel

A frequent application is to write the entered value to two tags (e.g., setpoint and a "setpoint accepted" handshake). Both writes can be issued from the same InputFinished handler:

let setpoint   = Tags("Tag101");
let acknowledge = Tags("Tag101_Ack");

setpoint.Write(value);
acknowledge.Write(true);

// Pulse-style: reset the acknowledge flag 500 ms later via a scheduled action.
HMIRuntime.Schedule(
    function () { acknowledge.Write(false); },
    500,
    HMIRuntime.ScheduleOnce
);

Properties Reference for IO Field (RT Unified, TIA Portal V20)

The following table summarizes the IO field screen object properties exposed to the WinCC Unified scripting runtime. All members are accessed on the item reference that the script editor implicitly passes into the handler.

Complete Working Example: S7-1500 Setpoint IO Field

The following end-to-end example ties a TIA Portal V20 project to a SIMATIC S7-1500 CPU. The PLC exposes a DB element "Setpoint_SP" of type Real; the HMI tag Tag101 is connected via an HMI connection with the standard S7 naming convention.

PLC side (S7-1500, TIA Portal V20):

// DB "HMI_Data", element "Setpoint_SP" : Real;  // Tag address DB10.DBX0.0 REAL
// Optional: handshake bit for write confirmation
// "Setpoint_New" : Bool;                       // DB10.DBX4.0

HMI side, IO field on Screen_1:

• Mode: Input/output
• Format pattern: 9999.9
• Process value dynamization (script, Property → Script):

let src = Tags("Tag101");
src.Read();
return src.Value;

• InputFinished event (script):

let dest = Tags("Tag101");
let raw  = Number(value);

if (Number.isFinite(raw)) {
    // Round to one decimal to match the format pattern.
    let rounded = Math.round(raw * 10) / 10;
    dest.Write(rounded);
    HMIRuntime.Trace("Setpoint committed: " + rounded);
} else {
    HMIRuntime.Trace("Setpoint rejected: " + value);
}

Verification

After downloading the project to the Unified Runtime target, verify the configuration using the following commissioning checklist:

1. Visual read: Confirm the IO field shows the current value of the S7 tag. If it stays at ###, the read script is not returning the value or the tag quality is Bad. Check the tag's Quality property with Tags("Tag101").Quality in a temporary trace.
2. Visual write: Tap the IO field, enter a value, and press Enter (or use the configured confirmation key). The display should remain at the entered value. If the value reverts to the previous PLC value, the InputFinished script is not writing, or the operator role lacks write authorization.
3. PLC-side echo: Monitor the tag in the PLC using a watch table or the S7-1500 web server. The new value must appear within one HMI acquisition cycle (default 100 ms for cyclic tags on S7 connections).
4. Script trace: Open the Unified Runtime's diagnostic viewer or the WinCC Unified Control Panel → Logs and Traces. Confirm the HMIRuntime.Trace(...) lines appear at the expected points.
5. Cycle-loop test: Force the PLC value to a known constant (e.g., 42.0) using the watch table, then enter a different value on the HMI. After confirmation, the HMI should display the entered value until the PLC has acknowledged it and updated the source — proving the write direction is functional and not being overwritten by the read dynamization.

Troubleshooting Matrix

Alternative: Direct Tag Dynamization (No Script)

If the only requirement is a plain read/write IO field with no validation, transforms, or secondary writes, the script layer is unnecessary. Configure as follows:

1. Select the IO field, open Properties → General → Process value.
2. Click the tag browser and select Tag101.
3. Compile and download. The runtime handles read and write automatically; the operator can enter a value, press Enter, and the PLC receives it within the configured acquisition cycle.

This is the path Siemens recommends for straightforward setpoints. Reserve the scripting path for cases that require validation, derived writes, logging, conditional write enable, or non-linear mapping.

Best Practices and Field-Proven Caveats

• Always coerce input. The value argument from InputFinished arrives as a String. Explicit conversion via Number(), parseInt(), or parseFloat() is required for numeric tags. null becomes 0 in Number(); always guard with Number.isFinite().
• Avoid Tags(...).Value in InputFinished writes. Reading the current PLC value back through Tags(...).Value inside a write handler is a common mistake that re-introduces a write-back loop on the same script. Write the value argument directly to the destination tag.
• Use the same tag for read and write. The Unified runtime does not require separate read and write tags; a single tag drives both directions when the IO field is in Input/output mode.
• Prefer HMIRuntime.Trace for commissioning. On Unified PC stations, traces appear in the diagnostic trace viewer accessible via the system tray. On Unified Comfort panels, traces are written to a rotating log on the SD card and downloadable via the panel's web server.
• Type-strict writes. Writing a Real value to an Int tag triggers a runtime conversion error. Validate not only the range but the data type compatibility.
• Authorization on writes. Even with the script in place, an operator without the correct role cannot write. Verify role assignments in the User Administration editor. The InputFinished event fires regardless of role, but the Write() call is rejected by the runtime.
• Format string alignment. The IO field display format and the validation in the script must agree. A 9999 format on the field with a Real tag backing it will display integers only; the operator cannot enter "12.5" because the format strips the decimal point before the script sees it. Use 9999.0 or 9999.99 patterns for floating-point values.
• Migrate carefully from V7. Scripts migrated from WinCC V7 or WinCC Professional typically reference item.InputValue and trigger on "Change" events. These must be rewritten. A line-by-line find-and-replace is not sufficient — the event anchor and the property semantics both differ.

Related Screen Objects and Pattern Consistency

The same read-on-property, write-on-event pattern applies to other input-capable Unified screen objects:

Once the IO field pattern is in place, the same scripts transfer to other input objects with only the property/event names changed.

Reference Documentation

• IO field (RT Unified) — TIA Portal V20 documentation
• SIMATIC HMI Unified Comfort Panels — Product support
• TIA Portal Help Cloud — Engineering & Runtime Scripting