Inventory

The inventory has the possibility to store binaries also the API below is not published in “/inventory”.

Overview

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.

Inventory API

InventoryAPI [application/vnd.com.nsn.cumulocity.inventoryApi+json]

Name Type Occurs Description
self string 1 A URL linking 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).

GET - Representation of the Inventory API resource

Response body: application/vnd.com.nsn.cumulocity.inventoryApi+json

Required role: ROLE_INVENTORY_READ

Example request - Get the Inventory API resource

HEADERS
Authorization {{auth}}
Host {{hostname}}
200 - OK

GET <<url>>/inventory

Example response

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}"
}

Managed object collection

ManagedObjectCollectionAPI [application/vnd.com.nsn.cumulocity.managedObjectCollection+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
managedObjects ManagedObject 0..n List of managed objects, see below.
statistics PagingStatistics 1 Information about paging statistics.
prev string 0..1 A URI linking to a potential previous page of managed objects.
next string 0..1 A URI linking to a potential next page of managed objects.

GET - Representation of a ManagedObjectCollection

Response body: ManagedObjectCollection

Required role: ROLE_INVENTORY_READ

Example request - Get managed objects of a particular type

HEADERS
Authorization {{auth}}
Host {{hostname}}
GET <<url>>/inventory/managedObjects
Accept: application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=...

Example response

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" : "..."}

GET - Representation of a ManagedObjectCollection by query

Response body: ManagedObjectCollection

Required role: ROLE_INVENTORY_READ

Example request - Get managed objects found by query

HEADERS
Authorization {{auth}}
200 - OK

GET <<url>>/inventory/managedObjects?query=<<query language statement>>
Accept: application/vnd.com.nsn.cumulocity.managedObjectCollection+json;ver=...

Example response

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

Query language is applied to all managed objects. Users can query using the query parameter as follows:

Since all of this is happening as part of a URL, all necessary escaping has to be done with URL encoding. Regex features with custom filter queries are not supported.

The following parts explain how an application will handle a query in the parameter query.

Supported query operations:
Supported query functions:
Supported query values:
Supported query properties:
Grouping query operators:
Supported sort operations:

Important: If you query /inventory/managedObjects?type=c8y_Firmware&query=$filter=(name+eq+'Controller 1') the type queryParam is ignored.
Instead url/inventory/managedObjects?query=$filter=(type+eq+c8y_Firmware+and+name+eq+'Controller 1') has to be queried.

Example data

    {
        "_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 response

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

Managed object

Managed Object [application/vnd.com.nsn.cumulocity.managedObject+json]

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 string 1 A URL linking 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 datetime 1 The time when the object has been created. POST only
lastUpdated datetime 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 datetime 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. You need a global role with READ “Inventory” permission to query the managed object “parents”. Pass withParents=true query param to have “parents” included. If you query the managed object withParents=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.

GET - Representation of a managed object

Response body: ManagedObject

Required role: ROLE_INVENTORY_READ

Example request - Get a representation of a specific managed object

HEADERS
Authorization {{auth}}
Host {{hostname}}
200 - OK

GET <<url>>/inventory/managedObjects/<<deviceId>>
Accept: application/vnd.com.nsn.cumulocity.managedObject+json;=ver...

Example response

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.

POST - Create a new ManagedObject

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

Example request - Add a new ManagedObject

HEADERS
Authorization {{auth}}
Host {{hostname}}
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" }
    }

Example response

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.

GET - Supported measurements of a managed object

Example request - Retrieve supported measurements of a managed object

HEADERS
Authorization {{auth}}
Host {{hostname}}
200 - OK

GET <<url>>/inventory/managedObjects/<<deviceId>>/supportedMeasurements

Example response

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.

GET - Supported series of a managed object

Example request - Retrieve supported series of a managed object

HEADERS
Authorization {{auth}}
Host {{hostname}}
200 - OK

GET <<url>>/inventory/managedObjects/<<deviceId>>/supportedSeries

Example response

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.

PUT - Update a managed object

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

Example request - Change the name of a managed object

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"
}

Example response

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

DELETE - Managed object

Request body: N/A

Response message body: N/A

Required role: ROLE_INVENTORY_ADMIN or owner

Example request - Delete a managed object

HEADERS
Authorization {{auth}}
Host {{hostname}}

DELETE <<url>>/inventory/managedObjects/<<deviceId>>

Example response

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.

Managed object reference collection

ManagedObjectReferenceCollection [application/vnd.com.nsn.cumulocity.managedObjectReferenceCollection+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
references ManagedObjectReference 0..n List of managed object references, see below.
statistics PagingStatistics 1 Information about paging statistics.
prev string 0..1 A URI linking to a potential previous page of managed objects.
next string 0..1 A URI linking to a potential next page of managed objects.

GET - Managed object reference collection

Response body: ManagedObjectReferenceCollection

Example request - Get reference collection of a certain managed object

HEADERS
Authorization {{auth}}
Host {{hostname}}

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

Example response

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": "..."
}

POST - Add a managed object reference to the collection

Request body: ManagedObjectReference

Response body: ManagedObjectReference

Required role: ROLE_INVENTORY_ADMIN or parent and child owner

Example request - Add a ManagedObjectReference

HEADERS
Authorization {{auth}}
Host {{hostname}}
Content-Type application/vnd.com.nsn.cumulocity.managedObject+json;ver=…

POST <<url>>/inventory/managedObjects/<<deviceId>>/<<references>>

{
  "managedObject" : { "self" :"<<ManagedObject URL>>" }
}

Example response

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>>" }
    }

Managed object reference

ManagedObjectReference [application/vnd.com.nsn.cumulocity.managedObjectReference+json]

Name Type Occurs Description
self string 1 A URI linking to this resource.
managedObject ManagedObject 1 The ManagedObject being referenced.

GET - Managed object reference

Response body: ManagedObjectReference

Required role: ROLE_INVENTORY_READ

Example request

HEADERS
Authorization {{auth}}
Host {{hostname}}
200 - OK

GET <<url>>/inventory/managedObjects/<<deviceId>>/<<references>>/<<referenceId>>

Example response

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",
    ...
  }
}

DELETE - Managed object reference

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.

Example request - Delete a managed object reference

HEADERS
Authorization {{auth}}
Host {{hostname}}
DELETE /inventory/managedObjects/<<deviceId>>/<<references>>/<<referenceId>>

Example response

HTTP/1.1
204 - NO CONTENT

Notifications

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

Example response

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"
  }
]