Developing applications

Overview

Cloud of Things applications can have two forms:

• web applications - web-based user interface applications
• microservices - server-side business logic

Web applications are HTML5 single page applications, that appear in the Cloud of Things application switcher and that are hosted in the Cloud of Things platform.

Microservices are Docker containers, hosted by Cloud of Things and exposing a REST API.

Applications regardless of their form are identified by a so-called application key. The application key enables Cloud of Things to associate a REST request from an application with the particular application. The application key is the unique identifier of the application and should remain unchanged in all versions of that application. See the section on Application management in the Cloud of Things OpenAPI Specification.

Super tenants (Management tenants or Enterprise tenants) can subscribe subtenants to Cloud of Things applications deployed by them. This provides a basic application marketplace.

Web applications

Overview

A Cloud of Things web application can be a

• a user interface application built on any web framework of your choice
• a user interface application built using the Cloud of Things user interface framework as a set of user interface plugins.

All subscribed web applications of a tenant appear in the application switcher on the top right of theCloud of Things UI, so that users can navigate between the applications. They are hosted by Cloud of Things and the application will be made available through a URL <tenant>.ram.m2m.telekom.com/apps/<application>.

The Cloud of Things UI itself is built around a framework based on Angular, AngularJS and Bootstrap, the modern HTML5 web application frameworks. It is designed in a modular fashion around a set of plugins so that developers can create their own configurations of the Cloud of Things user interfaces. For more information on developing plugins, refer to Web SDK for plugins.

Deploying web applications

For an application to be available it must be deployed on the Cloud of Things platform.

For details on how to deploy an application to Cloud of Things, refer to Administration > Managing applications in the User guide.

Web application hosting

You can host your own HTML5 and JavaScript web applications through Cloud of Things by using the application manager under Ecosystem > Applications > All applications in the Cloud of Things Administration application.

For details refer to Administration > Managing applications in the User guide.

Microservices

Microservices are server-side applications. Microservices can be used to develop for example the following functionality on top of Cloud of Things:

• Integrations
• Batch analytics
• Decoder
• Backend applications

Microservices are deployed as Docker images to Cloud of Things, and follow specific conventions. They typically provide one REST API, which is available under /service/<microservice-name>. They typically access Cloud of Things using the documented REST API.

When developing a Cloud of Things microservice, a developer is not restricted to any programming language. However, a microservice must serve as a HTTP server working on port 80 and must be encapsulated in a Docker image.

The hosting of the microservice is provided by Cloud of Things. This way developers can focus on business logic and leave scaling, security, high availability and monitoring to Cloud of Things. Microservices can be built on top of the API exposed by the Cloud of Things. This way, Cloud of Things microservices are a comfortable means to provide new functionality and extend existing ones.

For detailed information on developing and deploying microservices on top of Cloud of Things refer to the Microservice SDK guide which provides information on the general concept of microservices in Cloud of Things as well as specific guidance and examples for various programming languages. For microservice developers Cumulocity provides a Microservice SDK in the Java programming language.

Subscribing applications

The application concept of Cloud of Things includes a basic application marketplace.

Tenants can be subscribed to applications which have been deployed by their superior tenant (Management tenant or Enterprise tenant).

Granting access to subtenants and subscribing to applications is done in the Administration application, see Enterprise tenant > Managing tenants > Applications in the User guide.

Tenants can also have their own applications which can also be subscribed to subtenants. See Administration > Managing application > Custom applications in the User guide for details on adding custom applications.

Service discovery

A tenant can have multiple available applications but to use an application’s functionality a subscription to the application must be established for the tenant. As an example, when a custom decoder microservice is available in the tenant’s marketplace, it is not enabled to be used until the tenant subscribes for the microservice application.

To see the list of subscribed applications for the tenant, the Cloud of Things REST API can be used to get specific tenant information. Those applications will be listed under the applications fragment.

Extensible device registration

Introduction

To address the growing number of IoT protocols and certain restrictions in the general single or bulk device registration, an extensible device registration is available with release 10.15.

The general concept is based on extending the device registration using a metadata-based approach. Microservices and agents that implement current device registrations can add custom forms to the device registration wizard by providing simple descriptions of the required registration attributes. The metadata is then used by the UI to render a corresponding device registration wizard.

There are two possible ways to extend the UI:

• with a single device registration form
• with a bulk device registration form

Advantages of extended device registration

The extended device registration provides the following advantages:

• Extensibility of the device registration wizard: You can easily add own forms to the device registration wizard in the Device management application UI. The values to be entered in the user-specified forms can be freely customized by the device integration developers.

• Support for bulk registration using custom CSV: You can customize the bulk registration and hence implement support for CSV files of a different format.

• No UI code changes required: You do not need to write UI Angular code. This keeps the amount of integration work as little as possible. The device integration developer only needs to subscribe a microservice that provides an own wizard, and the wizard shows up automatically.

Extension enabling

As a first step to extend the device registration flow you must define extensions in the application representation.

There are two types of extensions:

• Single device registrations type: extensibleDeviceRegistration, for example:

"extensions": [
  {
    "name": "<extension name>",
    "description": "<description>",
    "type": "extensibleDeviceRegistration"
  },
  ...
]

• Bulk device registration type: extensibleBulkDeviceRegistration, for example:

"extensions": [
  {
    "name": "<extension name>",
    "description": "<description>",
    "type": "extensibleBulkDeviceRegistration"
  },
  ...
]

Single device registration

After enabling the extensibleDeviceRegistration extension type, the Devices > Register device menu in the Device management application is extended with an entry corresponding to the extension name property.

From now on, everything will be rendered based on data provided via the custom microservice. The added menu entry opens a window which fetches the form definition using the following endpoint:

GET /service/<contextPath>/deviceRegistration/metadata&lang=<user-language>

Make use of the lang query parameter in your microservice to respond with the already translated JSON Schema metadata. See also Limitations.

The UI automatically takes the contextPath for the GET request from the application definition of the microservice:

{
  "contextPath": "<relative path>",
  "availability": "MARKET",
  "type": "MICROSERVICE",
  "name": "<agent name>",
  ...
}

Example metadata definition:

{
    "c8y_DeviceRegistration": {
      "title": "Example extensible registration",
      "description": "The required and optional properties to register and setup devices",
        "pages": [
            {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "title": "Mandatory settings",
                "properties": {
                    "security": {
                      "default": "NO_SEC",
                      "type": "string",
                      "title": "Security mode",
                      "enum": [
                        "NO_SEC",
                        "SEC"
                      ]
                    },
                    "imei": {
                        "examples": [
                            "012345678901234"
                        ],
                        "type": "string",
                        "title": "Imei number"
                    }
                },
                "required": [
                    "imei",
                    "security"
                ]
            },
            {...}
        ]
    }
}

The important part is the pages array which contains steps of the wizard that the modal is going to render accordingly to the JSON Schema definition: https://json-schema.org/.

As a result the following wizard will be displayed:

In the final step all data collected via the wizard will be sent back to the microservice using the following REST endpoint:

POST /service/<contextPath>/deviceRegistration

{
  "imei": "012345678901234",
  "security": "NO_SEC",
  ...
}

The form is able to send anything defined via JSON Schema to the microservice. The Microservice provides the form definition and is responsible for the proper handling of the submitted data.

API specification

The device integration microservices must implement the following REST endpoints:

GET /service/<contextPath>/deviceRegistration/metadata?lang=<user-language>
Accept: application/json

Returns the metadata in the vocabulary of the JSON Schema.

POST /service/<contextPath>/deviceRegistration
Content-type: application/json

Creates a single device based on the collected data. Sends application/json with key-value pairs.

Single device registration flow diagram

The following diagram visualizes the single device registration flow:

Bulk device registration

Many device integrations require the registration of many devices at the same time. Currently, all protocols have to rely on the bulk registration mechanism of the platform, which often either requires too many fields or requires custom fields to be added. The latter ones can however so far not be validated, as the core directly creates devices – and microservices and agents have no control over the properties being written to the managed objects.

After enabling the extensibleBulkDeviceRegistration extension type, the Device management > Devices > Register device Bulk device registration modal is displayed with an extended wizard entry corresponding to the extension name property.

Additionally, the microservice provides the title of the wizard step and example bulk file(s):

{
  "c8y_DeviceRegistration": {
    "title": "<title>",
    "description": "<description>",
    "bulk": {
      "title": "<bulk form title>",
      "exampleFileUrls": [{
        "title": "<example title>",
        "description": "<example description>",
        "url": "<publicly-reachable-URL>"
      }]
    }
  }
}

As a result the following wizard will be displayed:

API specification

The device integration microservices must implement the following REST endpoints:

GET /service/<contextPath>/deviceRegistration/metadata?lang=<user-language>
Accept: application/json

Returns the metadata in the vocabulary of the JSON Schema.

POST /service/<contextPath>/deviceRegistration/bulk`
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name="file"; filename="<input csv file>"
Content-Type: text/csv

--boundary--

Sends multipart form-data of the csv file type.

Bulk flow diagram

The following diagram visualizes the bulk device registration flow:

Limitations

• The concept does not allow the microservice to hook into deregistrations/decommissioning of a device:
  • Any device integration microservice has to check if a device was deleted, for example to perform garbage collection.
• Interactive steps (like “Bluetooth Coupling”) can not be implemented as of now. The reason here is that the concept assumes that only static properties are required for a device registration, not some process that requires user interactions.
  • In theory, the meta-data based approach can easily be extended in a way that the JSON used to render the form is not static, but dynamically generated by the microservice. For example, you could specify a “page” that draws the next specification dynamically from an endpoint after posting all given user inputs there.
  • We step back from such a solution for now, because it complicates the data model and the requirements to be fulfilled by the microservice.
• No custom validations in the UI besides input validations by the JSON Schema vocabulary
• No custom styling possible
• Internationalization is not handled by the UI. As microservice developer it is your responsibility to provide already translated JSON Schema metadata