This blog post was written by Thomas Kopton: 

Thomas Kopton is a Senior Consultant at VMware PSO based in CEMEA specializing in SDDC Management solutions like vRealize Operations, Log Insight, Network Insight etc.  He has been with VMware since 2016 and worked in the IT industry for over 20 years.

Even if vRealize Operations, together with its rich Management Pack ecosystem, provides a huge number of metrics and properties for a variety of objects, there is sometimes that one requirement which cannot be met because of missing metric or property types for a given object.

Maybe you need to store an internal tracking number with each of your ESXi hosts or maybe you need to add a custom metric reflecting the speed and status of the fans inside your hosts.

In this blog post, I will give you an overview of how to use the vROps REST API to add new custom metrics and properties to existing objects.

How to collect or estimate values for such new metrics or properties (e.g. internal tracking numbers or fan status) is not the objective of this post.

Preparing the Postman environment

Postman client is one of the most popular and easy to use REST API clients and I will be using Postman to showcase all examples in this blog post. If you are not familiar with Postman, I highly recommend the Postman Learning Center to gain some experience with this tool. In an upcoming blog post I will explain how to accomplish the same using vRealize Orchestrator. So, stay tuned.

To be more flexible and quickly change between various vROps instances, Postman has a concept of environments to hold variables such as FQDNs, authentication information or other information used in REST calls. This way it is possible to have all information related to a certain environment in on place. My test environment looks like this:

Once created and selected, these variables can be used in REST calls, here an example of a vROps REST call to retrieve all adapter instances:

In this example I used “Basic Auth” but this will change in the subsequent examples.

Authenticating to vROps

Even if “Basic Auth” is easy to use, VMware recommends using token-based authentication, thus first step is to acquire a token. This will be done using the following API call, description of all available methods can be found on every vROps instance, simply navigate to https://YourvROpsInstance/suite-api/docs/rest/index.html:

Note: to show the samples, your browser needs internet access.

We need to make a POST call with a body containing credentials and as response we will receive the token, which will be used later on without any additional authentication.

Now we have everything we need to work with the vROps REST API:

• Use case (add metric/property to an existing object)
• Token (for the authentication)
• API documentation (to find the right methods)
• Postman (to do the work)

Finding the object ID

If we want to add any information to an object in vROps, we need its internal ID. The easiest way to obtain that ID is to navigate to that particular object in the vROps UI and locating the ID in the URL. Let’s assume we would like to add our custom “Tracking Number” as a new property to an ESXi host. We navigate to that host and copy the ID from the URL. Of course, there is also a REST API call to retrieve this kind of information. GUI-approach first:

Now using the REST API and this example shows you how to user the token (the Authorization is set to “No Auth”) to authorize and how to use request parameters to narrow down your search:

Adding custom property to vROps object

Finally, we can add our shiny new property to the object. Let our property be:

TrackingID = 1337

Which will be always a number, this is important as we are defining the type of the property while pushing the first value. The API call to do this:

As you can see, we can push multiple new properties with multiple values in one invocation of the REST call.

Please notice the difference in the type of the array used for the actual values.

{

  "property-content" : [ {

    "statKey" : "system|availability",

    "timestamps" : [ 1119844280663, 1119844280693, 1119844280713 ],

    "values" : [ "UP", "UP", "DOWN" ],

    "others" : [ ],

    "otherAttributes" : { }

    }, {

    "statKey" : "config|num|processes",

    "timestamps" : [ 1119844280663, 1119844280693, 1119844280713, 1119844280718 ],

    "data" : [ 93.0, 95.0, 97.0, 99.0 ],

    "others" : [ ],

    "otherAttributes" : { }

  } ]

}

“values” stands for string data type and “data” stands for float, never mix up values for one particular property, this will make vROps try to convert between string and float resulting in unpredicted behavior.

So. Let’s push our new property as number. For the timestamp value (Epoch time) and the ObjectID you can use the “Pre-request Script” functionality in Postman:

The property itself id described in the body and if everything worked out you will get 200 as response:

And here we see our new custom property in the GUI:

Adding custom metrics to vROps object

Adding custom metrics is as easy as adding properties. As mentioned, do not mix up strings and numbers in one metric, stick to what you defined with the first invocation of the call.

Let us push two new custom metrics, this time one string and one number:

Fan01Speed = 15.00

Fan01Status = “on”

And this is what you see in the GUI:

In upcoming post, I will demonstrate how to create custom objects using RSEST API via Postman and vRO.