Cumulocity Microservice Tutorial Part 2 (Managed Object CRUD)

Introduction

This tutorial will show you how to create, read, update & delete a managed object (CRUD).

Precondition

This tutorial will show you how to handle managed objects.

The tutorial is based on Microservice Tutorial Part 1a & Part 1b.

Source code

Managed Object

A managed object is a representation of a thing like a machine, a company, a person, a book, a bulb, a car etc. The structure of a managed object is not predefined by cumulocity to give you the freedom to represent everything.

Example body for a device with temperature measurement support:

{

    "name": "myDevice", 

    "c8y_IsDevice": {}, 

    "c8y_SupportedMeasurements": ["c8y_TemperatureMeasurement"]

}

The example above contains the parameter ‘c8y_IsDevice’. This parameter marks a managed object as a device. Devices will be handled in C8Y in another way as managed objects without this parameter.

The following dependency will give you the possibility to use this parameter/class:

<dependency>

    <groupId>com.nsn.cumulocity.model</groupId>

    <artifactId>device-capability-model</artifactId>

    <version>1004.6.15</version>

</dependency>

The device capability model will give you access to predefined measurements like temperature, signal strength or humidity.

Create a new (empty) application

See Microservice Tutorial Part 1b for details.

{

  "key": "microservice-part2-key",

  "name": "microservice-part2",

  "type": "MICROSERVICE",

  "requiredRoles": ["ROLE_INVENTORY_ADMIN"],

  "roles": []

}

Role update

  • required roles
  • roles

Required roles are application specific roles. This microservice needs inventory admin rights to be able to create a new managed object and identity admin right to be able to create an external id.

Because I forget to add the ROLE_IDENTITY_ADMIN to my request body I will send an update request to my microservice:

Notice that the defined roles will not exist if you are going to build your microservice resp. *.zip file. You need to define the needed roles within your cumulocity.json Manifest file.

You can ask now for the new bootstrap user:

You need now subscribed to your microservice before you are able to use the microservice.

Create a new managed object

You need the inventory API to handle managed objects e.g. creation. You will find this class within C8Y java client library.


private final InventoryApi inventoryApi;

You need the identity API to handle the external ID e.g. IMEI of a managed object. You will find this class also within the C8Y java client library.
private final IdentityApi identityApi;
A managed object (MO) can have any kind of structure. We will create a simple MO with a name and type:

ManagedObjectRepresentation managedObject = new ManagedObjectRepresentation();

managedObject.setName(managedObjectName);

managedObject.setType(managedObjectType);

You can also mark your MO as a device:
managedObject.set(new IsDevice());
I defined the structure of the MO but I did not create the MO. You need to use the create function of the inventory API to create a new MO based on the predefined MO structure:

ManagedObjectRepresentation createdManagedObject = 
inventoryApi.create(managedObject);

The managed object ID is an internal unique ID. This id is not that user friendly. You can define your need to create your own external (user understandable) external ID by using the identity API:

ExternalIDRepresentation externalIDRepresentation = new ExternalIDRepresentation();

externalIDRepresentation.setType("c8y_Serial");

externalIDRepresentation.setExternalId(managedObjectName);

externalIDRepresentation.setManagedObject(createdManagedObject);

identityApi.create(externalIDRepresentation);

You can now test your function:
http://localhost:8181/create?managedObjectName=WorkhopObject1&managedObjectType=group_temperature_device)
Open your microservice to get the URL for the public cloud:
https://your-tenant-name.cumulocity.com/service/microservice-part2/create?managedObjectName=WorkshopObject1&managedObjectType=group_temperature_devices

Read (get) an existing managed object

URL: http://localhost:8181/read?externalId=WorkshopObject1

We will ask for a managed object based on the given external id. Here you will find the external id of your managed object:

Create an external id representation based on given external id to be able to read the existing managed object:


ExternalIDRepresentation externalIDRepresentation = 
identityApi.getExternalId(new ID("c8y_Serial", externalId));

Get the managed object based on given external id:

Get the managed object based on given external id representation

        ManagedObjectRepresentation managedObjectRepresentation = 
externalIDRepresentation.getManagedObject();

Update an existing managed object

URL: http://localhost:8181/update?externalId=WorkshopObject1&newManagedObjectName=WorkshopObjectNameChange

To update an existing managed object you need to create a new managed object with the new atributes e.g. a new name and override the existing one with the new managed object.

Create a new managed object:

ManagedObjectRepresentation newManagedObjectRepresentation = 
new ManagedObjectRepresentation();

Because I would like to update the name of my existing managed object I will set new name for my new managed object:
newManagedObjectRepresentation.setName(newManagedObjectName);
Create an external id representation based on given external id to be able to read the existing managed object:

ExternalIDRepresentation externalIDRepresentation =
 identityApi.getExternalId(new ID("c8y_Serial", externalId));

Get the existing managed object. You need the internal id to be able to update the correct managed object:

ManagedObjectRepresentation managedObjectRepresentation = 
externalIDRepresentation.getManagedObject();

Update your existing managed object based on given internal id:
newManagedObjectRepresentation.setId(managedObjectRepresentation.getId());

Start update process:
inventoryApi.update(newManagedObjectRepresentation);

Delete an existing managed object

URL: http://localhost:8181/delete?externalId=WorkshopObject1

Get the existing managed object. You need the internal id to be able to delete the correct managed object:

ManagedObjectRepresentation managedObjectRepresentation = 
externalIDRepresentation.getManagedObject();

Get the managed object based on given external id representation:

ManagedObjectRepresentation managedObjectRepresentation = 
externalIDRepresentation.getManagedObject();

Delete the managed object
inventoryApi.delete(managedObjectRepresentation.getId());