Inventory
The inventory has the possibility to store binaries also the API below is not published in “/inventory”.
The inventory has the possibility to store binaries also the API below is not published in “/inventory”.
The inventory interface consists of the following parts:
Info: For all PUT/POST requests an accept header should be provided, otherwise an empty response body will be returned.
Name | Type | Occurs | Description |
---|---|---|---|
self | URL | 1 | Link to this resource. |
managedObjects | ManagedObjectCollection | 1 | Collection of all managed objects. |
managedObjectsForType | ManagedObjectCollection URI-Template | 1 | Read-only collection of all managed objects of a particular type (placeholder {type}). |
managedObjectsForFragmentType | ManagedObjectCollection URI-Template | 1 | Read-only collection of all managed objects with a particular fragment type or capability (placeholder {fragmentType}). |
managedObjectsForListOfIds | ManagedObjectCollection URI-Template | 1 | Read-only collection of managed objects fetched for a given list of ids (placeholder {ids}),for example “?ids=41,43,68”. |
managedObjectsForText | ManagedObjectCollection URI-Template | 1 | Read-only collection of managed objects containing a text value starting with the given text (placeholder {text}). Text value is any alphanumeric string starting with a latin letter (A-Z or a-z). |
Response body: application/vnd.com.nsn.cumulocity.inventoryApi+json
Required role: ROLE_INVENTORY_READ
HEADERS | |
---|---|
Authorization | {{auth}} |
200 - OK
GET <<url>>/inventory
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.inventoryapi+json;ver=… |
HTTP/1.1
200 - OK
{
"managedObjectsForFragmentType" : "<<ManagedObjectCollection URL>>?fragmentType={fragmentType}",
"managedObjectsForType" : "<<ManagedObjectCollection URL>>?type={type}",
"self" : "<<InventoryAPI URL>>",
"managedObjects" : {
"self" : "<<ManagedObjectCollection URL>>",
"references": []
},
"managedObjectsForListOfIds" : "<<ManagedObjectCollection URL>>?ids={ids}"
}
Name | Type | Occurs | Description |
---|---|---|---|
self | URI | 1 | Link to this resource. |
managedObjects | ManagedObject | 0..n | List of managed objects, see below. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | URI | 0..1 | Link to a potential previous page of managed objects. |
next | URI | 0..1 | Link to a potential next page of managed objects. |
Response body: ManagedObjectCollection
Required role: ROLE_INVENTORY_READ
HEADERS | |
---|---|
Authorization | {{auth}} |
GET <<url>>/inventory/managedObjects
Accept: application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=...
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=… |
HTTP/1.1
200 OK
{
"self" : "<<Collection URL>>",
"managedObjects" : [
{
"self" : "<<Object 42 URL>>",
"id" : "42",
"type" :"bg_mps_D413",
"name" : "Meter1",
...
},
{
"self" : "<<Object 43 URL>>",
"id": "43",
"type" :"bg_mps_D413",
"name": "Meter2",
...
}
],
"statistics" : {
"totalPages" : 42,
"pageSize" : 5,
"currentPage : 1
}, "next" : "...", "prev" : "..."}
Response body: ManagedObjectCollection
Required role: ROLE_INVENTORY_READ
HEADERS | |
---|---|
Authorization | {{auth}} |
200 - OK
GET <<url>>/inventory/managedObjects?query=<<query language statement>>
Accept: application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=...
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=.. |
HTTP/1.1
200 OK
Content-Type: application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=...
Content-Length: ...
{
"self" : "<<Collection URL>>",
"managedObjects" : [
{
"self" : "<<Object 42 URL>>",
"id" : "42",
"type" :"bg_mps_D413",
"name" : "Meter1",
...
},
{
"self" : "<<Object 43 URL>>",
"id": "43",
"type" :"bg_mps_D413",
"name": "Meter2",
...
}
],
"statistics" : {
"totalPages" : 42,
"pageSize" : 5,
"currentPage : 1
}, "next" : "...", "prev" : "..."}
Query language is applied to all managed objects.
This part explains, how an application will handle a query in parameter ‘query’.
has: has(c8y_IsDevice) - match objects with custom property c8y_IsDevice
Supports only custom fragments.
bygroupid(12) - match objects from group with ID equals 12
{
"_id": 1,
"name": "Dev_001",
"num": 1,
"c8y_Availability": {
"statusId": 1
}
},
{
"_id": 2,
"name": "Dev_002",
"num": 2,
"c8y_Availability": {
"statusId": 1
}
},
{
"_id": 3,
"name": "Mo_003",
"num": 3,
"c8y_Availability": {
"statusId": 2
}
},
{
"_id": 4,
"name": "Mo_004",
"num": 4,
"c8y_Availability": {
"statusId": 2
}
}
...query=num eq 1 - {"_id": 1, ...}
...query=name eq 'Dev_002' - {"_id": 2, ...}
...query=name eq '*00*' - return all 4 rows
...query=name eq '*Dev_001*' - {"_id": 1, ...}
...query=c8y_Availability.statusId eq 2 - {"_id": 3, ...}, {"_id": 4, ...}
...query=num gt 2 - {"_id": 3, ...}, {"_id": 4, ...}
...query=num le 2 - {"_id": 1, ...}, {"_id": 2, ...}
...query=num eq 1 or num eq 2 - {"_id": 1, ...}, {"_id": 2, ...}
...query=has(c8y_Availability) - return all 4 rows
Name | Type | Occurs | Description | PUT/POST |
---|---|---|---|---|
id | String | 1 | Unique identifier of the object, automatically allocated when the object is created (see above). | No |
self | URL | 1 | Link to this resource. | No |
type | String | 0..1 | The most specific type of the managed object as fully qualified Java-style type name, dots replaced by underscores. | Optional |
name | String | 0..1 | Human-readable name that is used for representing the object in user interfaces. | Optional |
* | Object | 0..n | Additional properties associated with the specific ManagedObject. | Optional |
creationDate | TimeStamp | 1 | The time when the object has been created. | POST only |
lastUpdated | TimeStamp | 1 | The time when the object was last updated. | No |
childDevices | ManagedObject ReferenceCollection | 0..1 | A collection of references to child devices. | No |
childAdditions | ManagedObject ReferenceCollection | 0..1 | A collection of references to child additions. | No |
childAssets | ManagedObject ReferenceCollection | 0..1 | A collection of references to child assets. | No |
deviceParents | ManagedObject ReferenceCollection | 0..1 | A collection of references to device parent objects. Note: GET to /inventory/managedObjects/{{deviceId}}/deviceParents is not implemented. | No |
assetParents | ManagedObject ReferenceCollection | 0..1 | A collection of references to asset parent objects. Note: GET to /inventory/managedObjects/{{deviceId}}/assetParents is not implemented. | No |
statusChangeDate | ManagedObjectReferenceCollection | 0..1 | The property is updated when the tenant status is modified. The value cannot be modified, it can only be viewed. | No |
It is recommended for property names not to start with “child” or “parent”. This way you will be able to handle other types of references.
A managed object reference in the “child” and “parents” collections contains only id
, name
and self
properties.
Not every GET response contains “parents” collections. It is required to pass withParents=true
query param to have “parents” included. If you query the managed object withParent=true
it will return a flat list of all parents and grandparents of the given object.
Info: If you query
childDevices
, only the children of the given device are returned without any grandchildren.
Response body: ManagedObject
Required role: ROLE_INVENTORY_READ
HEADERS | |
---|---|
Authorization | {{auth}} |
200 - OK
GET <<url>>/inventory/managedObjects/<<deviceId>>
Accept: application/vnd.com.nsn.cumulocity.managedObject+json;=ver...
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedObject+json;ver=… |
HTTP/1.1
200 - OK
{
"id" : "42",
"name" : "SomeName",
"self" : "<<This ManagedObject URL>>",
"type" :"com_nsn_cumulocity_example_Clazz",
"lastUpdated": "2012-05-02T19:48:40.006+02:00",
"com_othercompany_StrongTypedClass" : { ... },
"childDevices": {
"self" : "<<ManagedObjectReferenceCollection URL>>",
"references" : [
{
"self" : "<<ManagedObjectReference URL>>",
"managedObject": {
"id": "1",
"self" : "<<ManagedObject URL>>"
"name": "Some Child"
}
},
...
]
},
...
}
Info: Parents of the ManagedObject are always empty unless a flag “withParents” is specified.
Request body: ManagedObject
Response body: ManagedObject (when accept header is not provided, empty response body is returned)
Required role: ROLE_INVENTORY_ADMIN or ROLE_INVENTORY_CREATE
HEADERS | |
---|---|
Authorization | {{auth}} |
Content-Type | application/vnd.com.nsn.cumulocity.managedObject+json;ver=… |
Accept | application/vnd.com.nsn.cumulocity.managedObject+json;ver=… |
POST <<url>>/inventory/managedObjects
{
"name" : "A brand new switch",
"com_cumulocity_model_BinarySwitch" : { "state": "OFF" }
}
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedObject+json;ver=… |
HTTP/1.1
201 - Created
{
"self" : "<<URL of new object>>",
"id" : "111",
"lastUpdated": "2012-04-21T18:03:19.932+02:00",
"name" : "A brand new switch",
"com_cumulocity_model_BinarySwitch" : {
"state": "OFF" }
...
}
The id
and lastUpdated
of the new managed object are generated by the server and returned in the response to the POST operation.
HEADERS | |
---|---|
Authorization | {{auth}} |
200 - OK
GET <<url>>/inventory/managedObjects/<<deviceId>>/supportedMeasurements
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedObject+json;ver=… |
HTTP/1.1
200 - OK
{
"c8y_SupportedMeasurements": ["c8y_AnalogMeasurement", "c8y_MotionMeasurement", "c8y_SignalStrength", "c8y_TemperatureMeasurement"]
}
Important: In order to have fragment names included in the supported measurements list, the fragment has to have a specific structure:
"fragment_name" : {
"serie_name" : {
"value" : ...
"unit" : ...
}
}
Real example:
"c8y_SpeedMeasurement": {
"Speed": {
"value": 1234,
"unit": "km/h"
}
}
Fragment_name
and serie_name
can be replaced by a different valid json property name, but that name may not contain whitespaces and special characters like [], *. The structure has to be exactly as above, a two-level deep json object.
HEADERS | |
---|---|
Authorization | {{auth}} |
200 - OK
GET <<url>>/inventory/managedObjects/<<deviceId>>/supportedSeries
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedObject+json;ver=… |
HTTP/1.1
200 - OK
{
{"c8y_SupportedSeries":["c8y_TemperatureMeasurement.T","c8y_SpeedMeasurement.speed","c8y_SignalStrength.rssi"]}
}
Important: In order to have fragment names included in the supported series list, the fragment has to have a specific structure. See the explanation above regarding supported measurements.
Request body: ManagedObject
Response body: ManagedObject (when the accept header is not provided, an empty response body is returned)
Required role: ROLE_INVENTORY_ADMIN or owner
HEADERS | |
---|---|
Authorization | {{auth}} |
Accept | application/vnd.com.nsn.cumulocity.managedObject+json;ver=… |
Content-Type | application/vnd.com.nsn.cumulocity.managedObject+json;ver=… |
200 - OK
PUT <<url>>/inventory/managedObjects/<<deviceId>>
{
"name" : "Life, the Universe and the REST"
}
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedObject+json;ver=… |
HTTP/1.1
200 - OK
{
"id" : "42",
"name" : "Life, the Universe and the REST",
"self" : "<<This ManagedObject URL>>",
"type" :"com_nsn_cumulocity_example_Clazz",
"lastUpdated": "2012-05-02T19:58:40.006+02:00",
"com_othercompany_StrongTypedClass" : { ... },
"childDevices": {
...
},
...
}
When a managed object of type c8y_SmartRule
is updated, an audit record is created with type “SmartRule” and activity “Smart rule updated”, “Smart rule enabled” or “Smart rule disabled”.
Request body: N/A
Response message body: N/A
Required role: ROLE_INVENTORY_ADMIN or owner
HEADERS | |
---|---|
Authorization | {{auth}} |
DELETE <<url>>/inventory/managedObjects/<<deviceId>>
HTTP/1.1
204 - NO CONTENT
If the managed object is a device or a group and the optional query parameter “cascade=true” is used, all child devices and child assets will be deleted recursively. By default, the delete operation is propagated to the subgroups only if the deleted object is a group.
Info: Inventory DELETE requests are not synchronous. The response could be returned before the delete request has been completed.
Name | Type | Occurs | Description |
---|---|---|---|
self | URI | 1 | Link to this resource. |
references | ManagedObjectReference | 0..n | List of managed object references, see below. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | URI | 0..1 | Link to a potential previous page of managed objects. |
next | URI | 0..1 | Link to a potential next page of managed objects. |
Response body: ManagedObjectReferenceCollection
HEADERS | |
---|---|
Authorization | {{auth}} |
Info: “404 Not Found” error will appear if the object has no references.
GET <<url>>/inventory/managedObjects/<<deviceId>>/<<references>>
Info: References can be either
childDevices
orchildAssets
.
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedobjectreferencecollection+json;ver=… |
HTTP/1.1
200 - OK
{
"self" : "<<This ManagedObjectReferenceCollection URL>>",
"references" : [
{
"self" : "<<ManagedObjectReference URL>>",
"managedObject" : {
"self" : "<<ManagedObject 1 URL>>",
"name" : "Meter1",
"id" : "1",
...
}
},
{
"self" : "<<ManagedObjectReference URL>>",
"managedObject" : {
"self" : "<<ManagedObject 2 URL>>",
"name" : "Meter2",
"id" : "2",
...
}
}
],
"statistics" : {
"pageSize" : 5,
"currentPage : 1
},
"next": "...",
"prev": "..."
}
Request body: ManagedObjectReference
Response body: ManagedObjectReference
Required role: ROLE_INVENTORY_ADMIN or parent and child owner
HEADERS | |
---|---|
Authorization | {{auth}} |
Content-Type | application/vnd.com.nsn.cumulocity.managedObject+json;ver=… |
POST <<url>>/inventory/managedObjects/<<deviceId>>/<<references>>
{
"managedObject" : { "self" :"<<ManagedObject URL>>" }
}
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedObjectReference+json;ver=… |
HTTP/1.1
201 - Created
{
"self" : "<<This ManagedObjectReference URL>>,
"managedObject" : {
"id" : "2",
"self" : <<ManagedObject 2 URL>>,
"name" : "Meter2",
...
}
}
As an alternative, it is also allowed to pass the following reference object in the request body when adding to the collection:
{
"managedObject" : { "id" :"<<ManagedObject id>>" }
}
Name | Type | Occurs | Description |
---|---|---|---|
self | URI | 1 | Link to this resource. |
managedObject | ManagedObject | 1 | The ManagedObject being referenced. |
Response body: ManagedObjectReference
Required role: ROLE_INVENTORY_READ
HEADERS | |
---|---|
Authorization | {{auth}} |
200 - OK
GET <<url>>/inventory/managedObjects/<<deviceId>>/<<references>>/<<referenceId>>
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.managedObjectReference+json;ver=… |
HTTP/1.1
200 - OK
{
"self" : "<<This ManagedObjectReference URL>>",
"managedObject" : {
"self" : "<<ManagedObject 4 URL>>",
"name" : "Foo",
"id" : "4",
...
}
}
Request body: N/A
Response message body: N/A
Required role: ROLE_INVENTORY_ADMIN or parent owner or child owner
Info: This operations just removes the reference, it does not delete the object itself.
HEADERS | |
---|---|
Authorization | {{auth}} |
DELETE /inventory/managedObjects/<<deviceId>>/<<references>>/<<referenceId>>
HTTP/1.1
204 - NO CONTENT
Inventory notifications permit the monitoring of changes in the inventory (CREATE, UPDATE and DELETE).
The basic protocol for receiving notifications is described in Real-time notifications.
The URL is:
/cep/realtime
The subscription channel must contain the managed object ID of the object in the inventory to be monitored or a “*” as placeholder to receive notifications for the entire inventory.
/managedobjects/<<managedObjectId>>
In addition to the managed object, the response will contain a realtimeAction
to identify which action resulted in the given object (CREATE, UPDATE or DELETE). In case of a deletion the data will only contain the ID of the deleted managed object.
Required role: ROLE_INVENTORY_READ
HEADERS | |
---|---|
Content-Type | application/json |
HTTP/1.1
200 - OK
[
{
"channel": "/managedobjects/12345",
"successful": true,
"error": "",
"data": [{
"realtimeAction": "UPDATE",
"data": {
"id": "12345",
"self": "...",
"creationTime": "2011-09-06T12:03:27.927+02:00",
"name": "a device",
"c8y_IsDevice": {},
"c8y_Location": { ... }
}
}],
"clientId": "Un1q31d3nt1f13r"
}
]