Upgrade

Updating the Web SDK version

From version 1019.x.x onwards the Web SDK is following semantic versioning. Meaning that every major version bump (for example, from 1019 to 1020) may contain breaking changes, but every minor or fix bump should not break your application. So it is save to update to any minor or fix version, but if you update to any major version, you might need to migrate things.

Easiest way for migration at the moment is still comparing the diff with git:

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 must create a new application with the desired version and copy over the files. The diff then tells you, where merge conflicts might happen. Fix any merge conflicts prior to merging.

ng new cockpit
cd cockpit
ng add @c8y/websdk 

If you select a newer version of the application you want to scaffold, you get the latest scaffolding files. If you copy them over to your solution which was checked in before, you can see the difference between the versions.

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 must 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):

With that tool it is easy to compare which file was changed with the upgrade and where custom changes may have 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.

Angular CLI before 10.19.x.x

When developing a pure Angular you can create an Angular CLI (ng-cli) project and add Cumulocity CLI to it. This functionality is available for:

• Angular 7: Supported from version 10.4.2.0
• Angular 8: Supported from version 10.5.9.0
• Angular 11: Supported from version 10.10.4.0
• Angular 12: Supported from version 10.11.45.0
• Angular 14: Supported from version 10.15.132.0
• Angular 15: Supported from version 10.18.157.0

Install Angular CLI

Follow the instructions to install @c8y/cli globally.

npm install -g @angular/cli@v8-lts

Create a new project

ng new my-first-iot-project
cd my-first-iot-project

Add Cumulocity CLI

ng add @c8y/cli

Run application

ng serve

In your browser, open http://localhost:4200/ to see the new application run.

You can configure the application options inside the package.json file and customize branding with LESS or CSS custom variables.

C8Y Command Line Tool (CLI)

To support you with bootstrapping, running and deploying applications we have build a Command Line Interface. The tool is the successor of the cumulocity-node-tools. To avoid conflicts, it listens to the new command c8ycli instead of c8y. You can install it via npm:

npm install -g @c8y/cli

If you don’t want to install the @c8y/cli globally you can also run it with the npx command. For example, you can scaffold a new project quickly by executing the following command:

npx @c8y/cli new

A new project creates a local @c8y/cli. You can run the project by navigating to its directory and executing the following commands:

npm install && npx c8ycli serve

The serve command starts a local development server. It supports two important flags:

• -u: The -u parameter specifies the Cumulocity instance to which all API requests are proxied. This means data is actually pulled from the configured Cumulocity instance.
• -p: The port to use. If not defined, port 9000 is used. If you have a server running on this port already, the command will fail. The application will then be served at the URL http://localhost:<<port>>/apps/<<your-application-name>>/. Tip: Click the URL in the terminal while holding the “control” key.

General usage

c8ycli [options] [command]

Options

    -u, --url <url>                 The URL of the remote instance
    --version                       Provides version number
    -h, --help                      Provides usage information

Commands

All the commands except of new take an array of glob patterns. These will be resolved to directories or entry point manifests.

    new [name] [template]                   Creates a folder to start a new application or extend an existing one
    serve [options] [appPaths...]           Runs local development server
    build [options] [appPaths...]           Builds the specified applications
    deploy [options] [appPaths...]          Deploys applications from the specified paths
    locale-extract [options] [srcPaths...]  Extracts all strings for translation and outputs the .po files to defined folder

The new command

The c8ycli new [name] [template] command creates an empty application or extends an existing application (Cockpit, Devicemanagement or Administration). To extend an existing application use the name of the existing application as [name] and [template] like this:

$ c8ycli new cockpit cockpit

The c8ycli new command can also be provided on its own without the [name] and [template] options. In this case, follow the steps below to complete the process via the interface before the application is scaffolded.

Step 1:

? Enter the name of the project: (my-application)

The first step asks for the project name. If no project name is entered, the default value my-application is used.

Step 2:

? Which base version do you want to scaffold from? (Use arrow keys)
> 1010.0.X (latest)
> 1011.X.0 (next)
> 1011.0.X
> 1009.0.X
> 1007.0.X
> 1006.0.X
> other

In the second step, the base scaffolding version must be selected. The interface will provide the CD version (latest), as well as older yearly releases. Additionally a version can be manually entered by selecting the other option.

Step 2 (other):

? Enter the desired version:

In this step, the desired version must be entered manually, for example, 1010.0.0.

Step 3:

? Which base project do you want to scaffold from?
  administration
  application
  cockpit
  devicemanagement
  hybrid
  tutorial

In the final step, the base project to scaffold from must be selected.

Application options

The application options can be defined with --app.<option>=<value>. These will be applied to all applications found with [appPaths...].

    --app.name="My Application"
    --app.key=myapp-key
    --app.contextPath=myapplication
    --app.brandingEntry="./branding/mybranding.less"

Webpack options

The webpack options can be defined with --env.<option>=<value>. These will be directly passed to the webpack configuration.

    --env.mode="production"
    --env.hmr

Upgrading from Angular 16 to Angular 17

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

• Update all @c8y dependencies to version 1020.x.x in your package.json.
• Replace import 'zone.js/dist/zone' with import 'zone.js' in the src/polyfills.ts file.
• Replace all occurrences of "browserTarget" with "buildTarget" in the angular.json file.
• Run the command ng update @angular/core@17 @angular/cli@17 to update Angular core and CLI to version 17.
• Update ngx-bootstrap to version 12.0.0.
• Update @angular/cdk to version 17.x.x.
• Remove any reference of loginOptions in the src/main.ts file. The loginOptions function is now called under the hood as part of the loadOptions function.
• Add the @c8y/options package as a devDependency in your package.json.

Upgrading from Angular 17 to Angular 18

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

• Update all @c8y dependencies to version 1021.x.x in your package.json.
• Run the command ng update @angular/core@18 @angular/cli@18 to update Angular core and CLI to version 18.
• Update ngx-bootstrap to version 18.0.0.
• Update @angular/cdk to version 18.x.x.
• The brandingEntry application option can no longer be used to customize the global style of your application. Instead, global styles should now be specified via the mechanism Angular provides. If you previously did not use the brandingEntry in your cumulocity.config.ts file, you would now need to reference the @c8y/style/main.less file in the styles arrays of your angular.json file. In case you’ve previously used the brandingEntry in your cumulocity.config.ts you would now need to reference the same file in the styles arrays of your angular.json file. The brandingEntry should be removed from the cumulocity.config.ts file.
• Node.js, TypeScript, RxJS: Version compatibility.
• Follow the Angular 18 upgrade guide: Updating to version 18.

Upgrading from Angular 15 to Angular 16 and NG CLI

Angular 16 is supported from version 1019.0.0. With the latest release of version 1019.0.0, the Web SDK has transitioned to using ng-cli, marking the end of further development for c8ycli.

This switch aims to align with industry standards, making it more convenient for developers to work with the Web SDK. If you are an Angular developer looking to migrate your existing Web SDK project to ng-cli, the following step-by-step guide leads you through the process.

1. Create an ng-cli Project

First, download the appropriate version of ng-cli and scaffold your project using the ng new command. Make sure to use the name of your existing project during this process.

2. Add @c8y/websdk to Build an App

Integrate the @c8y/websdk into your ng-cli project by running ng add @c8y/websdk. Ensure you select the correct project type: application or hybrid.

3. Copy Over Source Files

Copy all your components, directives, modules, tests, and services files to the new ng-cli project. Also, migrate any non-standard files, such as assets, to the new project.

4. Align the package.json

Update your package.json file by verifying and comparing dependencies. Ensure that you retain the new dependencies while adding any custom dependencies. Update other properties from your original project, excluding the “c8y” property object. Change all scripts to use ng instead of c8ycli and rename any occurrences of “server” to “serve.”

5. Align cumulocity.config.ts

Transfer all “c8y.application” properties from the package.json file to the new cumulocity.config runTime object. Format it as JavaScript and check for errors. Check if federation sharing is sufficient; otherwise, adjust as needed. Some options may need to be moved to buildTime.

6. Verify tsconfig Files

Review and align the tsconfig files according to your project’s needs. You might need to disable certain strict configurations, such as noPropertyAccessFromIndexSignature or noImplicitReturns, which are enabled by default.

7. Install Dependencies and Verify

Install dependencies and ensure that all peer dependencies match. Update any dependencies that may require modification to run seamlessly with Angular 16.

8. Check the Angular Update Guide

As ng-cli uses Angular 16, check the Angular update guide to ensure compatibility. Angular Update Guide

9. Start it

Finally, attempt to run your application using npm start or npx ng <<name-of-your-app>>. Check for compilation errors and resolve any issues. For Angular 16, remove all entryComponents arrays in the modules, as they were deprecated in version 15 and removed in version 16.

Common Pitfalls

• Ensure that the rxjs Subject is correctly typed with void if it should only emit without a value.
• Remove all entryComponents from your code.
• Import ApplicationOptions from the @c8y/devkit/dist/options package, and consider importing only the types to avoid unnecessary bundling (import type from '@c8y/devkit/dist/options';).

Upgrading from Angular 14 to Angular 15

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

• Update all @angular/* dependencies to 15.2.7.

• Update TypeScript to version 4.9.5.

• Follow the Angular 15 upgrade guide: Updating to version 15.

• Use Node version ^14.20.0 || ^16.13.0 || ^18.10.0.

• Delete node_modules and reinstall them.

• Token hooks were deprecated and replaced by function hooks. Check the table below to see to which function hooks the token hooks have been migrated to.

Deprecated HOOK Tokens and Their Replacements

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:

• Update all @angular/* dependencies to 14.0.6.
• Update TypeScript to version 4.7.4 as TypeScript 4.6 is now required by Angular.
• Follow the Angular 14 upgrade guide: Updating to version 14.
• Install new dev dependencies:
  • "html-loader": "4.1.0",
  • "style-loader": "3.3.1",
• Use Node version 14.
• Delete node_modules and reinstall them.

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:

• Update all @angular/* dependencies to 12.2.x.
• Update TypeScript to version 4.2.x as TypeScript 4.2 is now required by Angular.
• Follow the Angular 12 upgrade guide: Updating to version 12.
• Use Node version 14.

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:

• Edit tsconfig.json and set enableIvy to true or delete it as this setting is the default setting:

    "angularCompilerOptions": {
        "enableIvy": true
  }

• Edit package.json and add the postinstall hook:

    "scripts": {
        ...
    "postinstall": "ngcc"
  }

• Delete node_modules and reinstall them. If ngcc works you should see a compiling step after installing all dependencies.

• If you use Jest (JavaScript Testing Framework) check Jest - Angular IVY for the configuration.

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:

• Fix @angular/compiler-cli to version 11.2.9 or lower
• Remove the index property from the angular.json file, if it exists. Also, the --index flag from ng-cli is not supported. A custom index.html file can be passed with ApplicationOptions indexTemplate.