Troubleshooting

This page helps on how to resolve common encountered issues by using OneCX.

General Troubleshooting Steps

When you encounter an issue like an injection error, application is not loading, blank page, etc., please do the following steps first which should resolve most of the common issues:

OneCX Compatibility

Make sure that the App is OneCX compatible and you followed the guidelines.

Webpack Configuration

  • Verify if all necessary packages are shared in your webpack.config.js:

    • angular packages

    • onecx packages

    • rxjs

    • primeng

    • ngx-translate

  • Check in your package.json which of the mentioned packages are installed:

Example package.json
...
"dependencies": {
    ...
    "@angular/core": "^18.2.12",
    "@angular/forms": "^18.2.12",
    "@angular/platform-browser": "^18.2.12",
    "@angular/router": "^18.2.12",
    "@ngx-translate/core": "^15.0.0",
    "@onecx/accelerator": "^5.48.3",
    "@onecx/integration-interface": "^5.48.3",
    "primeng": "^17.18.11",
    "rxjs": "~7.8.1",
    ...
  },
...

  • Check your webpack.config.json if those packages are shared and add them if they are missing:

Table 1. Example webpack.config.js
Correct (✓) Incorrect (✗)
webpack.config.js
...
  shared: share({
    '@angular/common': {
      requiredVersion: 'auto',
      includeSecondaries: { skip: ['@angular/common/http/testing'] },
    },
    '@angular/common/http': {
      requiredVersion: 'auto',
      includeSecondaries: true,
    },
    '@angular/core': { requiredVersion: 'auto', includeSecondaries: true },
    '@angular/forms': { requiredVersion: 'auto', includeSecondaries: true },
    '@angular/platform-browser': {
      requiredVersion: 'auto',
      includeSecondaries: true,
    },
    '@angular/router': { requiredVersion: 'auto', includeSecondaries: true },
    '@ngx-translate/core': { requiredVersion: 'auto' },
    primeng: { requiredVersion: 'auto', includeSecondaries: true },
    rxjs: { requiredVersion: 'auto', includeSecondaries: true },
    '@onecx/accelerator': { requiredVersion: 'auto', includeSecondaries: true },
    '@onecx/integration-interface': {
      requiredVersion: 'auto',
      includeSecondaries: true,
    },
    ...
  }),
...
webpack.config.js
...
shared: share({
    '@angular/common': {
      requiredVersion: 'auto',
      includeSecondaries: { skip: ['@angular/common/http/testing'] },
    },
    '@angular/common/http': {
      requiredVersion: 'auto',
      includeSecondaries: true,
    },
    '@angular/forms': { requiredVersion: 'auto', includeSecondaries: true },
    '@angular/platform-browser': {
      requiredVersion: 'auto',
      includeSecondaries: true,
    },
    '@angular/router': { requiredVersion: 'auto', includeSecondaries: true },
    '@ngx-translate/core': { requiredVersion: 'auto' },
    primeng: { requiredVersion: 'auto', includeSecondaries: true },
    '@onecx/accelerator': { requiredVersion: 'auto', includeSecondaries: true },
    // MISSING: '@angular/core'
    // MISSING: 'rxjs'
    // MISSING: '@onecx/integration-interface'
    ...
  }),
...

Installed Packages

  • Verify if all shared packages have the caret '^' sign in your package.json (except for rxjs it is a tilde '~').

  • For that, first check your webpack.config.js which packages are being shared:

Example webpack.config.js
...
    shared: share({
    '@angular/common': {
      requiredVersion: 'auto',
      includeSecondaries: { skip: ['@angular/common/http/testing'] },
    },
    '@angular/common/http': {
      requiredVersion: 'auto',
      includeSecondaries: true,
    },
    '@angular/core': { requiredVersion: 'auto', includeSecondaries: true },
    '@angular/forms': { requiredVersion: 'auto', includeSecondaries: true },
    '@angular/platform-browser': {
      requiredVersion: 'auto',
      includeSecondaries: true,
    },
    '@angular/router': { requiredVersion: 'auto', includeSecondaries: true },
    '@ngx-translate/core': { requiredVersion: 'auto' },
    primeng: { requiredVersion: 'auto', includeSecondaries: true },
    '@onecx/accelerator': { requiredVersion: 'auto', includeSecondaries: true },
    ...
  }),
...

  • Then check if the correct range (caret '^' or tilde '~' for rxjs) is present for the shared packages in your package.json:

Table 2. Example package.json
Correct (✓) Incorrect (✗)
package.json
...
"dependencies": {
    ...
    "@angular/common": "^18.2.12",
    "@angular/core": "^18.2.12",
    "@angular/forms": "^18.2.12",
    "@angular/platform-browser": "^18.2.12",
    "@angular/router": "^18.2.12",
    "@ngx-translate/core": "^15.0.0",
    "@onecx/accelerator": "^5.48.3",
    "@onecx/integration-interface": "^5.48.3",
    "primeng": "^17.18.11",
    "rxjs": "~7.8.1",
    ...
  },
...
package.json
...
"dependencies": {
    ...
    "@angular/common": "18.2.12",
    "@angular/core": "18.2.12",
    "@angular/forms": "18.2.12",
    "@angular/platform-browser": "18.2.12",
    "@angular/router": "18.2.12",
    "@ngx-translate/core": "15.0.0",
    "@onecx/accelerator": "5.48.3",
    "@onecx/integration-interface": "5.48.3",
    "primeng": "17.18.11",
    "rxjs": "7.8.1",
    ...
  },
...

Clean Install and Build

Do a clean install and build of the App:

  • Remove .angular and .nx folder

  • Remove node_modules and package-lock.json

  • Run following command to clear the npm cache:

  npm cache clean --force

  • Install all packages:

  npm install

  • Build the App

Application Setup/Settings

  • Verify if the Remote Module name in the webpack.config.js is the same as the Remote Module setting in the Application Store.

  • Navigate to the Application Store → open the App → click on the 'Components' tab → open the 'Module' UI Component → check App ID:

Table 3. Example webpack.config.js and Application Store setting (remote module name)
webpack.config.js Application Store 
...
const config = withModuleFederationPlugin({
  name: 'onecx-workspace-ui',
  filename: 'remoteEntry.js',
  exposes: {
    './OneCXWorkspaceModule': 'src/main.ts',
    ...
    }
  }),
...
application store remote module name

  • Verify if the tag name for the component is the same as the tag name set in the Application Store:

Table 4. Example values.yaml and Application Store setting (tag name)
values.yaml Application Store
values.yaml
...
microfrontend:
  enabled: true
  specs:
    main:
      exposedModule: "./OneCXWorkspaceModule"
      description: "OneCX Workspace UI"
      note: "OneCX Workspace UI auto import via MF operator"
      type: MODULE
      technology: WEBCOMPONENTMODULE
      remoteName: onecx-workspace
      tagName: ocx-workspace-component
      endpoints:
        - name: workspace-detail
          path: /{workspace-name}
...
application store remote module tag name

Shell related

  • Make sure you are using the latest version of the Shell.

  • Verify if the Angular version of the App is lower than the Shell’s.

  • Go to the browser’s DevTools and run in the console following command:

DevTools Console
window['onecxWebpackContainer']

  • You will get a list of all the shared packages.

  • Check e.g. the @angular/core entry to see the versions:

devtools webpack shared packages