Data model

Input streams

General structure

All input streams share the same base structure.

Types:

For simpler access you can receive the payload directly in the data type of the respective stream by accessing it via an API specific parameter:

ManagedObject

class: com.cumulocity.model.ManagedObject

The Object[] for the references to the parents and children contains only IDs. You can use the cast function e.g. cast(event.managedObject.childAssets[0], com.cumulocity.model.ID).

Example:

select
  event.managedObject.id,
  event.managedObject.type,
  event.managedObject.name,
  event.managedObject.lastUpdated,
  event.managedObject.owner,
  event.managedObject.childAssets,
  event.managedObject.assetParents,
  event.managedObject.deviceParents,
  event.managedObject.childDevices
from ManagedObjectCreated event;

Event

class: com.cumulocity.model.event.Event

Example:

select
  event.event.id,
  event.event.creationTime,
  event.event.type,
  event.event.text,
  event.event.time,
  event.event.source
from EventCreated event;

Measurement

class: com.cumulocity.model.measurement.Measurement

Example:

select
  event.measurement.id,
  event.measurement.type,
  event.measurement.time,
  event.measurement.source
from MeasurementCreated event;

Operation

class: com.cumulocity.model.operation.Operation

Example:

select
  event.operation.id,
  event.operation.creationTime,
  event.operation.status,
  event.operation.deviceId
from OperationCreated event;

Alarm

class: com.cumulocity.model.event.Alarm

Example:

select
  event.alarm.id,
  event.alarm.creationTime,
  event.alarm.type,
  event.alarm.count,
  event.alarm.severity,
  event.alarm.status,
  event.alarm.text,
  event.alarm.time,
  event.alarm.source
from AlarmCreated event;

Response received

Example:

select
  event.status,
  event.body,
  event.creationTime,
  getString(event.source, 'id.value') as source
from ResponseReceived event;   

Output streams

General structure

Output streams contain the possibility to CREATE, UPDATE and DELETE data in Cumulocity IoT. When updating or deleting data it is necessary to provide the ID of the object that will be updated or deleted. When creating data, Cumulocity IoT will generate an ID if not set in the event processing. The creation of data also requires certain parameters to be set (the same as at our REST APIs). In addition to the predefined parameters listed, it is possible to add any custom fragment to the data. Please take a look at the custom fragments section for adding custom fragments.

Note: Creating your own ID will only work on ManagedObjects.

ManagedObjects

Example:

insert into CreateManagedObject
select
  "myManagedObject" as name,
  "myType" as type
from EventCreated event;

insert into UpdateManagedObject
select
  "12345" as id,
  "myNewManagedObject" as name
from EventCreated event;

insert into DeleteManagedObject
select
  "12345" as id
from EventCreated event;

Events

Example:

insert into CreateEvent
select
  "copiedEventType" as type,
  "This event was copied" as text,
  event.event.time as time,
  event.event.source as source
from EventCreated event;

insert into DeleteEvent
select
  "12345" as id
from EventCreated event;

Measurements

Example:

insert into CreateMeasurement
select
  "c8y_TemperatureMeasurement" as type,
  event.event.time as time,
  event.event.source as source,
  {
    "c8y_TemperatureMeasurement.T.value", 5
  } as fragments
from EventCreated event;

insert into DeleteMeasurement
select
  "12345" as id
from EventCreated event;

Operations

Example:

insert into CreateOperation
select
  OperationStatus.PENDING as status,
  event.event.source as deviceId,
  {
    "c8y_Restart", {}
  } as fragments
from EventCreated event;

insert into UpdateOperation
select
  "12345" as id,
  OperationStatus.EXECUTING as status
from EventCreated event;

Alarms

Example:

insert into CreateAlarm
select
  "c8y_HighTemperatureAlarm" as type,
  event.event.time as time,
  event.event.source as source,
  CumulocitySeverities.WARNING as severity,
  CumulocityAlarmStatuses.ACTIVE as status,
  "The device has high temperature" as text
from EventCreated event;

insert into UpdateAlarmn
select
  "12345" as id,
  CumulocityAlarmStatuses.ACKNOWLEDGED as status
from EventCreated event;

Special streams

The streams mentioned in this section do not interact with the Cumulocity IoT database but will create calls to external services.

SendMail

It is possible to have more than one mail address in the parameters receiver,cc and bcc. Therefore create a string that contains all mail addresses separated by commas. “receiver1@mail.com,receiver2@mail.com”.

Example:

insert into SendEmail
select
  "receiver1@cumulocity.com,receiver2@cumulocity.com" as receiver,
  "cc@cumulocity.com" as cc,
  "bcc@cumulocity.com" as bcc,
  "reply@cumulocity.com" as replyTo,
  "Example mail" as subject,
  "This mail was sent to test the SendEmail stream in Cumulocity" as text
from AlarmCreated;

SendSms

It is possible to have more than one phone number in the parameter receiver. Therefore create a string that contains all phone numbers separated by commas e.g. “+49123456789,+49987654321”. Although it is technically not required by Cumulocity IoT to have the country code we recommend you to use it because the sms gateway might require it. You can use the notation like e.g. “0049” or “+49” (for Germany).

Note:

This feature will only work if your tenant is linked to a sms provider. For more information please contact product support.

Example:

insert into SendSms
select
  "+49123456789" as receiver,
  "This sms was sent to test the SendSms stream in Cumulocity" as text,
  "12345" as deviceId
from AlarmCreated;

SendPush

This stream enables the possibility to send push notifications from Cumulocity IoT via the Telekom push service to mobile applications.

Note:

This feature will only work if your tenant is linked to a push provider. For more information please contact product support.

Example:

insert into SendPush
select
"TELEKOM" as type,
"sample push message" as message,
a.alarm.source.value as deviceId
from AlarmCreated a;

SendRequest

This stream enables the possibility to send HTTP requests from Cumulocity IoT to external systems.

Example:

insert into SendRequest
select
  'post' as method,
  'http://some.external.service.com' as url,
  'application/json' as contentType,
  toJSON(m.payload) as body,
  m.payload as source
from MeasurementCreated m

SendExport

This stream enables the possibility to generate export.

Example:

insert into SendExport
select
    'configurationExportId' as enabledSources,
    'subject' as subject,
    'text' as text,
    'receiver@example.com' as receiver
from
    pattern [every timer:at(5, *, *, *, *)]

Additional data models

ID

class: com.cumulocity.model.ID

Example:

select
  event.measurement.source.value,
  event.measurement.source.type,
  event.measurement.source.name
from MeasurementCreated event;

OperationStatus

class: com.cumulocity.model.operation.OperationStatus

OperationStatus is an enum offering the following values: PENDING, SUCCESSFUL, FAILED, EXECUTING

Example:

insert into UpdateOperation
select
  event.operation.id.value as id,
  OperationStatus.FAILED as status
from OperationCreated event;

Severity

class: com.cumulocity.model.event.Severity

Severity is the interface for the enum implementation CumulocitySeverities. CumulocitySeverities offers the following values: CRITICAL, MAJOR, MINOR, WARNING

Example:

insert into UpdateAlarm
select
  event.alarm.id.value as id,
  CumulocitySeverities.MAJOR as severity
from AlarmCreated event;

AlarmStatus

class: com.cumulocity.model.event.AlarmStatus

AlarmStatus is the interface for the enum implementation CumulocityAlarmStatuses. CumulocityAlarmStatuses offers the following values: ACTIVE, ACKNOWLEDGED, CLEARED

Example:

insert into UpdateAlarm
select
  event.alarm.id.value as id,
  CumulocityAlarmStatuses.ACKNOWLEDGED as status
from AlarmCreated event;