Overview
This section describes how to develop and deploy microservices on top of Cumulocity IoT using the Microservice SDK for Java. It also contains a Hello world tutorial that you may follow to get the basics of developing microservices using Java. After you have successfully deployed your first microservice to Cumulocity IoT, you may also continue with the section Developing microservices to learn more about other features and capabilities of the SDK.
Info: You can develop microservices for Cumulocity IoT with any IDE and build tool that you prefer, but this section focuses on Maven and some troubleshooting for Eclipse.
These are some useful references to get started with the basic technologies underlying the SDK:
- The client libraries use the Cumulocity IoT REST interfaces as underlying communication protocol as described in the section Using the REST interface.
- All examples are open source and can be reviewed at the Cumulocity IoT microservices examples repository.
Important: You need to have at least version 8 of the Java Development Kit installed in your development environment as older versions of the JRE and JDK are not updated with the latest security patches and are not recommended for use in production.
If you face any issue or need technical support, please use the Cumulocity IoT community at Stack Overflow. You will find there many useful questions and answers.
Hello world tutorial
Here you will learn how to create your first microservice that can be deployed on the Cumulocity IoT platform using the Microservice SDK for Java.
Prerequisites
You need to have Cumulocity IoT credentials and a dedicated tenant. In case you do not have that yet, create an account on the Cumulocity IoT platform, for example by using a free trial. At this step you will be provided with a dedicated URL address for your tenant.
Verify that you have Java 8 installed together with Maven 3. It can be downloaded from the Maven website.
$ mvn -v
Apache Maven 3.6.0
Maven home: /Library/Maven/apache-maven-3.6.0
Java version: 1.8.0_201, vendor: Oracle Corporation
Java home (runtime): /Library/Java/JavaVirtualMachines/jdk1.8.0_201.jdk/Contents/Home/jre
OS name: "mac os x", version: "10.14.6", arch: "x86_64", family: "mac"
You will also need a Docker installation, and in case that you don’t have it yet, go to the Docker website to download and install it.
Cumulocity IoT hosts linux/amd64 Docker containers and not Windows containers. The Docker version must be 1.12.6 or above. Use the following command to verify your Docker installation:
$ docker version
Client: Docker Engine - Community
Version: 19.03.2
API version: 1.40
OS/Arch: darwin/amd64
Server: Docker Engine - Community
Engine:
Version: 19.03.2
API version: 1.40 (minimum version 1.12)
OS/Arch: linux/amd64
Developing the “Hello world” microservice
You can download the source code of this example from our Bitbucket or GitHub repositories to build and run it using your favorite IDE, or follow the instructions below to guide you step-by-step for you to have a better understanding of the code and what needs to be done/configured.
Important: This microservice example has been tested under macOS, Ubuntu 18 and Windows 10 with Java 8, Maven 3.6.0, Docker 19.03.2; Eclipse 2019.03 and IntelliJ IDEA 2019.2 as IDE. Other tools or Java versions may require different configurations.
Create a Maven project
Use the Maven Archetype Plugin to create a Java project from an existing Maven template. Use c8y.example
as your groupId, hello-microservice-java
as your artifactId, and set the version following the SemVer format as specified in Microservice manifest.
$ mvn archetype:generate -DgroupId=c8y.example -DartifactId=hello-microservice-java -Dversion=1.0.0-SNAPSHOT -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
This will create a folder hello-microservice-java in the current directory with a skeleton structure for your project.
Specify the properties
You will find the pom.xml file inside the hello-microservice-java folder. Edit this file and add a <properties>
element to set the -source
and -target
of the Java Compiler using version 1.8. This example uses Spring Boot to quickly build and create the application using the Spring Framework. Hence, also specify in the <properties>
element the version to use as follows:
<properties>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
<spring-boot-dependencies.version>1.5.17.RELEASE</spring-boot-dependencies.version>
</properties>
Add the Cumulocity IoT’s microservice library
You need to specify the version of the Cumulocity IoT’s microservice library to be used. This can be found on the platform; at the top-right corner, click the tenant user and find the backend version on the pop-up menu.
Alternatively, you can use an API call to retrieve the backend version:
GET {{url}}/tenant/system/options/system/version
The response looks like this:
{
"category": "system",
"value": "1004.6.12",
"key": "version"
}
See also Tenants > System options in the Reference guide.
In the <properties>
element specified above, add a child element <c8y.version>
with the backend version of your tenant. Also add a <microservice.name>
child element to name your microservice application.
<c8y.version>1004.6.12</c8y.version>
<microservice.name>hello-microservice-java</microservice.name>
Important: When naming your microservice application use only lower-case letters, digits and dashes. The maximum length for the name is 23 characters.
Add repositories and dependencies
Your pom.xml file needs to have <repository>
and <pluginRepository>
elements to point to the Cumulocity IoT Maven repository which stores the client libraries.
<repositories>
<repository>
<id>cumulocity</id>
<layout>default</layout>
<url>http://download.cumulocity.com/maven/repository</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>public</id>
<url>http://download.cumulocity.com/maven/repository</url>
</pluginRepository>
</pluginRepositories>
Also add a dependency for the Microservice SDK library inside the <dependencies>
node.
<dependencies>
...
<dependency>
<groupId>com.nsn.cumulocity.clients-java</groupId>
<artifactId>microservice-autoconfigure</artifactId>
<version>${c8y.version}</version>
</dependency>
</dependencies>
Add a <dependencyManagement>
element to automatically manage the required artifacts needed for your microservice application.
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.nsn.cumulocity.clients-java</groupId>
<artifactId>microservice-dependencies</artifactId>
<version>${c8y.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Configure the build plugins
Your microservice application has to be packed as a Docker image in a ZIP file including all the required dependencies. To achive that, include in your pom.xml file build plugins as follows:
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>${spring-boot-dependencies.version}</version>
<configuration>
<mainClass>c8y.example.App</mainClass>
</configuration>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>com.nsn.cumulocity.clients-java</groupId>
<artifactId>microservice-package-maven-plugin</artifactId>
<version>${c8y.version}</version>
<executions>
<execution>
<id>package</id>
<phase>package</phase>
<goals>
<goal>package</goal>
</goals>
<configuration>
<name>${microservice.name}</name>
<image>${microservice.name}</image>
<encoding>UTF-8</encoding>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
Create a Java application
Edit the App.java file located in the folder /src/main/java/c8y/example with the following content:
package c8y.example;
import com.cumulocity.microservice.autoconfigure.MicroserviceApplication;
import org.springframework.boot.SpringApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@MicroserviceApplication
@RestController
public class App {
public static void main (String[] args) {
SpringApplication.run(App.class, args);
}
@RequestMapping("hello")
public String greeting (@RequestParam(value = "name", defaultValue = "World") String you) {
return "Hello " + you + "!";
}
}
The code uses four annotations; three are part of the Spring Framework and one of the Cumulocity IoT Microservice SDK. The @RestController
annotation marks the class as a controller where every method returns a domain object instead of a view. The @RequestMapping
annotation ensures that HTTP requests to the hello endpoint are mapped to the greeting()
method. @RequestParam
binds the value of the query string parameter name into the you
parameter of the greeting()
method. Refer to the Spring Guides for more details about building RESTful Web Services using the Spring Framework.
Employing the @MicroserviceApplication
annotation is a simple way to add the required behavior for Cumulocity IoT microservices including:
- Security
- Subscription
- Health check endpoint at /service/<microservice-name>/health
- Context
- Settings
- Internal platform API
- Spring Boot application
Configure the microservice application
Create the directory src/main/resources to contain an application.properties file specifiying the name of the microservice application and the server port:
application.name=my-first-microservice
server.port=80
Create the directory src/main/configuration to contain a cumulocity.json file. This is the manifest file and it is required to deploy the microservice in the Cumulocity IoT platform.
{
"apiVersion": "1",
"version": "@project.version@",
"provider": {
"name": "Cumulocity GmbH"
},
"isolation": "MULTI_TENANT",
"requiredRoles": [
]
}
Build the microservice application
In a terminal, navigate to the folder where your pom.xml is located and execute the following Maven command:
$ mvn clean install
After a successful build, you will find a ZIP file inside the target directory.
$ ls target | grep zip
hello-microservice-java-1.0.0-SNAPSHOT.zip
Deploying the “Hello world” microservice
To deploy your microservice on the Cumulocity IoT platform you need:
- A valid tenant, a user and a password in order to access Cumulocity IoT.
- The ZIP file built with Maven on the previous steps.
Important: The Microservice hosting feature must be activated on your tenant, otherwise your request will return an error message like “security/Forbidden, access is denied”. This feature is not assigned to tenants by default, so trial accounts won’t have it. Contact us via Empower Portal so that we can assist you with the activation. Note that this is a paid feature.
In the Administration application, navigate to Applications > Own applications, click Add application and select Upload microservice from the options list.
Upload the ZIP file of your microservice application and click Subscribe for your tenant to be to subscribed to the microservice afterwards.
Once the ZIP file has been uploaded successfully, you will see a new microservice application created.
Test the deployed microservice
Employing your tenant credentials, you can test the microservice on any web browser using the URL as follows:
https://<yourTenantDomain>/service/hello-microservice-java/health
You can also use third-party applications or commands to make a GET request to your microservice endpoint. To do so, you need:
- A valid tenant, a user and a password in order to access Cumulocity IoT.
- An authorization header as “Basic <Base64(<tenantID>/<username>:<password>)>”.
For instance, if your tenant ID, username and password are t0071234, testuser and secret123 respectively, you can get the Base64 string with the following command:
$ echo -n t0071234/testuser:secret123 | base64
dDAwNzEyMzQvdGVzdHVzZXI6c2VjcmV0MTIz
and your authorization header would look like "Authorization": "Basic dDAwNzEyMzQvdGVzdHVzZXI6c2VjcmV0MTIz"
. Employing the cURL command you can test your microservice as follows:
$ curl -H "Authorization: <AUTHORIZATION>" https://<yourTenantDomain>/service/hello-microservice-java/hello?name=Skywalker
Running the microservice locally
You can run the Docker container locally in order to test the REST calls from the microservice to Cumulocity IoT.
To run a microservice which uses the Cumulocity IoT API locally, you need:
- A valid tenant, a user and a password in order to access Cumulocity IoT.
- An authorization header as “Basic <Base64(<tenantID>/<username>:<password>)>”.
Create the application
If the application does not exist, create a new application on the Cumulocity IoT platform employing a POST request.
POST <URL>/application/applications
HEADERS:
"Authorization": "<AUTHORIZATION>"
"Content-Type": "application/vnd.com.nsn.cumulocity.application+json"
"Accept: application/vnd.com.nsn.cumulocity.application+json"
BODY:
{
"name": "<APPLICATION_NAME>",
"type": "MICROSERVICE",
"key": "<APPLICATION_NAME>-key"
}
You have to replace the values <URL>
with the URL of your Cumulocity IoT tenant (domain), <AUTHORIZATION>
is Basic with a Base64 encoded string, and for <APPLICATION_NAME>
use the desired name for your microservice application and its key
name.
Important: When naming your microservice application use only lower-case letters, digits and dashes. The maximum length for the name is 23 characters.
The cURL command can be used to create the application with a POST request:
$ curl -X POST -s \
-d '{"name":"local-microservice-java","type":"MICROSERVICE","key":"my-hello-world-ms-key"}' \
-H "Authorization: <AUTHORIZATION>" \
-H "Content-Type: application/vnd.com.nsn.cumulocity.application+json" \
-H "Accept: application/vnd.com.nsn.cumulocity.application+json" \
"<URL>/application/applications"
In case of errors, e.g. invalid names, you will get the details printed in the console. When the application is created successfully, you will get a response in JSON format similar to the following example:
{
"availability": "PRIVATE",
"contextPath": "local-microservice-java",
"id": "<APPLICATION_ID>",
"key": "my-hello-world-ms-key",
"manifest": {
"noAppSwitcher": true,
"settingsCategory": null
},
"name": "local-microservice-java",
"owner": {
"self": "...",
"tenant": {
"id": "<TENANT_ID>"
}
},
"requiredRoles": [],
"roles": [],
"self": "<URL>/application/applications/<APPLICATION_ID>",
"type": "MICROSERVICE"
}
In the Administration application, navigate to Applications > Own applications. There you will see the created microservice.
Acquire the microservice bootstrap user
You will need the bootstrap user credentials in order to run the microservice locally. Get the details of your bootstrap user with a GET request.
GET <URL>/application/applications/<APPLICATION_ID>/bootstrapUser
HEADERS:
"Authorization": <AUTHORIZATION>
"Content-Type": application/vnd.com.nsn.cumulocity.user+json
Info: Besides the cURL command, you can also employ a graphical interface such as Postman.
Run the Docker container
The Docker image was built and added to the local Docker repository during the Maven build. You can list all the Docker images available with the following command:
$ docker images
Get your IMAGE ID and TAG from the list. While not strictly a means of identifying a container, you can specify a version of an image (TAG) you would like to run the container with. Run the Docker container for the microservice also providing the URL of your tenant and the bootstrap user credentials. Do not forget to expose the port 80 to a port on your host system, e.g. 8082.
$ docker run -p 8082:80 -e C8Y_BOOTSTRAP_TENANT=<BOOTSTRAP_TENANT> -e C8Y_BOOTSTRAP_USER=<BOOTSTRAP_USERNAME> -e C8Y_BOOTSTRAP_PASSWORD=<BOOTSTRAP_USER_PASSWORD> -e C8Y_MICROSERVICE_ISOLATION=MULTI_TENANT -i -t -e C8Y_BASEURL=<URL> <IMAGE_ID>
If your Docker image has run successfully, you shall see the output on the console similar to the one below.
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v1.5.7.RELEASE)
2019-10-21 15:53:07.510 INFO 7 --- [main] c8y.example.App : Starting App on dff01acae6d8 with PID 7 (/data/hello-microservice-java.jar started by root in /)
...
2019-10-21 15:53:17.583 INFO 7 --- [main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 80 (http)
2019-10-21 15:53:17.598 INFO 7 --- [main] c8y.example.App : Started App in 11.32 seconds (JVM running for 12.192)
Subscribe to the microservice
In the Administration application, navigate to Applications > Own applications. Locate your microservice application and click it to open its details. On the top right side click Subscribe.
At this point, you may open your favorite browser and test your microservice at http://localhost:8082/hello. Enter your bootstrap user credentials using <tenant>/<username> and your password.
You may also use the name parameter, e.g. http://localhost:8082/hello?name=Neo.
Improving the microservice
Now that you have done your first steps, check out the section Developing microservices to find out what else can be implemented. Review also the Java example in this guide to learn using more features of the microservice SDK and REST API by employing third-party services.
Developing microservices
It is described below the different microservice SDK features, including annotations, services, configuration files, logging and the Maven build plugin.
There are two possible deployment types on the platform:
- Hosted deployment - The default for microservices and the suggested one for typical use cases.
- External/legacy deployment - Requires custom installation of the platform and agent.
For development and testing purposes, one can deploy a microservice on a local Docker container.
Annotations
The simplest way to add required behavior to your application is to annotate a main class with @MicroserviceApplication
. This is a collective annotation consisting of:
Annotation | Description |
---|---|
@SpringBootApplication | Comes from Spring Boot auto configure package |
@EnableContextSupport | Required to use @UserScope or @TenantScope scopes for method invocations |
@EnableHealthIndicator | Provides a standard health endpoint used by the platform to monitor the microservice availability |
@EnableMicroserviceSecurity | Provides a standard security mechanism, verifying user and roles against the platform |
@EnableMicroserviceSubscription | Responsible for subscribing microservices to the platform, updating metadata and listening to tenant subscription change events |
@EnableMicroservicePlatformInternalApi | Injects the platform API services into Spring context for a microservice to use |
@EnableTenantOptionSettings | Provides microservice configuration within tenant options and allows overriding default properties from files |
Context support
It is described below the context support as utility tool for the user management described in General aspects of microservices in Cumulocity IoT.
@UserScope
and @TenantScope
at type level annotation indicate that a bean created from class will be created in the scope defined. The user scope implies using tenant platform user credentials for platform calls. The tenant scope implies using service user credentials.
An example of injecting a bean into the tenant scope is available in the platform API module as follows:
@TenantScope
public EventApi eventApi (Platform platform) throws SDKException {
return platform.getEventApi();
}
A sample utilization of the bean can be as follows:
@Autowired
private PlatformProperties platformProperties;
@Autowired
private ContextService<MicroserviceCredentials> contextService;
@Autowired
private EventApi eventApi;
public PagedEventCollectionRepresentation get10Events () {
return contextService.callWithinContext(
(MicroserviceCredentials) platformProperties.getMicroserviceBoostrapUser(),
new Callable<PagedEventCollectionRepresentation>(){
public PagedEventCollectionRepresentation call(){
return eventApi.getEvents().get(10);
}
});
}
Microservice security
The @EnableMicroserviceSecurity
annotation sets up the standard security configuration for microservices. It requires basic authorization for all endpoints (except for health check endpoint configured using @EnableHealthIndicator
). A developer can secure its endpoints using standard Spring security annotations, e.g. @PreAuthorize("hasRole('ROLE_A')")
and user’s permissions will be validated against user’s roles stored on the platform.
Microservice subscription
The microservice subscription module is responsible for two main features:
- Registration
- Tenant subscription event listening
The default behavior for the package is self-registration, which means that after you run the application it will try to register and use the generated credentials for the communication with the platform. The self-registration is required to correctly deploy the microservice on the platform.
The other way to register an application to the platform is to do it manually. This can be done by creating a new application on the platform with the same application name and providing the following properties into the microservice:
application.name=<application_name>
C8Y.bootstrap.register=false
C8Y.bootstrap.tenant=<tenant>
C8Y.bootstrap.user=<username>
C8Y.bootstrap.password=<password>
To create an application and acquire credentials, refer to Creating applications and Acquiring microservice credentials in the Using the REST interface section.
The subscription package provides means to monitor and it acts upon changes in tenant subscriptions to a microservice. To add a custom behavior, a developer can add an event listener for MicroserviceSubscriptionAddedEvent
and MicroserviceSubscriptionRemovedEvent
as the following example:
@EventListener
public void onAdded (MicroserviceSubscriptionAddedEvent event {
log.info("subscription added for tenant: " + event.getCredentials().getTenant());
});
On application startup, the MicroserviceSubscriptionAddedEvent
is triggered for all subscribed tenants.
Heap and perm/metadata
To calculate heap and perm/metadata, it takes the limit defined on the microservice manifest and it is converted into Megabytes (MB). For Java applications developed using the Java Microservice SDK the minimal value is 178MB.
10% is reserved for “system”, but not less than 50 MB.
10% is taken for PermGen on JDK 7 or Metaspace on JDK 8, but not less than 64 MB and not more than 1024MB.
The rest is allocated for heap size.
Platform API
The package consists of a number of services that are built and injected into Spring context. A developer can use them to perform basic operations against the platform. The beans are built based on the properties read from a file. For hosted deployment, most of the properties are provided by the platform.
The API provides the following services:
- Alarm - AlarmApi
- AuditRecord - AuditRecordApi
- CepModule - CepApi
- Operation - DeviceControlApi
- Event - EventApi
- ExternalID - IdentityApi
- Binary - BinariesApi
- ManagedObject - InventoryApi
- Measurement - MeasurementApi
The API provides basic CRUD methods. The following is an alarm interface example:
// Methods
AlarmRepresentation create(final AlarmRepresentation alarm)
Future createAsync(final AlarmRepresentation alarm)
AlarmRepresentation getAlarm(final GId gid)
AlarmCollection getAlarms()
AlarmCollection getAlarmsByFilter(final AlarmFilter filter)
AlarmRepresentation update(final AlarmRepresentation alarm)
Sample usage:
@Autowired
private AlarmApi alarms;
public AlarmRepresentation addHelloAlarm (){
AlarmRepresentation alarm = new AlarmRepresentation();
alarm.setSeverity("CRITICAL");
alarm.setStatus("Hello");
return alarms.create(alarm);
}
Configuration files
The properties file used by the hosted deployment must be located in src/main/resources/application.properties.
The properties used by a microservice are:
Property | Description |
---|---|
application.name | The name of the microservice application |
C8Y.bootstrap.register | Indicates if a microservice should follow self-registration process. True by default |
C8Y.baseURL | Address of the platform. Provided by the deployment process |
C8Y.baseURL.mqtt | Address of the MQTT service. Provided by the platform |
C8Y.bootstrap.tenant | Microservice owner tenant |
C8Y.bootstrap.user | User used by a microservice or by the microservice registration process |
C8Y.bootstrap.password | Password used by a microservice or by the microservice registration process |
C8Y.bootstrap.delay | Subscription refresh delay |
C8Y.bootstrap.initialDelay | Initial subscription delay |
C8Y.microservice.isolation | Microservice isolation. Only PER_TENANT or MULTI_TENANT values are available. MULTI_TENANT by default |
C8Y.httpReadTimeout | Read timeout interval for HTTP client in milliseconds. Defaults to 3 minutes |
Microservice settings
The microservice settings module provides two features:
- Configure a microservice by defining tenant options
- Override existing properties - Tenant options can override default values from properties files
By default the microservice loads the tenant options for the category specified by the microservice context path.
The custom settings category can be specified by the manifest parameter: settingsCategory
.
When neither settings category nor context path is provided in the microservice manifest, the application name is used.
Info: Once the microservice is deployed it is not possible to change the category during application upgrade.
Options can be configured for the application owner or the subscriber. The subscriber can override the owner’s option value only when such option is defined as editable.
Settings are lazy cached for 10 minutes, so when they were accessed previously, the user must wait the remaining time to see the change being applied. When the access attempt occurs to fetch settings without the tenant context being specified, the application owner is used to complete the request.
Info: For security reasons, the functionality is not available when running the microservice in legacy mode, i.e. local development or RPM installation.
Tenant option settings can be accessed in two ways:
Using Environment:
@Autowired
private Environment environment;
public int getAccessTimeout() {
return environment.getProperty("access.timeout", Integer.class, 30);
}
Using settings service:
@Autowired
private MicroserviceSettingsService settingsService;
public String getAccessTimeout() {
return settingsService.get("access.timeout");
}
Settings can be encrypted by using the credentials. prefix for the tenant option key. They will be decrypted and become available within the microservice environment.
Defining tenant options for a microservice with the same key as it was defined in the configuration files, such as .properties or the manifest file, will override the particular property.
For instance, there is a property defined in the application.properties file of the microservice hello-world with context path helloworld:
access.timeout=25
Now the microservice owner can override it by defining the following setting in the cumulocity.json manifest file:
"settings": [{
"key": "access.timeout",
"defaultValue": "35",
"editable": true
}]
Because the access.timeout
setting is defined as editable, the subscriber can override it by creating an own tenant option via REST API:
POST <URL>/tenant/options
BODY:
{
"category": "helloworld",
"key": "access.timeout",
"value": "40"
}
Note: You cannot override a property injected by Spring
@Value("${property.name}")
.
Logging
The standard output should be used for hosted deployment.
Maven plugin
The package module provides a Maven plugin to prepare a ZIP file required by the microservice deployment. The build requires an executable JAR file. To create one, a developer can use spring-boot-maven-plugin
. An example with minimum configuration is presented below:
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
<configuration>
<mainClass>${main.class}</mainClass>
</configuration>
</plugin>
<plugin>
<groupId>com.nsn.cumulocity.clients-java</groupId>
<artifactId>microservice-package-maven-plugin</artifactId>
<version>9.16.2</version>
<executions>
<execution>
<id>package</id>
<phase>package</phase>
<goals>
<goal>package</goal>
</goals>
<configuration>
<name>hello-world</name>
<encoding>UTF-8</encoding>
<rpmSkip>true</rpmSkip>
<containerSkip>false</containerSkip>
</configuration>
</execution>
<execution>
<id>microservice-package</id>
<phase>package</phase>
<goals>
<goal>microservice-package</goal>
</goals>
<configuration>
<name>hello-world</name>
<image>hello-world</image>
<encoding>UTF-8</encoding>
<skip>false</skip>
</configuration>
</execution>
</executions>
</plugin>
Package goal
The package plugin is responsible for the creation of a Docker container, rpm file and for creating a ZIP file that can be deployed on the platform. It can be configured with the following parameters:
- name (alias package.name) - defaults to project.artifactId
- description (alias package.description) - defaults to project.description
- jvmArgs (alias agent-package.jvmArgs) - jvm-gc arguments. The default value is
-XX:+UseConcMarkSweepGC -XX:+CMSParallelRemarkEnabled -XX:+ScavengeBeforeFullGC -XX:+CMSScavengeBeforeRemark
". It will be overwritten if other options are provided. - arguments (alias agent-package.arguments) - arguments passed during application startup
- encoding (alias project.build.sourceEncoding) - defaults to UTF-8
- heap (alias agent-package.heap) - defaults to min = 128MB max = 384MB
- perm (alias agent-package.perm) - defaults to min = 64MB max = 128MB
- skip (alias skip.agent.package) - to skip the whole packaging part
- rpmSkip (alias skip.agent.package.rpm) - to skip rpm file creation. False by default
- containerSkip (alias skip.agent.package.container) - to skip Docker image creation. True by default
- manifestFile - points to a manifest file location. Default value: $
/src/main/configuration/cumulocity.json
Example configuration:
<configuration>
<name>hello-world</name>
<encoding>UTF-8</encoding>
<rpmSkip>true</rpmSkip>
<containerSkip>false</containerSkip>
<manifestFile>${basedir}/src/main/microservice/cumulocity.json</manifestFile>
</configuration>
Push goal
The push plugin is responsible for pushing the Docker image to a registry. The registry can be configured by:
- containerSkip (alias skip.agent.package.container) - Prevents the push to execute. True by default
- registry (alias agent-package.container.registry) - Docker registry address
Example configuration:
<configuration>
<registry>http://{yourregistry.com}</registry>
<containerSkip>false</containerSkip>
</configuration>
Upload goal
The upload goal is responsible for deploying the microservice to a server. There are three options to configure the server URL and credentials:
- settings.xml - Maven global configuration placed at ~/.m2/settings.xml
- pom.xml - Maven project configuration file
- Command line
All three ways can be used together, e.g. a goal partially can be configured in the settings.xml and partially in the pom.xml. In case of conflicts, the command line configuration has the highest priority and settings.xml configuration the lowest.
To upload a microservice to the server you need to configure the following properties:
- url - Mandatory URL that will be used for deployment. Empty by default.
- username - Mandatory tenant ID and user name used for authorization. Empty by default.
- password - Mandatory password used for authorization. Empty by default.
- name - Optional name of the uploaded application. By default it is the same as
package.name
property orartifactId
ifpackage.name
is not provided.
settings.xml
To configure the goal in the settings.xml file, add the server configuration as follows:
<server>
<id>microservice</id>
<username>demos/username</username>
<password>******</password>
<configuration>
<url>https://demos.cumulocity.com</url>
</configuration>
</server>
pom.xml
To configure the plugin in the pom.xml file, add the server configuration as follows:
<plugin>
<groupId>com.nsn.cumulocity.clients-java</groupId>
<artifactId>microservice-package-maven-plugin</artifactId>
<configuration>
<application>
<name>cep</name>
</application>
<!-- please note that the credentials are optional if they are already configured in settings.xml -->
<credentials>
<url>https://demos.cumulocity.com</url>
<username>demos/username</username>
<password>******</password>
</credentials>
</configuration>
</plugin>
Command line
To pass the configuration only to the particular build, execute the following command:
$ mvn microservice:upload -Dupload.application.name=cep -Dupload.url=https://demos.cumulocity.com -Dupload.username=demos/username -Dupload.password=******
Deployment
Hosted deployment
Info: For your convenience, Cumulocity IoT provides a Microservice utility tool for easy packaging, deployment and subscription.
To deploy an application on an environment you need the following:
- URL address of your tenant
- Authorization header as “Basic <Base64(
: )>” - Tenant - tenant ID
- ZIP build from previous steps
Step 1 - Create the application
If the application does not exist, create a new application on the platform:
POST /application/applications
Host: ...
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: "application/json"
BODY:
{
"name": "<APPLICATION_NAME>",
"type": "MICROSERVICE",
"key": "<APPLICATION_NAME>-microservice-key"
}
Example:
$ curl -X POST -s \
-d '{"name":"hello-microservice-1","type":"MICROSERVICE","key":"hello-microservice-1-key"}' \
-H "Authorization: <AUTHORIZATION>" \
-H "Content-type: application/json" \
"<URL>/application/applications"
If the application has been created correctly, you can GET the application ID:
GET /application/applicationsByName/<APPLICATION_NAME>
Host: ...
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: "application/json"
Example:
$ curl -H "Authorization:<AUTHORIZATION>" \
<URL>/application/applicationsByName/hello-world
Step 2 - Upload the ZIP file
POST /application/applications/<APPLICATION_ID>/binaries
Host: ...
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: "multipart/form-data"
Example:
$ curl -F "data=@<PATH_TO_ZIP>" \
-H "Authorization: <AUTHORIZATION>" \
"<URL>/application/applications/<APPLICATION_ID>/binaries"
Step 3 - Subscribe to the microservice
POST /tenant/tenants/<TENANT_ID>/applications
Host: ...
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: "multipart/form-data"
BODY:
{
"application": {
"id": "<APPLICATION_ID>"
}
}
Example:
$ curl -X POST -d '{"application":{"id": "<APPLICATION_ID>"}}' \
-H "Authorization: <AUTHORIZATION>" \
-H "Content-type: application/json" \
"<URL>/tenant/tenants/<TENANT_ID>/applications"
Local Docker deployment
To deploy the application on a local Docker container, one needs to inject the environment variables into a container. This is done with the Docker run -e
command. The full description of available parameters is available in Environment variables.
An example execution could be:
$ docker run -e "C8Y_BASEURL=<C8Y_BASEURL>" -e "C8Y_BASEURL_MQTT=<C8Y_BASEURL_MQTT>" <IMAGE_NAME>
Monitoring
The microservice’s health endpoint can be checked to verify if a hosted microservice is running successfully. This endpoint is enabled by default for all microservices that are developed using the Java Microservice SDK.
GET <URL>/service/<APPLICATION_NAME>/health
Example response when the microservice is functional:
HTTP/1.1 200
{
"status": "UP"
}
or in case it is not working:
HTTP/1.1 503
{
"status": "DOWN"
}
Legacy Deployment
Properties
For external/legacy deployment, the following paths will be searched in order to find a properties file specific for the environment the application is run on:
- {UPPERCASE(application_name)}_CONF_DIR/.{application_name}
- {UPPERCASE(application_name)}_CONF_DIR/{application_name}
- {user/home}/.{application_name}
- {user/home}/{application_name}
- {CONF_DIR}/.{application_name}
- {CONF_DIR}/{application_name}
- /etc/{application_name}
Logging
For external/legacy deployment, logging into the application implies using Spring Logging. The following locations are searched for log-back file:
- {UPPERCASE(application_name)}_CONF_DIR/.{application_name}/logging.xml
- {UPPERCASE(application_name)}_CONF_DIR/{application_name}/logging.xml
- {user/home}/.{application_name}/logging.xml
- {user/home}/{application_name}/logging.xml
- {CONF_DIR}/.{application_name}/logging.xml
- {CONF_DIR}/{application_name}/logging.xml
- /etc/{application_name}/logging.xml
Services platform and SMS API
This section describes the Cumulocity IoT SMS API and shows how to access it using the Cumulocity IoT Java Client. You will also learn how to send and receive SMS messages via the Java Client API.
Using the services platform
The services platform interface is responsible for connecting to the Java services (SMS) API.
ServicesPlatform platform = new ServicesPlatformImpl("<URL>", new CumulocityCredentials("<tenant>", "<user>", "<password>", "<application key>"));
The URL pointing to the platform must be of the form <tenant>.cumulocity.com, for example https://demos.cumulocity.com, which will process all the API requests.
Info: You need to have appropriate credentials to be able to access the Services API from outside. See the example above.
Accessing the SMS Messaging API
The following code snippet shows how to obtain a handle to the SMS API from Java.
SmsMessagingApi smsMessagingApi = platform.getSmsMessagingApi();
Using this handle, you can send and retrieve the SMS messages from Java by calling its functions.
Assigning required roles
To use the SMS messaging API, the user must have the required roles SMS_ADMIN and SMS_READ for sending and receiving messages respectively. Refer to Administration > Managing permissions in the User guide.
Choosing a SMS provider
OpenIT
OpenIT credentials can be assigned using the Administration application. Click OpenIT credentials in the navigator and save these credentials for your tenant.
Note that receiving messages and receiving specific messages are not supported for this provider.
Jasper Control Center
Refer to Optional services > Connectivity in the User guide for information about how to set these credentials.
Ericsson
Use our Rest API to store tenant options separately for each key:
POST /tenant/options
Host: ...
Authorization: Basic ...
Provider:
{
"category": "messaging",
"key": "provider",
"value": "ericsson-dcp"
}
Base URL:
{
"category": "messaging",
"key": "ericsson-dcp.baseUrl",
"value": "<URL>"
}
Username:
{
"category": "messaging",
"key": "ericsson-dcp.username",
"value": "<username>"
}
Password:
{
"category": "messaging",
"key": "ericsson-dcp.password",
"value": "<password>"
}
Sender address:
{
"category": "messaging",
"key": "sms.senderAddress",
"value": "<The phone number all SMS will be sent from (provided by Ericsson DCP)>"
}
Sender name:
{
"category": "messaging",
"key": "sms.senderName",
"value": "<The name associated with the phone number>"
}
Note that receiving specific messages is not supported for this provider.
Telia Sonera
Use our Rest API to store tenant options separately for each key:
POST /tenant/options
Host: ...
Authorization: Basic ...
Provider:
{
"category": "messaging",
"key": "provider",
"value": "soneraoma"
}
Username of Telia Sonera Client Application:
{
"category": "messaging",
"key": "soneraoma.username",
"value": "<username>"
}
Password assigned for Telia Sonera Client Application:
{
"category": "messaging",
"key": "soneraoma.password",
"value": "<password>"
}
Telia Sonera OAuth Service Endpoint:
{
"category": "messaging",
"key": "soneraoma.authUrl",
"value": "<OAuth Service endpoint URL as appears in TS Application Profile, e.g., https://api.sonera.fi/autho4api/v1>"
}
Telia Sonera Messaging OMA v1 Endpoint:
{
"category": "messaging",
"key": "soneraoma.messagingUrl",
"value": "<Messaging endpoint URL as appears in TS Application Profile, e. g., https://api.sonera.fi/sandbox/messaging/v1>"
}
Note that receiving messages and receiving specific messages is not supported for this provider.
Tropo
Use our Rest API to store tenant options separately for each key:
POST /tenant/options
Host: ...
Authorization: Basic ...
Provider:
{
"category": "messaging",
"key": "provider",
"value": "tropo"
}
Base URL:
{
"category": "messaging",
"key": "tropo.baseUrl",
"value": "<URL>"
}
Credentials:
{
"category": "messaging",
"key": "tropo.credentials",
"value": "<credentials>"
}
Sender address:
{
"category": "messaging",
"key": "sms.senderAddress",
"value": "cumulocity"
}
Sender name:
{
"category": "messaging",
"key": "sms.senderName",
"value": "cumulocity"
}
Note that receiving messages and receiving specific message is not supported for this provider.
Sending a message
To send a SMS message using the API, prepare the message with the SendMessageRequest builder and call the sendMessage function of the API with the prepared message.
SendMessageRequest smsMessage = SendMessageRequest.builder()
.withSender(Address.phoneNumber("<phone number>"))
.withReceiver(Address.phoneNumber("<phone number>"))
.withMessage("<message text>")
.build();
smsMessagingApi.sendMessage(smsMessage);
Receiving messages
You can use the API as follows to receive all SMS messages. Note that not every SMS provider supports receiving messages.
smsMessagingApi.getAllMessages(Address.phoneNumber("<phone number>"));
You can use the API as follows to receive a specific SMS message identified by message ID. Note that not every SMS provider supports receiving messages.
smsMessagingApi.getMessage(Address.phoneNumber("<phone number>"), "<message id>");
SMS management endpoints
The Rest API can be used to send and receive SMS messages.
Sending a message:
POST /service/messaging/smsmessaging/outbound/tel:<sender phone number>/requests
Host: ...
Authorization: Basic ...
Content-Type: application/json
{
"outboundSMSMessageRequest": {
"address": ["tel:<phone number>"],
"senderAddress": "tel:<phone number>",
"outboundSMSTextMessage": {
"message": "<message text>"
},
"receiptRequest": {
"notifyUrl": "<notify url>",
"callbackData": "<callback data>"
},
"senderName": "<sender name>"
}
}
Receiving all messages:
GET /service/messaging/smsmessaging/inbound/registrations/tel:<receiver phone number>/messages
Host: ...
Authorization: Basic ...
HTTP/1.1 200 OK
{
"inboundSMSMessageList": [
{
"inboundSMSMessage": {
"dateTime": "<date>",
"destinationAddress": "<destination address>",
"messageId": "<message id>",
"message": "<message>",
"resourceURL": "<resource url>",
"senderAddress": "<sender address>"
}
]
}
Receiving a specific message:
GET /service/messaging/smsmessaging/inbound/registrations/tel:<receiver phone number>/messages/<message id>
Host: ...
Authorization: Basic ...
HTTP/1.1 200 OK
{
"inboundSMSMessage": {
"dateTime": "<date>",
"destinationAddress": "<destination address>",
"messageId": "<message id>",
"message": "<message>",
"resourceURL": "<resource url>",
"senderAddress": "<sender address>"
}
}
Troubleshooting
Some common problems and their solutions have been identified and documented below.
SSL or certificate errors
You can use both HTTP and HTTPS from the Java client libraries. To use HTTPS, you may need to import the Cumulocity IoT production certificate into your Java Runtime Environment. Download the certificate and import it using the following command:
$ $JAVA_HOME/bin/keytool -import -alias cumulocity -file cumulocity.com.crt -storepass changeit
Answer “yes” to the question “Trust this certificate? [no]:”.
Use the following argument to run Java:
-Djavax.net.ssl.trustStore=<home directory>/.keystore
If you use Eclipse/OSGi, open the Run Configurations… dialog in the Run menu. Double-click OSGi Framework, then open the Arguments tab on the right side. In the VM arguments text box, add the above parameter.
Since Java ships with its own set of trusted root certificates, you might still get the error message “java.security.cert.CertificateException: Certificate Not Trusted”. In this case, make sure that the Go Daddy Certificate Authority (CACert) is available for your JAVA environment using the following command:
$ keytool -import -v -trustcacerts -alias root -file gd_bundle.crt -keystore $JAVA_HOME/lib/security/cacerts
gd_bundle.crt can be downloaded directly from the GoDaddy repository.
When I install the SDK, Eclipse complains about compatibility problems
Make sure that you use the Target Platform preferences page to install the SDK as described in the instructions. Install New Software installs software into your running Eclipse IDE, but you need to install the SDK as a separate server software.
I get “Expected to find an object at table index” when running a microservice or application
This error occurs due to a bug in particular Eclipse versions. As a workaround, select Run from the main menu and then Run Configurations …. On the left, select the launch configuration that you have been using, e.g. OSGi Framework. On the right, click the Arguments tab. Append a " -clean" to the Program Arguments and click Apply.
The microservice or application won’t start
Verify that all required plug-ins are checked in your launch configuration. Go to Run > Run Configurations and select the OSGi Framework launch configuration. Click Select All and try running it again.
Check if the required plug-ins are started. While the application or microservice is running, type “ss” into the console and hit the return key. All listed plug-ins should be either in the ACTIVE or RESOLVED state.
Check if you are using the correct target platform. Go to the Target Platform page in the preferences and check if “Cumulocity runtime” is checked.
The microservice application does not compile. I get “Access Restriction” messages
This error may be caused because of a missing package import. Navigate to the Dependencies tab of the project manifest file and check if the package of the type that contains the method giving the access restriction is present in the Import-Package section.
You can find the package by opening the declaration of the method (right-click and select Open Declaration from the context menu).
When starting an application I get “address already in use” messages
Check if you are running another instance of the application. Click on the Display Selected Console icon in the console toolbar (the terminal icon) to browse through your consoles. Terminate other running instances by clicking the red Stop icon in the toolbar.
Under Unix/macOS you can also use the lsof
command to see which process is using a particular port. For example, to see which process is using TCP port 8080 enter:
$ lsof -i tcp:8080
It will return something like:
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
java 12985 neo 45u IPv6 0x077c76d0 0t0 TCP *:8080 (LISTEN)
This means that the process 12985 is using the 8080 port and it can be killed if necessary.
When trying to build an application I get a “BeanCreationException: Error creating bean with name methodSecurityInterceptor” error
This is caused mainly by versions incompatibility between the SDK and Spring Boot specified in your pom.xml file. If you want to use a recent version of the SDK, e.g. 10.4.0, the version of Spring Boot must be 1.5.17 or later.
Missing Docker permissions in Linux
When you build a microservice application via mvn
, you might get this error:
[ERROR] Failed to execute goal com.nsn.cumulocity.clients-java:microservice-package-maven-plugin:1004.6.12:package (package) on project hello-microservice-java: Execution package of goal com.nsn.cumulocity.clients-java:microservice-package-maven-plugin:1004.6.12:package failed: org.apache.maven.plugin.MojoExecutionException: Exception caught: java.util.concurrent.ExecutionException: com.spotify.docker.client.shaded.javax.ws.rs.ProcessingException: java.io.IOException: Permission denied -> [Help 1]
This is an issue with Docker in Linux OS. You can verify that your user is lacking permissions for Docker by running:
$ docker ps
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.40/containers/json: dial unix /var/run/docker.sock: connect: permission denied
In order to fix this, do the following:
-
Create the Docker group.
$ sudo groupadd docker
-
Add your user to the Docker group.
$ sudo usermod -aG docker $your_user_name
-
Log out and log back in, so that your group membership is updated. Alternatively, run
$ newgrp docker
-
Try running a Docker command again.
Also refer to Docker Engine > Installation per distro > Optional post-installation steps in the Docker documentation.