One of the new features in Netcool Omnibus 7.4 is a REST-like interface to the ObjectServer added to support OSLC. This interface allows you to query, update, add, and delete entries from any ObjectServer table. The documentation says that there is at least one IBM product that supports it, but we’re going to start simple and give the straight HTTP interface a try (documentation is available here).

Key Points

In general, there are three ways to specify which event(s) you want to operate (insert/update/delete) on in the ObjectServer:

1. Table Collection Services: allows you to specify any Omnibus table and provide an arbitrary event list filter.
2. Row Element Services + RowSerial: allows you to specify a single row in an ObjectServer table via its RowSerial column. While convenient, you may run into issues in a multi-ObjectServer environment because RowSerial is unique to a specific ObjectServer.
3. Row Element Services + KeyField: same as above, but portable across ObjectServers. See the docs for KeyField syntax.

Prerequisites

1. Obviously, this will only work in Omnibus 7.4!
2. You must modify (at least) three properties in your running NCOMS.props file. See the below for an example. There are many other settings (including enabling SSL), but we’ll ignore them since we’re just looking around. Be sure to restart the ObjectServer after you’ve made the changes!
   • NHttpd.EnableHTTP: TRUE
   • NHttpd.ListeningPort: 8080
   • NRestOS.Enable: TRUE
3. While you can access it from a web browser, you’ll want a client of some sort since the service returns straight JSON.

Web Browser Access

We’re ready to give the interface a test via web browser. I’ve used Chrome here, but others (even wget) will work. The following URL should get you all rows of alerts.status of Severity 5. Note that the “=” must be manually encoded when running from a web browser, which means replacing it with “%3D”.

http://<hostname>:<port>/objectserver/restapi/alerts/status?filter=Severity%3D5

Should give you something like this:

Notice how the output is in a somewhat odd format in that it contains two large sections: one which describes the returned columns and one with the actual data. This makes it more challenging to process. Since this is pure JSON, it’s also not very useful, so let’s develop something that will make it more useful!

.NET Interface

I’ll use C# for this example since it’s what I know as well as being a likely client environment on Windows. The first step is to develop some basic classes that will allow me to deserialize the JSON into strongly-typed C# classes. Fortunately, Visual Studio 2012 Web Tools has a “Paste JSON to Class” menu item which allows us to avoid much tedium (using the excellent JSON.Net library)! Doing so results in a class like this:

GET Request

From here want to develop a simple wrapper class that will let us perform some of the basic operations and return an instance of the “NetcoolEventList” class (or, as we’ll see later, a different class showing us the result of an operation) – something like this that takes a hostname, port, and filter and then returns alerts.status events that match:

This method does the job for us:

The highlighted lines do most of the work of making the request, pulling out the JSON text, and deserializing it into a strongly-typed NetcoolEventList object. At this point we can do whatever we want with it: put it into a custom GUI (perhaps one that already exists in-house), hook it into a different system, etc.

Before the 7.4 HTTP interface this kind of extraction/integration was much more difficult, especially in a Windows environment!

PATCH Request

The HTTP PATCH request is used to update data in the ObjectServer. Like the GET request, it can take a filter expression (when using Table Collection Services). Unlike the GET request, though, making a “generic” PATCH method/object in C# would be much trickier due to the required input format, so we’ll start with a RowSerial example that only updates Severity. The JSON payload will look like this (except that it will only contain Severity!):

Using “Paste JSON to Class” again gives us this:

While it would be nice to “reuse” the class from the GET request example, we cannot because the PATCH request does not have the same field values. If we had tried to use the existing class we’d get a 400 error because of the extra fields in the “EventSet” class such as “osname” and “dbname”. Omnibus is fine, though, with sending extra fields in the “rows” variable! Perhaps it’s an implementation artifact, but for this example it makes our life simpler.

To make the PATCH request we first must fill out an instance of the previous class – something like this. Note that since we are only telling Omnibus to operate on one column (by adding the “Severity” entry to a ColumnDescription) we only need to set the value of “Severity” in the NetcoolEvent entry:

Here’s what setting more than one column value would look like:

Here’s the simple method that performs the PATCH request. Note that we must (at least in .NET) explicitly set the ContentType because any other value will cause Omnibus to return a “415 Unsupported Media Type” error! The highlighted lines convert out filled-out request to the proper JSON format.

A PATCH returns data that is wrapped into the following class. Here is where you can log the results or simply provide feedback:

Conclusions

The Netcool Omnibus 7.4 HTTP interface has the promise to replace all the kludgy things we’ve done over the years with FreeTDS (or things even worse!). Given the ready availability of libraries that can make HTTP requests and parse JSON, migration to an easier-to-maintain and IBM-supported solution is something we should all consider!