Configuring Custom Engineering Units in PCS 7 APL via APLCustomerUnits.xml

In SIMATIC PCS 7 Advanced Process Library (APL), defining custom engineering measurement units that display correctly on WinCC faceplates is achieved by creating the configuration file APLCustomerUnits.xml in the OS project's GraCS directory. When an engineer specifies an unlisted unit code on an APL block parameter (such as PV_Unit) and the faceplate displays 'undefined unit', the issue stems from invalid XML syntax, saving the file with a byte order mark header, or failing to restart WinCC Runtime. To resolve this, create APLCustomerUnits.xml formatted in UTF-8 without byte order mark header, map custom unit IDs (values > 1000) to unit text strings, deploy the file across all OS servers and clients, and restart WinCC Runtime.

APL Engineering Unit Architecture and IEC 61987 Standards

In SIMATIC PCS 7 Advanced Process Library (APL), analog measurement blocks (such as MonAnL, PIDConL, and Pcs7AnIn) manage engineering units through dedicated integer parameters (PV_Unit, SP_Unit, MV_Unit). Rather than storing text strings like 'bar' or 'm3/h' directly inside controller memory—which would consume excessive work memory and complicate multi-language translation—APL utilizes standardized numeric unit codes complying with IEC 61987 and PROFIBUS PA Profile 3.02.

On the operator station (WinCC OS), APL faceplate scripts evaluate the numeric code and retrieve the corresponding text representation. Standard units (e.g., 1001 = °C, 1002 = °F, 1342 = bar, 1137 = m3/h) are embedded within standard WinCC text dictionaries. However, specialized processes frequently require non-standard units (such as Nm3/h, ppm/min, bbl/d, or proprietary chemical dosing ratios). Siemens introduced APLCustomerUnits.xml as the official mechanism to expand the APL unit dictionary with user-defined definitions.

Why APL Faceplates Display 'Undefined Unit' Errors

When an engineer creates APLCustomerUnits.xml and configures a block unit code, but the faceplate displays 'undefined unit', technical investigation identifies four primary failure modes:

File Encoding with Byte Order Mark Header: The XML parser embedded inside WinCC C-scripts (APL_GetUnitText.c) expects raw ASCII or UTF-8 formatting. If the XML file is saved using a Windows text editor that injects a 3-byte UTF-8 byte order mark header (0xEF, 0xBB, 0xBF), the XML parser fails during initialization and returns empty strings.
Missing Deployment to OS Clients and Standby Servers: The XML file was placed in the local GraCS directory on the Engineering Station, but was not transferred to the redundant OS Server or OS Clients. When an operator opens the faceplate on a client station, the local client cannot locate the XML file and defaults to displaying 'undefined unit'.
In-Memory Caching in WinCC Runtime: WinCC loads and parses APLCustomerUnits.xml into volatile memory only once when the first APL faceplate opens. Modifying the XML file while WinCC Runtime is active produces zero effect until runtime is deactivated and restarted.
Syntax and Schema Violations: Using invalid XML tags, omitting quotes around attributes, or violating case-sensitivity causes silent XML schema rejection.

APLCustomerUnits.xml Syntax and Unit Code Allocation Matrix

The following table details code ranges, formatting rules, and XML schema for APL custom units:

Unit Code RangeCategory / AllocationExample Unit CodeConfiguration Location1 to 999Legacy PROFIBUS PA Units1 = m, 2 = kg, 3 = sStandard Embedded APL Dictionary1000 to 1999Standard IEC 61987 Units1001 = °C, 1342 = barStandard Embedded APL Dictionary2000 to 19999Reserved by SiemensSystem UnitsDo not use for custom units10000+ (or > 1000)User-Defined Custom Units10001 = Nm3/h, 10002 = bbl/dConfigured in APLCustomerUnits.xmlFile PathMaster OS Project Folder<OS_Project>\GraCS\APLCustomerUnits.xmlMust reside in GraCSFile EncodingText File FormatUTF-8 without byte order mark headerStrict formatting requirement

Step-by-Step Procedure to Implement and Deploy Custom Units

To configure custom engineering units and display them on APL faceplates:

Create the XML Configuration File:
- Open a code editor (such as Notepad++ or VS Code).
- Create a new file with the following exact XML schema:
xml <?xml version="1.0" encoding="utf-8"?> <UserDefinedUnits> <Unit id="10001" text="Nm3/h" /> <Unit id="10002" text="bbl/d" /> <Unit id="10003" text="mg/Nm3" /> <Unit id="10004" text="g/100g" /> </UserDefinedUnits>
- In your text editor, ensure the encoding is set strictly to UTF-8 without byte order mark header.
- Save the file as APLCustomerUnits.xml.
Place the File in the WinCC GraCS Directory:
- Copy APLCustomerUnits.xml into the GraCS folder of your master OS project on the Engineering Station:
C:\Siemens\Step7\s7proj\<Project>\<OS_Server>\GraCS\
- If your system operates OS Clients with local project folders, ensure the file is copied into the GraCS folder of all OS Clients.
Assign the Custom Unit Code in CFC:
- In SIMATIC Manager, open the CFC chart containing the analog block (e.g., MonAnL or Pcs7AnIn).
- Open the block properties and locate parameter PV_Unit.
- Enter the custom unit ID: 10001.
- Compile the CFC chart changes and download to the S7 controller.
Compile the OS and Restart WinCC Runtime:
- Execute an OS Compile (Changes Only) to synchronize tags.
- If WinCC Runtime is currently running, deactivate Runtime.
- Restart WinCC Runtime to purge the memory cache and force the APL script engine to read APLCustomerUnits.xml.
- Open the faceplate; confirm that the unit displays Nm3/h cleanly.

Verification

Verify custom unit presentation:
1. Open the technological faceplate in WinCC Runtime; confirm that the process value field displays the custom text (e.g., 125.4 Nm3/h) without showing 'undefined unit'.
2. Check the block icon on the process screen; confirm that the engineering unit string displays correctly adjacent to the numeric value.
3. Open the faceplate Limit View; confirm that high and low alarm limits inherit the custom unit string.
4. Open WinCC trend windows; verify that historical curves display the custom unit on the Y-axis.

Limitations and Operational Precautions

Multi-Language Restrictions: APLCustomerUnits.xml provides static text strings. If multi-language switching (e.g., English, German, French) is required, use separate language entries supported by newer APL service packs.
Never Save with Byte Order Mark: Saving the file with UTF-8 byte order mark headers renders the XML parser completely unable to read the file.
Code Collisions: Avoid assigning unit IDs below 10000, as Siemens reserves lower ranges for standard IEC updates.