Web UI Projects - Widget Development Kit

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

Requirements

You need an installation of WinCC OA Version 3.19.23 or higher or 3.20.10 or higher. See the WinCC OA Documentation for how to set up a dashboard project.

Verify your current node or npm version like this:

node -v
npm -v

Set up a Node.js development environment:

• Node.js ^20.19.0 || ^22.12.0 || >=24.0.0
• npm ^6.11.0 || ^7.5.6 || >=8.0.0
• Nx v21.6.10

It is recommended to use NVM (Node Version Manager) - available for Windows and Linux.

To install a certain npm version, you can also use the following command:

npm install -g [email protected]

Workspace setup

The WDK is based on Angular 20.3.16 and expects to be installed within a Nx workspace. If you create a new project you can start directly with an empty workspace:

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

Need to install the following packages:
[email protected] Ok to proceed? (y) y
√ 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

This will create a new folder named wdk-project and install all necessary npm packages to create an Angular app—which may take some time. The example-app refers to a default Angular application that is created in the workspace. You can remove it later if you do not need it.

If you already have an Angular project, you need to add Nx capabilities to it. See the official transition guide from Nx for more information.

Next, go into your project's folder (named after the workspace you just created):

cd wdk-project

Pin the following dependencies to 20.3.16 and the Angular devkit/CLI packages to 20.3.15 in your package.json:

dependencies:

• "@angular/common"
• "@angular/compiler"
• "@angular/core"
• "@angular/forms"
• "@angular/platform-browser"
• "@angular/platform-browser-dynamic"
• "@angular/router"

devDependencies:

• @angular-devkit/build-angular"
• @angular-devkit/core"
• @angular-devkit/schematics"
• @angular/cli"
• @angular/compiler-cli"
• @angular/language-service"
• @schematics/angular"

Add following overrides to your package.json to avoid version conflicts with PrimeNG:

"overrides": {
  "primeng": {
    "@angular/animations": "20.3.16",
    "@angular/cdk": "20.2.14",
    "@angular/common": "20.3.16",
    "@angular/core": "20.3.16",
    "@angular/forms": "20.3.16",
    "@angular/platform-browser": "20.3.16",
    "@angular/router": "20.3.16"
  }
}

Install the WDK and all necessary dependencies:

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

Now your workspace is ready to create new dashboard widgets.

Developing a new widget

A very easy way to create a new widget is the WDK generator, which will be installed automatically.

You can start it through the Nx console or the CLI command. It will ask you all necessary details about your widget:

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

Note:
When the generator asks for a keyword, use a unique name without spaces. All following commands will use that term to identify your widget. In this example, we used 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

This will create a new app in your Nx workspace called widgets-demo along with a library called dashboard-widgets-demo. A brief example for custom widget translations can be found in the folder apps/widgets/demo/data/WebUI/msg. The widget definition, including its full name, a description, and a preview image, can be found in the folder: apps/widgets/demo/data/WebUI/widgets.

canWrite permission

Starting from WinCC OA version 3.20, a new licensing model was introduced. If you want to validate if the user has write rights, it is as simple as checking the checkCanWritePermission() property from DefaultAuthService.

This can be used to disable edit options of widgets for users that do not have required permissions.

Deploying your widget

Create a production build

To use your widget within a dashboard, you first have to compile it using the command:

npx nx build widgets-demo

This will create a production build of your widget. Your generated widget components will be put in dist/data/WebUI, and your custom translations and your definition files in the folder apps/widgets/demo/data/WebUI—the contents of those folders need to be copied to your WinCCOA project under data/WebUI.

Your dashboard should show the new widget in the widget selector after a page refresh.

Serve your widget

To make development easier, you can also serve your widget and let the dashboard react to changes on the fly. For this, you start your widget in serve mode:

npx nx serve widgets-demo

Then open the widget definition file located in the folder which you previously copied to your WinCCOA project, e.g.: data/WebUI/widgets/demo.json. At the very end, you will find a section that defines where your widget is located. In this section, switch the content of remoteEntry with remoteEntryDev to get something like this:

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

If you now make changes to your widget, you will see their effect after a page refresh. Keep in mind that you still need to build and copy your widget to your OA project at least once in the beginning and after any changes made in your translation files.

Please note that custom widgets created with this version of the widget development kit are only compatible with the dashboard in WinCCOA 3.19 and 3.20. Widgets created with previous versions of the WDK need to be updated to Angular 20 to be compatible. The nx migrate mechanism can be used for this, along with supplementary adaptations of the webpack configuration.

For more details about the WDK API, see the WinCC OA Documentation.

Troubleshooting

When working with npm packages, it can happen, that certain combinations of packages lead to version conflicts. We will try to document known issues here.

Changelog

Dashboard 9.1.0

• Update to Angular 20.3.16
• 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