Updating the Web SDK version

Version: 10.6.0.0 | Packages: @c8y/cli, @c8y/apps and @c8y/ngx-components

A UI build with an earlier version of the Web SDK is locked to the current version. A platform update doesn’t update the UI version, however a UI running against a newer backend always keeps working as all APIs are backwards compatible. That’s why an update makes mostly sense if a newer feature of the UI or the Web SDK needs to be used. Therefore, a new application needs to be built and deployed to the platform. This recipe describes best practices to do so.

Preparation

We recommend you to use a Source Control System to backup the data and to get better diffing of the code. If you are not using an SCM yet, see below for an introduction on how to use git to store your changes. If you are already using an SCM or you don’t want to use any, you can jump to the next section. If you decide not to use an SCM, backup your application before running the update.

Ensure that you have git installed on your system. Then open a terminal and run the following commands:

cd <<path/to-you-app>>
git init
git add .
git commit -m "init commit"

Now your code is committed to a local git repository stored in the .git folder. Next this recipe explains you how to update the Web SDK. If you don’t want to use git anymore after the update, you can simply erase the .git folder.

Updating

To update the Web SDK you can simply use the new command that is used for scaffolding:

c8ycli new <<app-name>> <<cockpit|devicemanagement|administration>> -a @c8y/apps@<<version>>

So for example if your current working directory is an application called “my-cockpit” based on Cloud of Things’s Cockpit application and you want to update to version 10.6.2.0, you must run the following command:

cd ..
c8ycli new my-cockpit cockpit -a @c8y/apps@1006.2.0
Info
The first two numbers of the version are combined (for example, 10.6 becomes 1006) as npm only supports semver version numbers. You can also remove the -a flag, in this case the version tagged with latest will be used.

The command simply copies over the files that are used for building a new application in the particular version. The following files are currently overwritten:

These are the files that are overwritten by an update based on the version of that article. The list might change in later versions. Next, we must reapply the changes that were made earlier to these files. A git diffing tool can be very helpful for that.

Diffing to reapply changes

A git diffing tool is useful to identify which changes have been made with the upgrade and which have been made earlier and now need to be reapplied. In the following screenshot we are using Visual Studio Code to identify the changes, as it has a well integrated diffing tool for git (mostly all other IDEs have support for git diffing as well):

Comparing the difference with vscode

With that tool it is easy to compare which file was changed with the upgrade and where custom changes may need to be reapplied. In this case MyCustomModule must only be placed in the upgrade app.module.ts. When this change is done, the update can be verified.

Verifying the update

To check if the version update worked, it is usually a good practice to run it locally first. Therefore, you need first to install the dependencies again. Remove the current node_modules directory and run npm install (or yarn) again to refresh the dependencies. After this, start the application with npm start. After login you can check the current UI version by clicking on you username.

If everything worked as expected, you can now deploy your application by running the commandnpm run deploy.

Conclusion

The update process is sometimes a bit tricky, especially if you have many changes in the app.module.ts. However, with git and Visual Studio Code the visual diffing may help you to accomplish this task. Also, it is a good practice to put your own Angular customizations into a module and only to make changes to the app.module.ts when it is absolutely necessary.

Upgrading from Angular 11 to Angular 12

Angular 12 is supported from version 10.11.45.0. The following configuration changes are required before you can run the application:

Info
AOT (Ahead-of-time compilation) is not yet supported.

How to enable IVY

Ivy is a new rendering engine for Angular applications that improves application speed and facilitates development. Enabling Ivy is not mandatory, but as the older view engine is deprecated, we recommend you to do so.

During the update:

    "angularCompilerOptions": {
        "enableIvy": true
  }
    "scripts": {
        ...
    "postinstall": "ngcc"
  }
Info
Deep imports are not supported. For example, you must import from @c8y/ngx-components/asset-navigator but not from @c8y/ngx-components/asset-navigator/services/asset-service.
Info
If you use Visual Studio Code, make sure that in the Angular Language Service Plugin the option “Use legacy View Engine language service” is not selected.

Upgrading from Angular 12 to Angular 14

Angular 14 is supported from version 1015.132.0. The following configuration changes are required before you can run the application:

Info
AOT (Ahead-of-time compilation) is not yet supported.
Info
If you use Visual Studio Code, make sure that in the Angular Language Service Plugin the option “Use legacy View Engine language service” is not selected.

Upgrading to Angular 11

Angular 11 is supported from version 10.10.4.0. AOT and Ivy are not yet supported. The following configuration changes are required before you can run the application:

Info
If you use Visual Studio Code, make sure that in the Angular Language Service Plugin the option “Use legacy View Engine language service” is not selected.

Migrating applications

This section targets developers who have either already developed a plugin with the AngularJS SDK for plugins or want to extend the existing default applications.

You should have read and understood the following concepts:

Setting up a hybrid application

With a hybrid application AngularJS and Angular can be used at the same time. It allows to use not-migrated plugins written in AngularJS in an Angular context. The CLI automatically sets up a hybrid application, if you use one of our default applications as a template (cockpit, devicemangement or administration). The command to be used is c8ycli new <your-app-name> <template-name>.

For example, to override the default cockpit you use:

c8ycli new cockpit cockpit

When you run this command it provides you with a very simple file structure that contains the following files:

Importing AngularJS plugins

If you want to integrate your custom plugin into an application, you must first set up the hybrid application for the application into which you want to import the plugin. Then you simply copy the plugin to the hybrid application and reference the cumulocity.json of the plugin in the ng1.ts file with an import:

import 'my-custom-plugin/cumulocity.json';

Webpack now reads the manifest file and converts the content to CommonJS require imports so that the plugin will be loaded and applied to the application.

Custom bootstrapping and upgrading

In the app.module.ts file we bootstrap the hybrid application with the following code on the HybridAppModule.

import { UpgradeModule as NgUpgradeModule } from '@angular/upgrade/static';
import { ng1Modules } from './ng1';

export abstract class HybridAppModule {
  ng1Modules = ng1Modules;
  protected upgrade: NgUpgradeModule;

  ngDoBootstrap() {
    (window as any).bootstrap();
    this.upgrade.bootstrap(document.getElementById('app'), this.ng1Modules, { strictDi: false });
  }
}

This module not only bootstraps the upgrade module but also initializes the Angular application.

In the app.module.ts you can control the bootstrapping. For example, you can add another module to the bootstrapped ng1 modules:

constructor() {
  this.ng1Modules.push('my-custom-module');
}

This will also load your my-custom-module. You can use this to override the ngDoBootstrap() function to whatever fits your application needs, for example, upgrade or downgrade Angular services as shown in the Angular docs.