Introduction
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”.
Pre-requisite
- 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
Move to the location you would like to generate the project:
$ cd ..
$ cd workspace
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 use go-c8y-cli you can use an easier way of using the archetype. Just use the environment variable which are set by that cli
C8Y_BASEURLandC8Y_HEADER_AUTHORIZATION. set-session on your terminal and run following maven command Example:$ mvn archetype:generate -DarchetypeGroupId=cumulocity.microservice -DarchetypeArtifactId=cumulocity-microservice-archetype -DinteractiveMode=false -DmicroserviceName=hello -DdevC8yBaseURL="$C8Y_BASEURL" -DdevC8yUserCredentialsBASE64="$C8Y_HEADER_AUTHORIZATION"
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
http://localhost:8080/api/hello/devices
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
https://cumulocity.com/guides/microservice-sdk/java/
https://github.com/SoftwareAG/cumulocity-microservice-archetype
https://github.com/SoftwareAG/cumulocity-microservice-templates
https://maven.apache.org/guides/introduction/introduction-to-archetypes.html
