Web UI Projects - Widget Development Kit

Development Kit for creating individual Widgets for the WinCC Open Architecture Dashboard using Angular and Nx.

| Dependency | Version | | ------------ | ------------------------------------ | | Angular | ~20.3.18 | | @angular/cdk | ~20.2.14 | | Nx | 21.6.10 | | webpack | ^5.105.4 | | Node.js | ^20.19.0 || ^22.12.0 || >=24.0.0 | | npm | 10.9.3 | | WinCC OA | >=3.19.23 or >=3.20.10 |

Requirements

• WinCC OA with dashboard project setup
• Node.js & npm - use NVM (Windows) to manage versions

Workspace setup

1. Create an Nx workspace

npm init [email protected] -- --preset=angular-monorepo

√ Where would you like to create your workspace? · wdk-project
√ Application name · example-app
√ Which bundler would you like to use? · webpack
√ Default stylesheet format · scss
√ Do you want to enable Server-Side Rendering (SSR) and Static Site Generation (SSG/Prerendering)? · No
√ Test runner to use for end to end (E2E) tests · none
√ Which CI provider would you like to use? · skip
? Would you like remote caching to make your build faster? · skip

If you already have an Angular project, see the Nx transition guide.

2. Configure package.json

cd wdk-project

Pin the following dependencies to ~20.3.18:

// dependencies
"@angular/common": "~20.3.18",
"@angular/compiler": "~20.3.18",
"@angular/core": "~20.3.18",
"@angular/forms": "~20.3.18",
"@angular/platform-browser": "~20.3.18",
"@angular/platform-browser-dynamic": "~20.3.18",
"@angular/router": "~20.3.18",

// devDependencies
"@angular-devkit/build-angular": "~20.3.18",
"@angular-devkit/core": "~20.3.18",
"@angular-devkit/schematics": "~20.3.18",
"@angular/cli": "~20.3.18",
"@angular/compiler-cli": "~20.3.18",
"@angular/language-service": "~20.3.18",
"@schematics/angular": "~20.3.18",

Add overrides:

"overrides": {
  "primeng": {
    "@angular/cdk": "~20.2.14",
    "@angular/animations": "~20.3.18",
    "@angular/common": "~20.3.18",
    "@angular/core": "~20.3.18",
    "@angular/forms": "~20.3.18",
    "@angular/platform-browser": "~20.3.18",
    "@angular/router": "~20.3.18"
  },
  "webpack": "^5.105.4"
}

3. Install the WDK

npm install @etm-professional-control/widget-development-kit --force

Developing a new widget

npx nx generate @etm-professional-control/widget-development-kit-generator:widget

Use a unique keyword without spaces. All commands below use this keyword. Example: demo.

✔ Give a full name of the widget you want to create: · My First Widget
✔ Give a unique keyword for your widget · demo
✔ Provide a short description: · A basic example implementation of a dashboard widget
✔ Enter a port number on which you want to serve the widget: · 4201
✔ Do you want to support multiple datapoints as inputs: (y/N) · false

Generated files:

| What | Location | | ----------------- | --------------------------------------- | | App | apps/widgets/demo/ | | Library | dashboard-widgets-demo | | Translations | apps/widgets/demo/data/WebUI/msg/ | | Widget definition | apps/widgets/demo/data/WebUI/widgets/ |

canWrite permission

From WinCC OA 3.20, use checkCanWritePermission() from DefaultAuthService to check user write permissions.

Deploying your widget

Build

npx nx build widgets-demo

Copy dist/data/WebUI and apps/widgets/demo/data/WebUI to your WinCC OA project under data/WebUI. Refresh the dashboard to see the widget.

Serve (development)

npx nx serve widgets-demo

Update data/WebUI/widgets/demo.json in your WinCC OA project - switch remoteEntry to your dev server:

"moduleFederationSettings": {
  "remoteEntry_original": "/data/WebUI/components/demo/remoteEntry.js",
  "remoteEntry": "http://127.0.0.1:4201/remoteEntry.js",
  "remoteName": "demo",
  "exposedModule": "./Module"
}

Changes are visible after page refresh. Build and copy is still needed once initially and after translation changes.

Compatibility

Compatible with WinCC OA 3.19 and 3.20. Widgets from previous WDK versions need updating to Angular 20 via nx migrate.

See WinCC OA Documentation for the WDK API reference.

Troubleshooting

Webpack compilation error

TypeError: The 'compilation' argument must be an instance of Compilation

Ensure the webpack override is set in your package.json (see step 2), then reinstall:

npm install --force

Mismatched Nx package versions

Failed to convert JavaScript value Object {...} into rust type String

All @nx/* packages must be the same version. Fix:

npm install [email protected] @nx/[email protected] @nx/[email protected] @nx/[email protected] @nx/[email protected] @nx/[email protected] @nx/[email protected] @nx/[email protected] @nx/[email protected] --save-dev --force

Changelog

Dashboard 9.1.0

• Update to Angular ~20.3.18
• Update to Nx 21.6.10

Dashboard 9.0.0

• Update to Angular 20.0.6
  • The Easy Dashboard, all custom widgets and the Widget Development Kit have been migrated to Angular 20.
  • To continue using your custom widgets in the dashboard, you will also need to update your workspace.
  • Learn more about Angular 20, about how nx migrate works, or get some nx update tips
• Update to Nx 21.2.2

Dashboard 8.0.2

• Fix deployment error in @etm-professional-control/oa-rx-js-api

Dashboard 8.0.1

• Update to Angular 18
  • The Easy Dashboard, all custom widgets and the Widget Development Kit have been migrated to Angular 18.
  • To continue using your custom widgets in the dashboard, you will also need to update your workspace.
  • Learn more about Angular 18, about how nx migrate works, or get some nx update tips

Dashboard 7.1.1

• It is now possible to find internal datapoints in the dashboard by starting the search term with "_".

Dashboard 7.0.2

• Update to Angular 16
  • The Easy Dashboard, all custom widgets and the Widget Development Kit have been migrated to Angular 16.
  • To continue using your custom widgets in the dashboard, you will also need to update your workspace.
  • Learn more about Angular 16, about how nx migrate works, or get some nx update tips

Dashboard 6.1.0

• A new widget: Sankey
  • The Sankey Widget displays flow data of current or historical values of different data sources.

Dashboard 6.0.0

• Interface modification for form components (wui-container, wui-fieldset, wui-form-group and wui-input-group)
  • Affects the users who already use custom widgets and want to migrate to WinCC OA 3.19.P005 or higher
  • This change is not backward compatible and it is required to update the usage of the aforementioned components and all WinCC OA instances
  • Components do not accept control/controls as properties anymore
  • Instead, new properties like isInvalid or isDirty are introduced (for more details, please check the corresponding .md files with examples for each component)
  • To simplify the migration, new pipes were introduced (isDirty, isInvalid and isTouched). They accept a list of controls to be verified. Details are to be found in corresponding .md files.

License

MIT