Introducing the Cumulocity IoT Source Transformer Microservice: Simplifying IoT Data Interactions

Knowledge base
, , ,
1

The world of IoT is complex and intricate, made more so by the need to handle and transform data effectively and efficiently. Bridging this gap is the Cumulocity Source Transformer Microservice. This project offers a solution to send measurements, events, and alarms to the Cumulocity APIs without the need to know the internalID, presenting a simplified approach to data handling in the IoT realm.

A Powerful Microservice

The Cumulocity Source Transformer Microservice opens its own service endpoint that requires the externalId and the externalId type for POST requests. Once these parameters are added, the microservicetransforms the Event/Alarm/Measurement, subsequently handing it over to the genuine Cumulocity API.

This microservice is not just a single block of code, but a constellation of modules working together to create a seamless experience:

  • main.py: The main runtime that opens a health endpoint and creates the rest endpoints.
  • API/authentication.py: Handles service user requests via the bootstrap user within the microservice environment.
  • API/inventory.py: Provides the internalId of the device from the externalId and the externalId type.
  • API/measurments.py: Creates the measurement from the payload and sends it to Cumulocity.
  • API/events.py: Creates the events from the payload and sends it to Cumulocity.
  • API/alarms.py: Creates the alarm from the payload and sends it to Cumulocity.
  • resources/base.py: This base class of the request extracts the externalId and the externalId type from the POST request, queries the internalId, and replaces the {"source": {"id": "internalID"} } within the JSON body of the POST request.

Note: The Debug Level is set to INFO by default, but this can be easily adjusted within main.py to suit user requirements.

How to Use

The Cumulocity Source Transformer Microservice allows measurements, alarms, or events to be sent by adding “type” and “externalId” as parameters to the POST request.

Due to this intermediate service, no further inventory role filtering occurs, allowing a device that can reach the service endpoint to write to any device.

Quick Start and Installation

A quick start to this microservice is as easy as using the provided zip in the release and uploading it as a microservice. If you prefer to start from scratch, the instructions to build the microservice are included in the repository, with Docker being the primary tool used for building.

To learn more about this transformative microservice, ask a question in the Tech Community Forums or explore additional information in the Software AG Tech Community. Join the community of innovators and enthusiasts as we journey towards a more efficient and effective IoT world.

Feedback and Ideas

  • If you find any bug, please raise an issue directly in the GitHub repository.
  • Please, feel free to share feedback and ideas by posting a reply here.

Want to help us improve the code? Check out our GitHub - SoftwareAG/contributing repository first.

Useful links

2 Likes
2

Great stuff! A few thoughts:

  • You could add at least the basic global custom roles for each bucket to your manifest so you can check if a user has a permission assigned for global roles or even more easier…
  • instead of using the service user you could use the request user with its permission to perform the request. So if you use a device_user which is the owner of one device you can update only that but no other and you can skip the whole permission implementation stuff in your microservice.