Cumulocity Microservice Tutorial Part 9 (Operation handling)

Introduction

This tutorial will show you how to handle operations e.g. event creation, changing the operation status etc.

Precondition

The tutorial is based on Microservice Tutorial Part 1a, Part 1b, Part 2, Part 3, Part 4, Part 5, Part 6, Part 7 & Part 8.

Source code

https://github.com/netperformance/cumulocity-microservice-part9

Microservice preparation

  1. Create a new microservice by using postman
  2. Get the bootstrap credentials by using postman
  3. Configure your application.properties
  4. Configure your cumulocity.json
  5. Subscribe to your microservice

Setup and create a new event

DeviceControlApi is needed for operation handling:

// you need the DeviceControlApi to get access to the operations

private final DeviceControlApi deviceControlApi;
// Managed object representation will give you access to the ID of the managed object

ManagedObjectRepresentation managedObjectRepresentation = resolveManagedObject();

// Operational representation object (setup your operation)

OperationRepresentation operationRepresentation = new OperationRepresentation();

operationRepresentation.setDeviceId(managedObjectRepresentation.getId());

operationRepresentation.set("Restart", "description");

operationRepresentation.set(new Restart());

// create a new operation

deviceControlApi.create(operationRepresentation);

![|624x405](upload://uOzFUlR6BU9zi72griN2mLLdez0.png)

Your managed object (device) needs to be an agent to be able to receive operations:

ManagedObjectRepresentation newManagedObject = new ManagedObjectRepresentation();

newManagedObject.setName("Microservice-Part9");

newManagedObject.setType("Microservice-Part9");

newManagedObject.set(new IsDevice());            

// add agent to managed object because only an agent is able to receive operations

newManagedObject.set(new Agent());

Get all operations

// To get access to event operation representation

OperationCollection operationCollection = deviceControlApi.getOperations();

// To get access to e.g. all operation page

PagedOperationCollectionRepresentation pagedOperationCollectionRepresentation = operationCollection.get();

// Representation of a series of operation elements. Get all pages.

Iterable<OperationRepresentation> iterable = pagedOperationCollectionRepresentation.allPages();

// Usage of google guava to create an operation list 

List<OperationRepresentation> operationRepresentationList = Lists.newArrayList(iterable);

Get an operation by given operation id

// Use GId to transform the given id to a global c8y id

OperationRepresentation operationRepresentation = deviceControlApi.getOperation(GId.asGId(operationId));

Change operation status

OperationRepresentation operationRepresentation = getOperationById(operationId);

if(operationRepresentation!=null) {

     // possible operation status: PENDING -> EXECUTING -> SUCCESSFUL or FAILED  

     // PENDING is the default status after creation of an operation

     operationRepresentation.setStatus(operationStatus);

     deviceControlApi.update(operationRepresentation);
}

Update of the required roles

We need to add the roles “ROLE_EVENT_READ” & “ROLE_EVENT_ADMIN” to the list of the required roles to get access to the events. 

![|624x284](upload://bpDVBdQMuJMjVgEZ7UFxoOjx6JQ.png)

{
  "requiredRoles": [
      "ROLE_INVENTORY_ADMIN",
      "ROLE_IDENTITY_ADMIN",
      "ROLE_DEVICE_CONTROL_ADMIN",
      "ROLE_DEVICE_CONTROL_READ"
  ]
}

List of all tutorials

Cumulocity Microservice Tutorial Part 1a (Hello World)
Cumulocity Microservice Tutorial Part 1b (local testing)
Cumulocity Microservice Tutorial Part 2 (Managed Object CRUD)
Cumulocity Microservice Tutorial Part 3 (Microservice/User-Context, external ID & measurement creation
Cumulocity Microservice Tutorial Part 4 (Read and display data from an external weather API & microservice settings/configuration)
Cumulocity Microservice Tutorial Part 5 (Creation of custom measurements)
Cumulocity Microservice Tutorial Part 6 (send a REST request via SDK to get the latest measurement)
Cumulocity Microservice Tutorial Part 7 (Alarm handling)
Cumulocity Microservice Tutorial Part 8 (Event handling)
Cumulocity Microservice Tutorial Part 9 (Operation handling)