Cumulocity Web Development Tutorial - Part 1: Start your journey

Starting your journey as a web developer in Cumulocity 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.

overwhelming

To make your journey easier I have created this tutorial series. This tutorial series targets web developers, who want learn how they can implement custom applications, widgets and plugins for Cumulocity. The various articles of this series will teach fundamental concepts about web development in the context of Cumulocity 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 tenant and also basic knowledge about Cumulocity 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 general concept about web development in Cumulocity. 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’s API to query data and display it in your web component. This web component will be converted into a Cumulocity widget in the fourth article. You will learn more about extending one of Cumulocity’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!

overwhelming

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 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. The @c8y/cli supports you in creating, building and deploying your Cumulocity 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 1014.0.204 at the time of writing this article. As new versions of Cumulocity 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@next (1016.6.0 at the time of writing):

npx @c8y/cli@next 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 1014.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 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 web application:

npx c8ycli server -u <<C8Y-URL>>

Make sure to replace <<C8Y-URL>> with the URL of your Cumulocity instance. The server command will spin up a local web server and deploy the Cumulocity web application. The -u parameter specifies the Cumulocity instance to which all API requests should be proxied to. This means data is actually pulled from the configured Cumulocity 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 you configured Cumulocity instance. The tenant id can be found in your configured Cumulocity tenant by clicking on your user at the top right of the header:

image

When you successfully signed in to your local Cumulocity instance, you will see a blank application:

Great, you have set up your development environment and created your first Cumulocity 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.

alive

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.

7 Likes

I am just starting my journey on this and thanks for this article. Earlier I had several issues with different (latest) node/npm version with webpack errors etc and was struggling.

I have followed all the steps and now I am able to bring up devicemanager and cockpit localhost setup and able to login. However, upon login on the right side of the screen now the issue I see is I get a URL error:
"No application for URI: test-devicemanager and tenant ID [type=com_cumulocity_model_idtype_GId, value=…]

When I login using direct tenant URL link everything works fine.

Thanks again for streamlining the environment setup!

Looks like the name in package.json () file should match the registered application name (under Ecosystem>Applications>All applications). So for updating cockpit or devicemanager app the name has to match.