Data model

Input streams

General structure

All input streams share the same base structure.

Parameter Data type Description
_type String The type of the event. See the table below which value types can be used for different streams.
_mode String The processing mode in which the data was sent to Cumulocity. See Processing mode.
_origin String The origin of the event. If the data was created by a cep rule the origin will be “cep”.
payload Object The actual data contained in the event

Types:

Stream Type
ManagedObjectCreated MANAGED_OBJECT_CREATE
ManagedObjectUpdated MANAGED_OBJECT_UPDATE
ManagedObjectDeleted MANAGED_OBJECT_DELETE
EventCreated EVENT_CREATE
EventUpdated EVENT_UPDATED
EventDeleted EVENT_DELETE
MeasurementCreated MEASUREMENT_CREATE
MeasurementDeleted MEASUREMENT_DELETE
OperationCreated OPERATION_CREATE
OperationUpdated OPERATION_UPDATE
AlarmCreated ALARM_CREATE
AlarmUpdated ALARM_UPDATE
ResponseReceived REQUEST_RESULT

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:

API Parameter Data type
Inventory managedObject ManagedObject
Events event Event
Measurements measurement Measurement
Device control operation Operation
Alarms alarm Alarm

ManagedObject

class: com.cumulocity.model.ManagedObject

|Parameter|Data type|Description| |:–|:———-|:————-|:———-| |id|ID|ID of the ManagedObject| |type|String|The type of the ManagedObject| |name|String|The name of the ManagedObject| |lastUpdated|Date|The time when the ManagedObject was last updated| |owner|String|The owner of the ManagedObject| |childAssets|Object[]|An array of the IDs of all child assets| |childDevices|Object[]|An array of the IDs of all child devices| |assetParents|Object[]|An array of the IDs of all parent assets| |deviceParents|Object[]|An array of the IDs of all child devices|

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

|Parameter|Data type|Description| |:–|:———-|:————-|:———-| |id|ID|The ID of the Event| |creationTime|Date|The time when the Event was created in the database| |type|String|The type of the Event| |text|String|The text of the Event| |time|Date|The time when the Event was created (as sent by device)| |source|ID|The ID of the device which created the 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

|Parameter|Data type|Description| |:–|:———-|:————-|:———-| |id|ID|The ID of the Measurement| |type|String|The type of the Measurement| |time|Date|The time when the Measurement was created (as sent by device)| |source|ID|The ID of the device which created the 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

|Parameter|Data type|Description| |:–|:———-|:————-|:———-| |id|ID|The ID of the Operation| |creationTime|Date|The time when the Operation was created in the database| |status|OperationStatus|The current status of the Operation| |deviceId|ID|The ID of the device which should execute the 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

|Parameter|Data type|Description| |:–|:———-|:————-|:———-| |id|ID|The ID of the Alarm| |creationTime|Date|The time when the Alarm was created in the database| |type|String|The type of the Alarm| |count|long|The number of times the alarm was reported while active| |severity|Severity|The severity of the Alarm| |status|AlarmStatus|The status of the Alarm| |text|String|The text of the Event| |time|Date|The time when the Event was created (as sent by device)| |source|ID|The ID of the device which created the 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

|Parameter|Data type|Description| |:–|:———-|:————-|:———-| |status|Integer|Http response status| |body|String|Http response body| |creationTime|Date|The time when the response was created| |source|Object|Source set in SendRequest output stream|

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. 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 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

|Available outputs| |:-| |CreateManagedObject| |UpdateManagedObject| |DeleteManagedObject|

Parameter Data type Description Mandatory
id ID or String ID of the ManagedObject UPDATE and DELETE
type String The type of the ManagedObject No
name String The name of the ManagedObject No
owner String The owner of the ManagedObject. If not set data created from event processing will have the owner “cep” No
childAssets Set<String> or Set<ID> A set of IDs of all child assets No
childDevices Set<String> or Set<ID> A set of IDs of all child devices No

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

Available outputs
CreateEvent
EventUpdated
DeleteEvent
Parameter Data type Description Mandatory
id ID or String The ID of the Event DELETE
type String The type of the Event CREATE
text String The text of the Event CREATE
time Date The time when the Event was created (as sent by device) CREATE
source ID or String The ID of the device which created the Event CREATE

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

Available outputs
CreateMeasurement
DeleteMeasurement
Parameter Data type Description Mandatory
id ID or String The ID of the Measurement DELETE
type String The type of the Measurement CREATE
time Date The time when the Measurement was created (as sent by device) CREATE
source ID or String The ID of the device which created the Measurement CREATE

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

Available outputs
CreateOperation
UpdateOperation
Parameter Data type Description Mandatory
id ID or String The ID of the Operation UPDATE
status OperationStatus or String The current status of the Operation CREATE
deviceId ID or String The ID of the device which should execute the Operation CREATE

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

Available outputs
CreateAlarm
UpdateAlarm
Parameter Data type Description Mandatory
id ID or String The ID of the Alarm UPDATE
type String The type of the Alarm CREATE
severity Severity or String The severity of the Alarm CREATE
status AlarmStatus or String The status of the Alarm CREATE
text String The text of the Event CREATE
time Date The time when the Event was created (as sent by device) CREATE
source ID or String The ID of the device which created the Alarm CREATE

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 database but will create calls to external services.

SendMail

Parameter Data type Description Mandatory
receiver String The mail address of the receiver yes
cc String The mail address of the cc no
bcc String The mail address of the bcc no
replyTo String The mail address which should receive replies to the sent mail yes
subject String The subject line of the mail yes
text String The body of the mail yes

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

Parameter Data type Description Mandatory
receiver String The phone number of the receiver yes
text String The body of the sms. Max. 160 characters yes
deviceId String The ID of the device generating the sms. A log event will be created for the device no

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 to have the country code we recommend using 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 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 via the Telekom push service to mobile applications.

Parameter Data type Description Mandatory
type String Push Provider Type. Currently only TELEKOM is possible. yes
message String The body of the push message. yes
deviceId String The ID of the device generating the push message. yes

Note:

This feature will only work if your tenant is linked to a push provider. For more information please contact 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 to external systems.

Parameter Data type Description Mandatory
url String Url of external system yes
method String Method of HTTP request yes
body String Body of HTTP reqeust no
authorization String HTTP Authorization header no
contentType String HTTP Content-Type header no
headers Map HTTP headers no
source Object Represents object which will be passed to ResponseReceived input stream no

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.

Parameter Data type Description Mandatory
enabledSources List Export configuration ids true
subject String Subject of email false
text String Text of email. Available placeholders: {host}, {binaryId}. Default message is: “File with exported data can be downloaded from {host}/inventory/binaries/{binaryId}” false
receiver String Receiver of email false

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

|Parameter|Data type|Description| |:–|:———-|:————-|:———-| |value|String|The actual ID value| |type|String|The type of the ID| |name|String|The name of the device (only if the ID refers to a device like in measurement.source)|

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;