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. Make sure to install Node.js 14.x.x. Installing any later version might cause issues when trying to run or build a Cumulocity IoT web application.
Once you have finished the setup of Node.js you can install the @c8y/cli (command line interface) tool, which is provided by Cumulocity IoT. The @c8y/cli supports you in creating, building and deploying your Cumulocity IoT plugins and web applications. You can install the command line tools globally by running
npm install -g @c8y/cli
in your command prompt/terminal. This will install the latest official version, which is 1017.0.325 at the time of writing this article. As new versions of Cumulocity IoT are released frequently you also need to update the cli tools regularly to have the latest version. Instead of installing the 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 web application which is based on version @c8y/cli@latest (1017.0.325 at the time of writing):
npx @c8y/cli@latest new
Running this command will install the @c8y/cli locally in a cache and execute the new command. You will be guided by a wizard to set up your application. The wizard asks you for the name of the application, from which version to scaffold the project from and which template should be used:
You can choose any name, e.g. my-c8y-application. Select version latest, in this case 1017.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 Cumulocity IoT project has been generated by the @c8y/cli, you must install the dependencies. Change directory in the command prompt to your new project and install all necessary dependencies:
cd my-c8y-application
npm install
Once the installation is finished, you can start the Cumulocity IoT web application:
npx c8ycli server -u <<C8Y-URL>>
Make sure to replace <<C8Y-URL>> with the URL of your Cumulocity IoT instance. The server 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:9000/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.