Topics¶

Topic structure¶

All topics must use this structure. When a level is not applicable, this level must be replaced by -:

1/2/3/4/5/6...n

Level	Description
1	Module name
2	Principal. By default it is interpreted as business partner ID. For system providers prefix the ID with `sp-`, for system distributors with `sd-`. I. e. `sp-f0eef712-234f-4d4c-aa89-ae1bd39239c0` or `sd-ec12fae1-dacf-4e6f-bd15-aafce92cfe45`. You can pass an asterisk (``) instead of the ID if the topic is for all principals of that level. E. g. (`sp-`).
3	Administration unit ID
4	`spu` (for system provider user), `sdu` (for system distributor user), `bpu` (for business partner user) or `eu` (for enduser)
5	User ID
6 to n	Custom topic levels

For example:

c1-core/48109350-1db6-11e9-8e66-2f71a0be4cc5/71.1000.103.2.1/spu/0604b020-7905-11eb-ad7b-f9e2c6c59018/...

If there is no associated administration unit:

c1-core/48109350-1db6-11e9-8e66-2f71a0be4cc5/-/spu/0604b020-7905-11eb-ad7b-f9e2c6c59018/...

If there is no associated user:

c1-core/48109350-1db6-11e9-8e66-2f71a0be4cc5/71.1000.103.2.1/-/-/...

Available topics¶

The following topics are available:

Payload¶

The payload must be in JSON format and it must be an object. Apart from that there are no restrictions.

Verified information¶

The modules and C1 Core add a key named verifiedData to the JSON objects. verifiedData includes all relevant fields, the data is associated to. The module adding this information must make sure, it is correct. verifiedData must only be added by trusted modules. Like this you can rely on this information and can use it for ACL checks. An example verifiedData object might look like this:

"verifiedData": {
    "time": <Unix epoch time in ms (UTC)>,
    "sp": "<system provider ID>",
    "sd": "<system distributor ID>",
    "bp": "<business partner ID>",
    "au": "<full administration unit ID>",
    "homeClientAu": "<full administration unit ID of edge client>",
    "userType": "sp" | "sd" | "bp" | "eu",
    "userId": "user ID",
    "nodeName": "<node name>"
}

homeClientAu contains the administration unit ID of the edge client. It differs from au in some cases. au always starts with homeClientAu though, i. e. it can only be the same or hierarchically below homeClientAu (an edge client can not and is not allowed to generate events for another edge client). It differs for example when there is only one edge client for the whole economic unit but the event is for a building or apartment.

nodeName is set to the host's name of the module connected to C1 Core.

C1 Core¶

User administration unit association¶

Topic¶

c1-core/<business partner ID>/<full administration unit ID>/eu/<enduser ID>/association

Description¶

Called whenever an end user is associated to or unassociated from an administration unit.

Payload¶

{
    "verifiedData": ...,
    "event": "association" | "unassociation",
    "userId": "{enduser ID}"
}

Change to economic unit, property or administration unit address¶

Topic¶

c1-core/<business partner ID>/<full location ID>/address

Description¶

Called whenever the address of the economic unit, property or administration unit has changed.

Payload¶

{
    "verifiedData": ...,
    "street": "{street}", //Only for properties or administration units
    "streetNumber": "{streetNumber}", //Only for properties or administration units
    "zip": "{zip}",
    "city": "{city}",
    "country": "{country}"
}

Edge clients¶

Telemetry¶

Topics¶

(1) c1-home/<business partner ID>/<administration unit ID>/-/-/<sub ID>/telemetry/device/<peer ID>/<channel>/<data point ID>
(2) c1-home/<business partner ID>/<administration unit ID>/-/-/<sub ID>/telemetry/interface/<interface ID>/<data point ID>
(3) c1-home/<business partner ID>/<administration unit ID>/-/-/<sub ID>/telemetry/system/<data point ID>

Description¶

(1) is called whenever a data point of an actual device connected to the edge client is updated. (2) is called on updates of the communication interfaces the devices are connected to. (3) is called on system updates.

Note

The topic part c1-home/<business partner ID>/<administration unit ID>/-/-/<sub ID>/ is prepended in C1 Proxy so it cannot be forged. I. e. this can be treated as verified information.

Note

Always use the time stored in the JSON object. There might be huge latencies or you might receive a cached value, so you cannot use the reception time.

Payload¶

{
    "verifiedData": ...,
    "time": <time of event generation>
    "value": <actual value>
}

Service messages from edge clients¶

Topic¶

c1-home/<business partner ID>/<administration unit ID>/-/-/<sub ID>/service-message

Description¶

Called when a service message is generated or deleted.

Note

The topic part c1-home/<business partner ID>/<administration unit ID>/-/-/<sub ID>/ is prepended in C1 Proxy so it cannot be forged. I. e. this can be treated as verified information.

Payload¶

There is always a property named type present depending on the value of type there are different properties available. type can be global, family or device.

Type "global"¶

Global service messages are not associated to a device or a communication interface. They are associated to the whole edge client instance, i. e. the whole gateway.

{
    "verifiedData": ...,
    "type": "global",
    "message": {"en-US": "<message>", "en": "<message>", "de-DE": "<message>", "de-AT": "<message>", "de": "<message>", ...},
    "active": true | false,
    "timestamp": <unix epoch time in seconds>,
    "priority": <priority>,
    "messageId": "<message ID>"
}

Property	Type	Description
`message`	Object	Contains all available message translations. Fall back language is `en`, so this translation is always present.
`active`	Boolean	`true` means the service message is active, `false` means, it should be removed.
`timestamp`	Number	The time the service message was generated in seconds.
`priority`	Number	The priority of the service message. `1` for critical, `2` for error, `3` for warning and `4` for info.
`messageId`	String	A unique service message ID. Every service message type gets it's own ID. When a service message with an existing ID arrives, the old service message should be overridden.
`data`	Variant	Optional additional data associated with the service message.

Type "family"¶

Family service messages are associated to a device family. When interface is set, they are associated to a communication interface.

{
    "verifiedData": ...,
    "type": "family",
    "message": {"en-US": "<message>", "en": "<message>", "de-DE": "<message>", "de-AT": "<message>", "de": "<message>", ...},
    "active": true | false,
    "timestamp": <unix epoch time in seconds>,
    "priority": <priority>,
    "messageId": "<message ID>",
    "familyId": <family ID>,
    "interface": "<interface ID>"
}

Property	Type	Description
`message`	Object	Contains all available message translations. Fallback language is `en`, so this translation is always present.
`active`	Boolean	`true` means the service message is active, `false` means, it should be removed.
`timestamp`	Number	The time the service message was generated in seconds.
`priority`	Number	The priority of the service message. `1` for critical, `2` for error, `3` for warning and `4` for info.
`messageId`	String	A unique service message ID. Every service message type gets it's own ID. When a service message with an existing ID arrives, the old service message should be overridden.
`familyId`	Number	The ID of the device family the service message is associated to.
`interface`	String	The interface the service message is associated to.

Type "device"¶

Device service messages are associated to a specific. When interface is set, they are associated to a communication interface.

{
    "verifiedData": ...,
    "type": "device",
    "message": {"en-US": "<message>", "en": "<message>", "de-DE": "<message>", "de-AT": "<message>", "de": "<message>", ...},
    "active": true | false,
    "timestamp": <unix epoch time in seconds>,
    "priority": <priority>,
    "messageId": "<message ID>",
    "peerId": <peer ID>,
    "channel": <channel>,
    "variable": "<variable>"
}

Property	Type	Description
`message`	Object	Contains all available message translations. Fallback language is `en`, so this translation is always present.
`active`	Boolean	`true` means the service message is active, `false` means, it should be removed.
`timestamp`	Number	The time the service message was generated in seconds.
`priority`	Number	The priority of the service message. `1` for critical, `2` for error, `3` for warning and `4` for info.
`messageId`	String	A unique service message ID. Every service message type gets it's own ID. When a service message with an existing ID arrives, the old service message should be overridden.
`peerId`	Number	The ID of the device the service message is associated to.
`channel`	Number	The channel of the device the service message is associated to.
`variable`	String	The data point the service message is associated to.

All modules¶

Service messages¶

Topic¶

<module ID>/<business partner ID>/-/-/-/-/service-message

Description¶

Called when a service message is generated or deleted by an Sensaru Cloud module.

Note

The topic part <module ID>/ must match the module's ID as specified in the client certificate. Otherwise the RPC call will be rejected by C1 Core.

Payload¶

{
    "verifiedData": ...,
    "id": "<service message UUID>"
    "message": {"en-US": "<message>", "en": "<message>", "de-DE": "<message>", "de-AT": "<message>", "de": "<message>", ...},
    "active": true | false,
    "timestamp": <unix epoch time in milliseconds>,
    "priority": <priority>,
    "header": "<header>",
    "footer": "<footer>",
    "entityId": "<entity ID>",
    "locationId": "<location ID>",
    "roles": [<role 1>, <role 2>, ...],
    "url": "<url>"
}

Property	Type	Description
`id`	String	The UUID of the service message.
`message`	Object	Contains all available message translations. Fallback language is `en`, so this translation is always present.
`active`	Boolean	`true` means the service message is active, `false` means, it should be removed.
`timestamp`	Number	The time the service message was generated in milliseconds.
`priority`	Number	The priority of the service message. `1` for critical, `2` for error, `3` for warning and `4` for info.
`header`	String	A line describing the entity the service message is associated to. E. g. the name of the device.
`footer`	String	A line further describing the entity the service message is associated to. E. g. the address.
`entityId`	String	An ID identifying the entity that triggered the service message, e. g. the ERP system ID of the device.
`roles`	Array[Integer]	Only applicable for service messages for edge devices. The array contains the roles of the device or data point.
`url`	String	The URL for the detailed service message view. This URL is opened within an iframe next to the service message.

Telemetry¶

Topic¶

<module ID>/sp-*/-/-/-/<server>/service-telemetry/<data-point>

Description¶

Called whenever a service telemetry data point is updated.