Building System Integrations with the new Cumulocity IoT Connector for


Every IoT-Project includes some sort of Integration. This can vary in form and complexity. For example, you may use a Microservice to automatically update another system whenever a new Alarm is created. Equally, Integration may take the form of a simple script to do bulk import or export of data. Instead of building complex software solutions to expand your IoT use case, build it with Integration.
This article builds upon Stefan Witschel’s article Data integration options with Cumulocity IoT and dives deeper into System Integration using and our new Cumulocity IoT Connector.
You may also wish to read the article on using the Cumulocity Trigger. Using the new Cumulocity Trigger will provide a good entry point for a Cumulocity IoT Integration.

This Knowledge base Article describes the necessary steps to use the new Cumulocity IoT Connector within Integration and create powerful integrations with it.
Let’s Go!


  • A integration cloud Tenant. Try the free trial!
  • A Cumulocity IoT cloud tenant. Try the free trial!
  • A user with “Application management”-Role in the Cumulocity IoT tenant.


To understand the use and functionality of the new Cumulocity IoT Connector, we’ll start by clarifying some basic information. Let’s start with the fundamentals and use that to build an example integration.

What is Integration? is an iPaaS (Integration Platform as a Service) by Software AG. It bundles the webMethods Suite in a cloud-based platform. Specifically, we are using Integration. It leverages the power of the Integration Server and Lambda-functions to allow businesses to integrate different applications and data sources. With Integration, it’s easy to automate processes, and manage and monitor all integrations from one place.

What does the connector do?

A connector in an iPaaS (Integration Platform as a Service) is a piece of software that enables different systems or applications to communicate and exchange data with each other. It basically functions as a REST-Client to a specific System.
Therefore the new Cumulocity IoT Connector is aware of the Cumulocity REST-Endpoints and their data-format. This enables the platform to perform REST-Requests to a Cumulocity Backend.

How is it Built?

The Connector is built using the Cumulocity OpenApi-File. We use our OpenApi-Generator to generate the Connector-Project. So in the best-case scenario, the Connector should just reflect the Specification of the API in the OpenAPI-File.
Therefore the action names in are taken from the OpenAPI. So it is useful to check with the OpenAPI while building the Integration since the specification includes helpful information about the endpoints.

How does the Connector authenticate with Cumulocity?

The new Cumulocity Connector comes with a custom Authentication Method.

The Authentication is done in 3 steps:

  • Authenticate using basic Auth of a User with “Application Management”-Role.
  • A new Microservice in Cumulocity is created, which has all the roles that the connector needs.
  • A Service user for this microservice is created and then used within the connector for all requests.

:bulb: These Steps are all performed by the Connector itself. So the user only needs to create a Connection using their Cumulocity-user with the “Application Management”-role. :exclamation:

We choose this form of authentication because:

  • The Connection will persist, even when the creating user is deleted or the password is changed.
  • The Connection is manageable. If wanted the microservice can just be deleted and will no longer have a connection to the Cumulocity tenant.

Using the new Cumulocity Connector

After logging in to your Integration and creating a new Workflow or FlowService, the Connector can be used. Just search for “Cumulocity IoT” in the search bar and chose the connector:

Cumulocity IoT Connector

Creating a connection to Cumulocity

The Integration: create an account for a connection to Cumulocity IoT article by Frédéric Joulin provides the necessary explanations about creating a connection in This process can be used for Trigger and Connector and connections are shared between them.

Building a System integration with Integration and Cumulocity IoT

As a demonstration, we will build a small Integration Workflow using the Cumulocity IoT Connector.
The Integration consists of three steps:

    1. Get all critical and active Alarms from Cumulocity.
    1. Loop over the Alarms.
    1. Get the Managed Object for each alarm.

Getting Started

  1. First we will log into our tenant and create a new Project
  1. Create a new Workflow or FlowService
    Now inside our project, we can go ahead and create a new Workflow or FlowService. For this example we will work with a Workflow. Therefore we just click the “new Workflow”-Button.

  2. We want to add the “Cumulocity IoT”-Connector from the Connectors list.


  1. Inside the Connector we will pick our Action and create a connection:

The Connection will look similar to this. Just enter the Server URL of your Cumulocity tenant and your user credentials. The “Cumulocity Application Name” holds the name of the microservice which will be created within your Cumulocity tenant.

After entering all the Details, you can press “Add” and the connection should be added successfully.

  1. Let’s configure the action and test it. Just follow the steps in the animation below.


This run should output some Alarms of our Cumulocity instance.

  1. Looping over all alarms
    Next, we are going to use the Loop Action:


Drag the Action into the workflow and press the settings button on it.
To loop over all Alarms of an Alarm-array we use this mapping:

On the right-hand side, ensure that the loop type is set to “Each Item”. Then drag the Alarms-Array to the “Source Array/Object”-Field. You may need to expand the tree on the left side to be able to see the array.

After finishing the mapping we can press “next”, and then “done” on the following page.
Then go into the loop, by pressing the Loop button on it.
This will open an overlay, that looks the same as a new workflow. Every action in there will be executed for each element in the array.

  1. Getting every Managed Object for the Alarm


The Loop-Overlay should look just like this now. From here you can go ahead and bring in other Systems to integrate your data.

These are just some actions that can be used within for any System Integration. holds a lot of Connectors for a large variety of systems.
Get creative and build your next Integration using the Cumulocity IoT Connector and :wink:

Helpful Tips for working with Integration

When working with there are some small caveats to be aware of, as well as some best practices that can really help you with the creation of good, easy-to-maintain integrations. Here are a few of the most important points to remember:

1. Custom Properties

The Datatype for custom fragments is not fully ui-supported in Integration. Therefore we have to apply a little workaround to use it.
There are two different ways to do it. Both are working with the transformation function within the action mapping.
Just create one of the following transformations:


This transformation makes use of the “JSON-Parse” Transform-step. The custom fragment can be entered as a JSON string and will be parsed to an IntegrationServer-Doctype.

Node.js Object export:

This is the same transformation as above, it just uses the Node.js transformation step. The custom Object needs to be defined within Node.js.

Either one of the Outputs of the transformation step can then just be mapped to the custom fragment field within the mapping view of the action like this:

2. Cumulocity as Trigger for the Integration

We expanded the Cumulocity IoT Connector capabilities by also building a Trigger. More information on the Trigger and how it can be included within an Integration can be found in this article.

3. Test Button

Always make sure to press the “Test”-Button on the last page of a Action-Configuration to test the Action execution. This will show you the output of a test run and also gives you the ability to use the output of this test run for the mapping in other actions.

Next steps

Try it out. :slight_smile:
Feel free to create any integration you want and let us know about it. We are always looking for areas where we can make improvements, and use cases that can benefit from this work.
A free tenant for can be claimed here.