Jump-Start your next Cumulocity microservice project in java


Setting up a microservice for Cumulocity using Microservice SDK project is easy.

However, a few manual steps must be taken before you have a successfully running microservice locally configured to your Cumulocity instance. To speed this process up, use a maven archetype instead: cumulocity-microservice-archetype

This open-source maven archetype helps you to setup your maven project in less than 5 minutes!!!

It is not just faster; it is also a good template which are based on best practices.

In this blog post I show you, step by step how to use this cumulocity-microservice-archetype to setup your first project “hello”.


  • Java installed >= 11
  • Maven installed >= 3.6
  • Cumulocity IoT Tenant >= 1010.0.0
  • Cumulocity IoT User Credentials (Base64 encoded)

Steps to follow

Step 1: Go to GitHub - SoftwareAG/cumulocity-microservice-archetype: Maven archetype for cumulocity microservice. Developed by Global Competency Center IoT and clone the repository

Step 2: Build and install the cumulocity-microservice-archetype in your local maven repository

$ cd cumulocity-microservice-archetype
$ mvn install

Step 3: Generate your project by using the archetype

Before you run the mvn archetyp:generate command you should know:

  • Microservice name
  • Cumulocity development environment URL:
  • Cumulocity development environment User credentials in Base64

Your Base64 user credentials you can collect via Developer tools, Network tab. The request header contains the Authorization option.

If you have all the parameter, then you can run following script (replace Basic XXXXX with your Base64 credentials and https://your.tenant.cumulocity.com with your cumulocity instance)

$ mvn archetype:generate -DarchetypeGroupId=cumulocity.microservice -DarchetypeArtifactId=cumulocity-microservice-archetype -DinteractiveMode=false -DmicroserviceName=hello -DdevC8yBaseURL=https://your.tenant.cumulocity.com -DdevC8yUserCredentialsBASE64="Basic XXXXX"

If you run interactive mode you get for each parameter an input prompt. For more details look at GitHub - SoftwareAG/cumulocity-microservice-archetype: Maven archetype for cumulocity microservice. Developed by Global Competency Center IoT

If maven tells you “BUILD SUCCESS”, you can continue with Step 4

Step 4: Run your fresh generated microservice the first time

$ cd cumulocity-microservice-hello
$ mvn clean install
$ cd target
$ java -jar cumulocity-microservice-hello-1.0.0-SNAPSHOT.jar

Step 5: Open the browser a check if microservice is running successfully


The browser will open an user/password dialog. Insert you user in following way {tenant}/{user name}.

If this REST endpoint is returning an array of all devices. Well done, you have already setup your microservice project successfully!!

Step 6: Develop further and use some good examples

Now you can start developing your own features. The project contains a simple controller and service. These classes should be removed and are placeholders for your controllers and services.

If you have special nonfunctional requirements please check the microservice templates. They contain good examples how to solve common problems.

Useful links | Relevant resources