Cumulocity IoT Web Development Tutorial - Part 1: Start your journey
Cumulocity IoT Web Development Tutorial - Part 2: Create your first component
Cumulocity IoT Web Development Tutorial - Part 3: Query data from Cumulocity IoT
Cumulocity IoT Web Development Tutorial - Part 4: Convert component into a widget
Cumulocity IoT Web Development Tutorial - Part 5: Provide widget as a UI Plugin
A new journey
Starting your journey as a web developer in Cumulocity IoT can be quite overwhelming in the beginning. There are a lot of concepts to discover and sometimes you simply get crushed by the amount of information available in the documentation.
To make your journey easier I have created this tutorial series. This tutorial series targets web developers, who want to learn how they can implement custom applications, widgets and plugins for Cumulocity IoT. The various articles of this series will teach fundamental concepts about web development in the context of Cumulocity IoT and point out best practices. As a prerequisite it is assumed that you already have an understanding about Angular and Typescript. Furthermore, you need to have a Cumulocity IoT tenant and also basic knowledge about Cumulocity IoT and its data model.
What topics can you expect?
The tutorial series is divided into multiple articles. Each article focuses on a specific topic accompanied by code samples. These code samples are shared in this public GitHub repository, which allows you to review the code for an individual article. There are a couple of articles planned. This first article discusses the general concept about web development in Cumulocity IoT. In addition, you will set up your development environment and create your first custom web application. In the next article you will learn more about how you can extend the custom web application and create your first component. The third article demonstrates how you can use Cumulocity IoT’s API to query data and display it in your web component. This web component will be converted into a Cumulocity IoT widget in the fourth article. You will learn more about extending one of Cumulocity IoT’s default applications as well. In the following articles you will extend this widget and get insight into the upcoming Microfrontend Framework.
Sounds interesting? Then let’s get started!
Let’s get started
You first need to install Node.js to not only have a proper javascript runtime, but also the necessary package manager (npm) to install additional required tools and dependencies. The correct Node.js version depends on the Angular version, you want to develop your application with. In this tutorial, you will use the latest version of the @c8y/websdk, which depends on Angular 17.3.x. Based on this Angular version, you have to install Node.js ^18.13.0 (Version compatibility • Angular).
Once you have finished the setup of Node.js you have to use @angular/cli to create a new project. Instead of installing the @angular/cli tools globally, I rather recommend to install these on demand using the npx command. npx is part of npm and allows you to run commands without having the package installed globally first. Furthermore, you can specify which version you want to have installed.
Let’s create an empty custom Cumulocity web application which is based on the latest version (1020.0.x at the time of writing). Use the @angular/cli and the npx command to create a new project:
npx @angular/cli@v17-lts new --style=less --standalone=false
@v17-lts makes sure to use the latest version 17 of Angular. You can choose any name for the application, e.g. my-c8y-application. Do not enable Server-Side Rendering (SSR).
Once the Angular project has been generated, you will use the @c8y/websdk to scaffold it to a Cumulocity IoT application. In the command prompt, change directory to the new project and add the @c8y/websdk to the project:
cd my-c8y-application
ng add @c8y/websdk
A wizard will guide you through the process to scaffold a new Cumulocity IoT application. The wizards asks you from which version to scaffold the project from and which template should be used:
Select version latest, in this case 1020.0.x. Use the template application from which the project should be scaffolded from. The different templates are described in later articles. More information on creating new applications can be found in the official documentation.
Once the scaffolding has been finished, you can start the Cumulocity IoT web application:
ng serve -u <<C8Y-URL>>
Make sure to replace <<C8Y-URL>> with the URL of your Cumulocity IoT instance. The ng serve command will spin up a local web server and deploy the Cumulocity IoT web application. The -u parameter specifies the Cumulocity IoT instance to which all API requests should be proxied to. This means data is actually pulled from the configured Cumulocity IoT instance. The same applies for the authentication. The application can be accessed in the browser via the URL: http://localhost:4200/apps/my-c8y-application/. In case you choose a different application name, you will see your application name instead of my-c8y-application in the URL.
You will be greeted by the login screen.
Provide the tenant id and user credentials of your configured Cumulocity IoT instance. The tenant id can be found in your configured Cumulocity IoT tenant by clicking on your user at the top right of the header:
When you successfully signed in to your local Cumulocity IoT instance, you will see a blank application:
Note: It can happen that an error message appears if you view your application the first time:
No application for URI: my-application and tenant ID .... If this is the case for you, you need to deploy your application to the tenant once to have it recognized by Cumulocity. In Part 3 you can find detailed information on how you can deploy your application and what you need to consider.
Great, you have set up your development environment and created your first Cumulocity IoT web application. In the next articles, you will create plugins and widgets to bring some life to your web application. To stop your application, you can simply enter [CTRL] + [C] inside the terminal.
Conclusion & Next steps
That’s it for part 1 of this tutorial series. You can find the sample application in the github repository. In part 2 you will extend the empty application with a custom component. Furthermore, you will get to know some tips and best practices about c8y web development. If you like you can leave a comment if you want to see a specific topic to be covered in this tutorial series.
This article is part of the TECHniques newsletter blog - technical tips and tricks for the Software AG community. Subscribe to receive our quarterly updates or read the latest issue.