In my previous blog post “Adding Custom Metrics and Properties to vRealize Operations Objects with the REST API” I have described how to add additional metrics and properties to existing objects in vRealize Operations using the REST API and Postman.
But what if you would like to use the outstanding vRealize Operations engine to manage and visualize objects which cannot be collected using the rich Management Pack ecosystem?
Let’s imagine you have a cool Smart Home system and you would like to get it integrated into your vRealize Operations. You would like to have all the various elements as objects in vRealize Operations to push metrics and properties to those objects.
In this post I will show you how to create your own custom environments in vRealize Operations using REST and vRealize Orchestrator.
Of course, this is just an example and the environment, and the corresponding inputs are “virtual”. The used vRealize Orchestrator workflows are examples and there are different ways to achieve the same outcome.
The vRealize Orchestrator workflows, actions etc. related to this post can be found here:
Adding custom objects to vRealize Operations with the REST API and vRealize Orchestrator workflows
The REST API call
There are several REST API calls available to create new objects in vRealize Operations. In this example we will use the method “createResourceUsingAdapterKind”:
POST /api/resources/adapterkinds/{adapterKindKey}
A sample URL body of the call can be as complex as in the official documentation or as easy as this one:
https://VROPS-FQDN/suite-api/api/resources/adapterkinds/MySmartHome
{
"description": "My new entry",
"creationTime": null,
"resourceKey": {
"name": "Living Room",
"adapterKindKey": "MyHouse",
"resourceKindKey": "Lightning"
},
"resourceStatusStates": [],
"dtEnabled": true,
"monitoringInterval": 5
}
This Entry will initially create our OPENAPI adapter instance for the new custom environment using the REST API. This environment will reflect a Smart Home installation containing various devices. This call will create a lightning device located in the living room. How to execute that call using vRealize Orchestrator will be described later on.
Input data
If we are going to use automation to create our objects it would be not very sophisticated to enter every value manually. Therefor as first step we design and create a JSON file describing the model of our Smart Home. This is an example how a very simple model may look like. The included properties and metrics will play a role in some subsequent blog posts.
{"MySmartHome": {
"Climate": [
{"Name": "Living Room", "Properties": [
{ "Manufacturer" : "CompanyA", "FWVersion" : "2.01" }
], "Metrics": [
{ "Temperatur" : "21", "Humidity" : "40", "BateryStatus" : "94%"}
]},
{"Name": "Kitchen", "Properties": [
{ "Manufacturer" : "CompanyA", "FWVersion" : "1.90" }
], "Metrics": [
{ "Temperatur" : "13", "Humidity" : "87", "BateryStatus" : "10%"}
]},
{"Name": "Bedroom", "Properties": [
{ "Manufacturer" : "CompanyA", "FWVersion" : "2.1" }
], "Metrics": [
{ "Temperatur" : "16", "Humidity" : "35", "BateryStatus" : "74%"}
]}
],
"Door": [
{"Name": "Front", "Properties": [
{ "Manufacturer" : "CompanyA", "FWVersion" : "1.95" }
], "Metrics": [
{ "Status" : "OPEN"}
]},
{"Name": "Garden", "Properties": [
{ "Manufacturer" : "CompanyA", "FWVersion" : "2.1" }
], "Metrics": [
{ "Status" : "CLOSED"}
]}
],
"Lightning": [
{"Name": "Living Room", "Properties": [
{ "Manufacturer" : "CompanyB", "FWVersion" : "0.91" }
], "Metrics": [
{ "Status" : "ON", "Level" : "100%", "BateryStatus" : "76%"}
]},
{"Name": "Kitchen", "Properties": [
{ "Manufacturer" : "CompanyC", "FWVersion" : "1.00" }
], "Metrics": [
{ "Status" : "ON", "Level" : "75%", "BateryStatus" : "45%"}
]},
{"Name": "Bedroom", "Properties": [
{ "Manufacturer" : "CompanyA", "FWVersion" : "2.90" }
], "Metrics": [
{ "Status" : "OFF", "Level" : "0%", "BateryStatus" : "14%"}
]}
]
}
}
Code 1: SmartHome Data as JSON
In this JSON example our Smart Home consists of three types of devices: Climate, Door and Lightning.
The instances of those devices can be located in different rooms and have various properties and metrics.
vRealize Orchestrator Preparation – Resource Element
To consume our JSON file in a vRealize Orchestrator workflow we need to import that file as “Resource Element”.
After importing the JSON file into vRealize Orchestrator it can be used as an attribute in any vRealize Orchestrator workflow.
vRealize Orchestrator Preparation – Configuration Element
Acquiring a valid vRealize Operations authentication token is one part of our workflow. To make the process as automated as possible, we will store frequently used values in a vRealize Orchestrator “Configuration Element”. Such values are for example user credentials and token related information.
A vRealize Orchestrator configuration element is a kind of dictionary data structure storing key:value pairs for ease of use in vRealize Orchestrator workflows.
vRealize Orchestrator Preparation – REST Endpoint and Operations
The last pre-requisite is a working REST endpoint including REST operations configured in our vRealize Orchestrator instance. vRealize Orchestrator provides appropriate workflows in the out-of-the-box library to add new REST hosts and operations offered by those hosts. The following figure shows the location of the workflows which can be used to configure a REST API provider.
Basically, we will use following REST calls:
POST /api/auth/token/acquire
POST /api/resources/adapterkinds/{adapterKindKey}
For details, please check the vRealize Operations REST API documentation provided by your vRealize Operations instance at:
https://$VROPSFQDN/suite-api/docs/rest/index.html
Authenticating to vRealize Operations using vRealize Orchestrator
As described in my post “Adding Custom Metrics and Properties to vRealize Operations Objects with the REST API” we will use the token based authentication in this example, too. This is how the AquireToken workflow looks like:
In the first step we are creating the JSON body:
jsonBody = {
"username": "",
"authSource": "",
"password": "",
"others": [],
"otherAttributes": {}
};
var userName = vropsConfig.getAttributeWithKey("userName");
var userPassword = vropsConfig.getAttributeWithKey("userPassword");
var authSource = vropsConfig.getAttributeWithKey("authSource");
jsonBody.username = userName.value;
jsonBody.password = userPassword.value;
jsonBody.authSource = authSource.value;
Code 2: createJsonBody Snippet
Scripting element callREST executes the REST call:
requestBody = JSON.stringify(jsonBody);
request = aquireToken.createRequest(null, requestBody);
request.contentType = "application/json";
request.setHeader("accept", "application/json");
response = request.execute();
jsonObject = JSON.parse(response.contentAsString);
vropsToken = jsonObject.token;
vropsTokenValidity = jsonObject.validity;
Code 3: callREST Snippet
Third element saves the received token, including the expiration information, in the configuration element:
vropsConfig.setAttributeWithKey("token",vropsToken);
vropsConfig.setAttributeWithKey("tokenValidity",vropsTokenValidity);
Code 4: saveToken Snippet
Creating Custom Objects
The actual job is being done in the CreateCustomObjects workflow:
After some URL-encoding for inputs containing e.g. white spaces, we collect information about the new objects using the JSON file (newObjecstInfo), the code snippet here has been shortened and includes only one object category. All workflows can be .
template = newObjectsJSONFile.getContentAsMimeAttachment();
jsonObject = JSON.parse(template.content);
var objects1 = jsonObject.SmartHome["Climate"];
…
…
newResources1 = new Array();
for (object1 in objects1) {
newResources1.push(objects1[object1].Name);
}
numberResource1 = newResources1.length;
Code 5: newObjectsinfo Snippet
What we are doing here is basically creating an array of strings containing the names of our new custom objects. At this point the code needs to be adopted to the model defined in the JSON file to parse the data correctly.
The next steps are fairly simple, we check the validity of the token which we saved in a configuration element and acquire a new token in case our token is valid for less than 10 minutes:
var vropsTokenValidity = vropsConfig.getAttributeWithKey("tokenValidity");
if (vropsTokenValidity.value != null) {
var dateNow = new Date();
var diff = vropsTokenValidity.value - dateNow.getTime();
tokenRemainigVaidity = diff / 1000 / 60;
} else {
tokenRemainigVaidity = 0;
}
Code 6: checkToken Snippet
The following scripting elements take care of looping through the arrays of strings to create all object one by one.
The main part related to creating new vR Ops objects consists of creating the JSON body:
jsonBody = {
"description": "New SmartHome entry",
"creationTime": null,
"resourceKey": {
"name": "",
"adapterKindKey": "",
"resourceKindKey": ""
},
"resourceStatusStates": [],
"dtEnabled": true,
"monitoringInterval": 5
};
if (creatingResource1) {
jsonBody.resourceKey.name = newResources1[numberResource1 - 1];
jsonBody.resourceKey.adapterKindKey = adapterKindKey;
jsonBody.resourceKey.resourceKindKey = resourceKind1;
numberResource1--;
}
Code 7: createJSONBody Snippet
The very last step is to execute the REST API call to create a custom object:
var params = [encodedAdapterKind];
var token = vropsConfig.getAttributeWithKey("token").value;
var request = createResourceCall.createRequest(params, JSON.stringify(jsonBody));
request.contentType = "application/json";
request.setHeader("accept","application/json");
request.setHeader("Authorization","vRealizeOpsToken " + token);
var response = request.execute();
if(response.statusCode >= 400) {
System.log(response.contentAsString);
throw "HTTPError: status code: " + response.statusCode;
}
Code 8: callREST Snippet
If everything worked out as expected, we will see our new object types and instances of those types in vRealize Operations.
After importing the vRealize Orchestrator package you will need to configure the REST operation according to your environment:
Our Smart Home in vRealize Operations
The Environment view in vRealize Operations 7.0 including our custom objects:
In some subsequent posts I am going to explain how to push metrics and properties to such custom objects.
Some other interesting object types, which may become relevant in the future, could help to boldly go where no one has gone before are described in my corresponding private blog post:
Adding custom objects to vRealize Operations with the REST API and vRealize Orchestrator workflows
Happy coding…
